Skip to main content
The Usage Limit Policy restricts how many times your agent can execute a specific action. Simple but effective rate limiting.

​
When to Use Usage Limit

Subscription agents (12 payments per year)
Trial periods (limited actions)
Preventing runaway agents
Metered access models
Safety cap for any automation

​
Basic Usage

const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 5n
});

// 5 transfers per session
const actions = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [usagePolicy]
  }
});

​
Agent Examples

​
Subscription Agent (12/Year)

// Chargeable on day one of the month
const dayOneTimeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter: ..., // unix-timestamp Eg: 1-1-2026 00:00:00 in unix timestamp
  validUntil: ...  // unix-timestamp Eg: 1-1-2026 23:59:59 in unix timestamp
});

// Used only once per month
const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 1n
});

const monthOnePaymentAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [dayOneTimeframePolicy, usagePolicy]
  }
});

// 10 similar actions for 10 months

const monthTwelvePaymentAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [dayOneTimeframePolicy, usagePolicy]
  }
});

// 12 actions which can be executed only once per month on day one for a year.
// Get a session quote and execute it to enable a permission for subscriptions

​
Trial Agent (10 Actions)

const SEVEN_DAYS = 7 * 24 * 60 * 60;

const now = Math.floor(Date.now() / 1000)
const validAfter = now
const validUntil = now + SEVEN_DAYS

// Only 7 days trail
const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

// Only 100 trades in trail mode
const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 100n
});

const monthOnePaymentAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [timeframePolicy, usagePolicy]
  }
});

​
Rebalancing Agent (Quarterly)

// Chargeable in every quarter
const quarterlyTimeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter: ..., // unix-timestamp Eg: 1-1-2026 in unix timestamp
  validUntil: ...  // unix-timestamp Eg: 31-3-2026 in unix timestamp
});

// Used only once per quarter
const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 1n
});

const quarterOneRebalanceAction = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453, 10],
    contractAddress: REBALANCER,
    functionSignature: '0x...',
    policies: [quarterlyTimeframePolicy, usagePolicy]
  }
});

// 2 similar actions for 2 quarters

const quarterFourRebalanceAction = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453, 10],
    contractAddress: REBALANCER,
    functionSignature: '0x...',
    policies: [quarterlyTimeframePolicy, usagePolicy]
  }
});

// 4 actions which can be executed only once per quarter for a year.
// Get a session quote and execute it to enable a permissions for rebalancer

​
Gaming Agent (Action Budget)

// 100 attacks per session
const attackUsagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 100n
});

const [attackAction] = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453],
    contractAddress: GAME,
    functionSignature: toFunctionSelector("attack(uint256)"),
    policies: [attackUsagePolicy]
  }
});

// 50 heals per session
const healUsagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 50n
});

const [healAction] = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453],
    contractAddress: GAME,
    functionSignature: toFunctionSelector("heal()"),
    policies: [healUsagePolicy]
  }
});

// 5 claim rewards per session
const claimRewardsUsagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 5n
});

const [claimAction] = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453],
    contractAddress: GAME,
    functionSignature: toFunctionSelector("claimRewards()"),
    policies: [claimRewardsUsagePolicy]
  }
});

​
Metered Access

Sell action packs: 
const USAGE_TIERS = {
  starter: 1000n,
  pro: 10_000n,
};

const starterUsagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: USAGE_TIERS["starter"]
});

const proUsagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: USAGE_TIERS["pro"]
});

​
Combining with Other Policies

​
Usage + Time (Most Common)

const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 5n
});

const actions = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [timeframePolicy, usagePolicy]
  }
});

​
Usage + Universal Action

const universalPolicy = mcNexus.buildActionPolicy({
  type: "universal",
  rules: [
    {
      condition: "equal",
      calldataOffset: calldataArgument(2),
      comparisonValue: parseUnits("10", 6)
    }
  ],
  // Configure spending limit for native token
  valueLimitPerUse: 1n
});

const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 5n
});

const actions = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [universalPolicy, usagePolicy]
  }
});
Usage renewal: When usage limits are reached, the onchain actions will be reverted. Need to enable a fresh session for the user.

​
Limits

  • usageLimit is a bigint
  • Maximum value: 2^256 - 1 (effectively unlimited)
  • Counter decrements atomically per successful execution
  • Failed executions don’t count against limit