> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Limit Policy

> Cap the total number of actions your agent can perform

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

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

## Basic Usage

```typescript theme={null}
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)

```typescript theme={null}
// 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)

```typescript theme={null}
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)

```typescript theme={null}
// 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)

```typescript theme={null}
// 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:

```typescript theme={null}
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)

```typescript theme={null}
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

```typescript theme={null}
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]
  }
});
```

<Info>
  Usage renewal: When usage limits are reached, the onchain actions will be reverted. Need to enable a fresh session for the user.
</Info>

## 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