IPcl.globalPeriodicVolume
globalPeriodicVolume(address user, string asset, uint64 resetPeriodSeconds, bool resolveAgentOwners) external view returns (PeriodicVolume memory) Reads the running periodic-volume counter for user under any PERIODIC_VOLUME_POLICY in the global config that matches the given asset and resetPeriodSeconds. Returns the currently accumulated amount, the configured max, the period length, and the unix timestamp at which the current window ends. Use this to preview whether an upcoming transfer would trip a global periodic cap before submitting the transaction.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
user | address | ✓ | The address whose running volume you want to read. Typically the intended msg.sender of the upcoming transaction. |
asset | string | ✓ | The denom string the policy is keyed on (for OKRW this is "aokrw", the base denom). |
resetPeriodSeconds | uint64 | ✓ | The reset-period length that identifies which PERIODIC_VOLUME_POLICY limit to read (e.g. 86400 for a 24-hour window, 2592000 for 30 days). Must match the resetPeriodSeconds configured on the target policy. |
resolveAgentOwners | bool | ✓ | If true and user is an agent wallet, the running counter is aggregated across the agent's owner(s) rather than read only from the agent address itself. If false, only the literal user address is looked up. |
Returns
PeriodicVolume Struct { uint256 amount, uint256 maxAmount, uint64 resetPeriodSeconds, uint64 resetAt }. amount is the running total inside the current window; maxAmount is the policy limit; resetAt is the unix timestamp at which the window rolls over.
Examples
Preview daily OKRW volume before a transfer
Reads the 24-hour global OKRW volume counter for user. resolveAgentOwners = false here because user is an EOA. Headroom is compared against a realistic transfer cap (10,000,000 OKRW = 1e7 × 10^18 aokrw).
import { createPublicClient, http, parseAbi } from "viem";
const PCL = "0x1000000000000000000000000000000000000005";
const pclAbi = parseAbi([
"function globalPeriodicVolume(address user, string asset, uint64 resetPeriodSeconds, bool resolveAgentOwners) view returns ((uint256 amount, uint256 maxAmount, uint64 resetPeriodSeconds, uint64 resetAt))",
]);
const client = createPublicClient({ transport: http("https://rpc-testnet.maroo.io") });
const user = "0x1111111111111111111111111111111111111111"; // replace before production
const v = await client.readContract({
address: PCL,
abi: pclAbi,
functionName: "globalPeriodicVolume",
args: [user, "aokrw", 86_400n, false],
});
const headroom = v.maxAmount - v.amount; // in aokrw
console.log(`used ${v.amount} / ${v.maxAmount} aokrw, resets at ${v.resetAt}`);
if (headroom < 10_000_000n * 10n ** 18n) {
// < 10,000,000 OKRW headroom — this transfer will trip the cap
}Aggregate an agent wallet's counter to its owner
Passing resolveAgentOwners = true matches how the policy evaluator scores an agent wallet — the counter is bucketed under the agent's owner(s), not the agent address itself. Use this when previewing behavior for an agent-controlled transfer.
const agentWallet = "0x2222222222222222222222222222222222222222"; // replace before production
const v = await client.readContract({
address: PCL,
abi: pclAbi,
functionName: "globalPeriodicVolume",
args: [agentWallet, "aokrw", 86_400n, true],
});
// v.amount now reflects the aggregated 24h volume across the agent's owner(s),
// which is what a PERIODIC_VOLUME_POLICY configured with agent-owner resolution
// evaluates at enforcement time.
console.log(v);