How-to: Set up a Permit2 allowance

Grant the Permit2 contract an allowance on the buyer’s USDC so Facilitator Service can settle usage-based payments

Usage-based upto payments move USDC through the Permit2 contract, so the buyer’s USDC allowance for Permit2 must cover each payment. There are two ways to grant the allowance:

• Onchain approval: one approve transaction grants Permit2 spending power indefinitely. Best when the buyer transacts repeatedly and can hold the gas asset.
• Gasless permit: the buyer signs an EIP-2612 permit for each payment, which you, as the seller, attach to the Facilitator Service call. Best when the buyer can’t hold the gas asset or integrates purely offchain, since Circle pays settlement gas when the permit is applied.

Onchain approval

Prerequisites

Before you begin, ensure that you’ve:

• Installed Node.js v22.6+
• Installed viem
• Funded the buyer wallet with Arc testnet USDC from the Circle Faucet

Grant the allowance onchain

Send one approve from the buyer, with Permit2 as the spender. The example targets Arc testnet.

approve-permit2.ts

import { createWalletClient, http, erc20Abi, maxUint256 } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { arcTestnet } from "viem/chains";

const buyer = privateKeyToAccount(
  process.env.BUYER_PRIVATE_KEY as `0x${string}`,
);
const client = createWalletClient({
  account: buyer,
  chain: arcTestnet,
  transport: http(),
});

const hash: `0x${string}` = await client.writeContract({
  address: "0x3600000000000000000000000000000000000000", // USDC on Arc testnet
  abi: erc20Abi,
  functionName: "approve",
  args: ["0x000000000022D473030F116dDEE9F6B43aC78BA3", maxUint256], // Permit2
});

This example approves maxUint256, which lets Permit2 move any amount of the buyer’s USDC indefinitely. For production, consider approving only what each payment needs and refreshing allowances periodically.

Gasless permit

Prerequisites

Before you begin, ensure that you’ve:

• Installed Node.js v22.6+
• Installed viem
• Funded the buyer wallet with Arc testnet USDC from the Circle Faucet

Grant the allowance with a gasless permit

Have the buyer sign the permit under the USDC contract’s own EIP-712 domain, not the Permit2 domain. Use the name and version that USDC reports on that network: USDC on Arc and USD Coin on Base and Polygon PoS, with version 2.

sign-permit.ts

import { createPublicClient, http, parseAbi } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { arcTestnet } from "viem/chains";

const usdc = "0x3600000000000000000000000000000000000000";
const permit2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
const buyer = privateKeyToAccount(
  process.env.BUYER_PRIVATE_KEY as `0x${string}`,
);
const publicClient = createPublicClient({
  chain: arcTestnet,
  transport: http(),
});

const nonce: bigint = await publicClient.readContract({
  address: usdc,
  abi: parseAbi(["function nonces(address owner) view returns (uint256)"]),
  functionName: "nonces",
  args: [buyer.address],
});
const deadline: bigint = BigInt(Math.floor(Date.now() / 1000) + 900);
const value: bigint = 5000000n; // allowance for Permit2 in atomic USDC units (equals permit2Authorization.permitted.amount)

const signature: `0x${string}` = await buyer.signTypedData({
  domain: {
    name: "USDC",
    version: "2",
    chainId: 5042002,
    verifyingContract: usdc,
  },
  types: {
    Permit: [
      { name: "owner", type: "address" },
      { name: "spender", type: "address" },
      { name: "value", type: "uint256" },
      { name: "nonce", type: "uint256" },
      { name: "deadline", type: "uint256" },
    ],
  },
  primaryType: "Permit",
  message: { owner: buyer.address, spender: permit2, value, nonce, deadline },
});

When you submit the settlement request, include the signed permit as the eip2612GasSponsoring extension on /settle. The Accept x402 payments quickstart shows a complete settlement call with this extension in place.

If a permit is present but invalid, Facilitator Service returns one of the permit reasons on /verify or /settle.