How-to: Configure rate limits and transfer caps

The TokenManager applies two transfer controls per token: a rate limit over a fixed epoch window, and a per-transaction maximum transfer amount. The rate limit tracks inbound and outbound flow; the max transfer amount applies to outbound transfers. Both controls live on the TokenManager for the token. Use this guide to configure them. Attestation does not bypass destination TokenManager checks. An inbound transfer can still be rejected by the rate limit or blocked while the token is paused.

Custom token issuers must configure rate limits and a max transfer amount before allowing public transfers. A rate limit configured as 0 blocks inbound and outbound flows. Every crossChainTransfer call reverts until you set a non-zero limit.

How the throttles behave

Rate limit: Caps the absolute net flow (|flowIn - flowOut|) within each fixed epoch window. It applies to inbound and outbound flow. The default window length is six hours. Setting the rate limit to 0 blocks both directions. After configuration, always verify the limit is non-zero before your first crossChainTransfer; a common mistake is configuring with rateLimit: 0 and skipping this guide.
Max transfer amount: Caps the size of a single outbound transfer transaction. Applies on top of the rate limit to prevent oversize single transfers regardless of the headroom remaining in the rate-limit window. Setting maxTransferAmount to 0 blocks all outbound transfers. Use type(uint256).max (or 2n ** 256n - 1n in TypeScript) to disable the per-transfer cap.

For example, with a rate limit of 1,000,000 over six hours:

A user transfers 300,000 out and 100,000 in during the window. Net outbound consumed is 200,000. Remaining headroom: 800,000.
A second user attempts to transfer 900,000 out in the same window. The transfer reverts because net outbound would exceed 1,000,000.

Prerequisites

Before you begin, ensure that you’ve:

Obtained the tokenId for the token you want to configure.
Confirmed the wallet you’ll use holds the operator role for that token’s TokenManager.

Steps

Discover the TokenManager address

Read the local TokenManager address from the CrossChainTokenService:

TypeScript

const serviceAbi = [
  {
    name: "resolveTokenManager",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "tokenId", type: "bytes32" }],
    outputs: [{ name: "tokenManager", type: "address" }],
  },
] as const;

const tokenManager: `0x${string}` = await publicClient.readContract({
  address: serviceAddress,
  abi: serviceAbi,
  functionName: "resolveTokenManager",
  args: [tokenId],
});

Set the rate limit

Call setRateLimit with the maximum absolute net flow (|flowIn - flowOut|) per window in the token’s smallest unit.

TypeScript

const rateLimitAbi = [
  {
    name: "setRateLimit",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [{ name: "rateLimit", type: "uint256" }],
    outputs: [],
  },
] as const;

await walletClient.writeContract({
  address: tokenManager,
  abi: rateLimitAbi,
  functionName: "setRateLimit",
  args: [5_000_000n * 10n ** 18n],
});

Set the max transfer amount

Call setMaxTransferAmount to cap the size of a single outbound transfer.

TypeScript

const maxTransferAmountAbi = [
  {
    name: "setMaxTransferAmount",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [{ name: "maxTransferAmount", type: "uint256" }],
    outputs: [],
  },
] as const;

await walletClient.writeContract({
  address: tokenManager,
  abi: maxTransferAmountAbi,
  functionName: "setMaxTransferAmount",
  args: [500_000n * 10n ** 18n],
});

Set the rate-limit window (optional)

The default window is six hours. To change it, call setRateLimitWindow with the new window length in seconds.

TypeScript

const rateLimitWindowAbi = [
  {
    name: "setRateLimitWindow",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [{ name: "window", type: "uint256" }],
    outputs: [],
  },
] as const;

await walletClient.writeContract({
  address: tokenManager,
  abi: rateLimitWindowAbi,
  functionName: "setRateLimitWindow",
  args: [3600n], // 1 hour
});

Verify the configuration

Read the current values from the TokenManager and compare them with the values you selected for the preceding configuration steps. If you skipped the optional window step, compare rateLimitWindow with the six-hour default. If rateLimit is still 0, transfers revert until you call setRateLimit with a non-zero amount (in the token’s smallest unit).

TypeScript

const tokenManagerReadAbi = [
  {
    name: "rateLimit",
    type: "function",
    stateMutability: "view",
    inputs: [],
    outputs: [{ name: "", type: "uint256" }],
  },
  {
    name: "maxTransferAmount",
    type: "function",
    stateMutability: "view",
    inputs: [],
    outputs: [{ name: "", type: "uint256" }],
  },
  {
    name: "rateLimitWindow",
    type: "function",
    stateMutability: "view",
    inputs: [],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

const [rateLimit, maxTransferAmount, rateLimitWindow] = await Promise.all([
  publicClient.readContract({
    address: tokenManager,
    abi: tokenManagerReadAbi,
    functionName: "rateLimit",
  }),
  publicClient.readContract({
    address: tokenManager,
    abi: tokenManagerReadAbi,
    functionName: "maxTransferAmount",
  }),
  publicClient.readContract({
    address: tokenManager,
    abi: tokenManagerReadAbi,
    functionName: "rateLimitWindow",
  }),
]);

console.log({ rateLimit, maxTransferAmount, rateLimitWindow });
if (rateLimit === 0n) {
  throw new Error("rateLimit is 0: token flows are blocked");
}

CCTP for USDC

CCTP for non-USDC

Gateway

How-to: Configure rate limits and transfer caps

How the throttles behave

Prerequisites

Steps

​How the throttles behave

​Prerequisites

​Steps

How the throttles behave

Prerequisites

Steps