Quickstart: Pay for resources with nanopayments

In this quickstart, you will deposit USDC into a Gateway Wallet, pay for an x402-protected resource without gas fees, and check your balance. By the end, you’ll have a working client that can make gasless payments to any x402-compatible API that supports Circle Gateway.

Circle Wallets
Self-managed

Use @circle-fin/developer-controlled-wallets to fund an Arc Testnet EOA and @circle-fin/x402-batching to pay for an x402-protected resource. Smart contract account (SCA) wallets are not supported for nanopayments because Gateway verifies the EIP-3009 authorization with ecrecover. For more information, see Account types.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22.6+.
Created a Circle Console account.
Created an API key in the Circle Console.
Generated and registered an Entity Secret.
Created an EOA developer-controlled wallet on Arc Testnet.

Complete the linked quickstarts before continuing. This path starts once your credentials and Arc Testnet wallet address are available. The wallet address is public configuration, so you will add it directly to pay.ts.

Step 1. Set up your project

1.1. Create the project and install dependencies

mkdir nanopayments-circle-wallets
cd nanopayments-circle-wallets
npm init -y
npm pkg set type=module
npm pkg set scripts.pay="node --env-file=.env pay.ts"
npm install @circle-fin/developer-controlled-wallets @circle-fin/x402-batching
npm install --save-dev typescript @types/node

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file:

npx tsc --init

Then, update the tsconfig.json file:

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

1.3. Set environment variables

Open .env in your editor and add:

.env

CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET

CIRCLE_API_KEY is your Circle API key.
CIRCLE_ENTITY_SECRET is your Circle entity secret.

Open .env in your editor rather than writing values with shell commands, and add .env to your .gitignore. This prevents credentials from leaking into your shell history or version control.

Step 2. Initialize the Circle Wallets client

Create pay.ts and replace the wallet address placeholder with the address from the developer-controlled wallet quickstart. Copy this block into pay.ts first.

pay.ts

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
import {
  BatchEvmScheme,
  CHAIN_CONFIGS,
} from "@circle-fin/x402-batching/client";

function stringifyTypedData(value: unknown): string {
  return JSON.stringify(value, (_, currentValue) =>
    typeof currentValue === "bigint" ? currentValue.toString() : currentValue,
  );
}

const apiKey = process.env.CIRCLE_API_KEY;
const entitySecret = process.env.CIRCLE_ENTITY_SECRET;
const walletAddress = "0xYOUR_ARC_TESTNET_WALLET_ADDRESS" as `0x${string}`;

if (!apiKey || !entitySecret) {
  throw new Error(
    "CIRCLE_API_KEY and CIRCLE_ENTITY_SECRET are required in .env.",
  );
}

if (walletAddress === "0xYOUR_ARC_TESTNET_WALLET_ADDRESS") {
  throw new Error(
    "Replace walletAddress with your Arc Testnet wallet address.",
  );
}

const circleClient = initiateDeveloperControlledWalletsClient({
  apiKey,
  entitySecret,
});

const chain = CHAIN_CONFIGS.arcTestnet;
const depositAmount = "1";
// 1 USDC = 1_000_000 base units (6 decimals)
const depositAmountBaseUnits = "1000000";
const gatewayApi = "https://gateway-api-testnet.circle.com";
const protectedUrl = "http://localhost:3000/premium-data";

const batchScheme = new BatchEvmScheme({
  address: walletAddress,
  signTypedData: async (params) => {
    const typedData = {
      domain: {
        ...params.domain,
        chainId: params.domain.chainId.toString(),
      },
      primaryType: params.primaryType,
      types: {
        EIP712Domain: [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
          { name: "chainId", type: "uint256" },
          { name: "verifyingContract", type: "address" },
        ],
        ...params.types,
      },
      message: params.message,
    };

    const response = await circleClient.signTypedData({
      walletAddress,
      blockchain: "ARC-TESTNET",
      data: stringifyTypedData(typedData),
    });

    const signature = response.data?.signature;
    if (!signature) {
      throw new Error("Circle Wallets returned no signature.");
    }
    return (
      signature.startsWith("0x") ? signature : `0x${signature}`
    ) as `0x${string}`;
  },
});

BatchEvmScheme builds the EIP-3009 payment authorization. The callback normalizes its viem-style typed data for Circle Wallets by adding the explicit EIP712Domain type, serializing chainId, and converting the response to a 0x-prefixed signature. The developer-controlled wallet signs the authorization without exposing a private key to this script.

Step 3. Fund the wallet

Use the Circle Faucet to send testnet USDC to the Arc Testnet wallet address from the wallet quickstart. Arc Testnet uses USDC as its native gas token, so the faucet funds both the USDC deposit and the transaction fees.

Step 4. Deposit USDC into Gateway

Prefer a shorter deposit flow? Use Unified Balance Kit with the Circle Wallets adapter. See Deposit and spend a Unified Balance (Circle Wallets) for Arc Testnet.

Before making a nanopayment, the wallet needs USDC in its Gateway balance. The following function:

Checks the current Gateway balance.
Approves the Gateway Wallet contract to spend USDC.
Deposits USDC into Gateway.
Waits until the deposited balance is available.

Add these functions to pay.ts. They are standalone declarations, so copy them as-is below the initialization code.

pay.ts

async function ensureGatewayBalance(): Promise<void> {
  let gatewayBalance = await getGatewayBalance();

  if (gatewayBalance >= Number(depositAmount)) {
    console.log(`Gateway balance: ${gatewayBalance} USDC`);
    return;
  }

  console.log(`Approving ${depositAmount} USDC for Gateway...`);
  const approval = await circleClient.createContractExecutionTransaction({
    walletAddress,
    blockchain: "ARC-TESTNET",
    contractAddress: chain.usdc,
    abiFunctionSignature: "approve(address,uint256)",
    abiParameters: [chain.gatewayWallet, depositAmountBaseUnits],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  const approvalId = approval.data?.id;
  if (!approvalId) {
    throw new Error("USDC approval was not created.");
  }
  await waitForCircleTransaction(approvalId);

  console.log(`Depositing ${depositAmount} USDC into Gateway...`);
  const deposit = await circleClient.createContractExecutionTransaction({
    walletAddress,
    blockchain: "ARC-TESTNET",
    contractAddress: chain.gatewayWallet,
    abiFunctionSignature: "deposit(address,uint256)",
    abiParameters: [chain.usdc, depositAmountBaseUnits],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  const depositId = deposit.data?.id;
  if (!depositId) {
    throw new Error("Gateway deposit was not created.");
  }
  await waitForCircleTransaction(depositId);

  console.log("Waiting for the Gateway balance to become available...");
  do {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    gatewayBalance = await getGatewayBalance();
  } while (gatewayBalance < Number(depositAmount));

  console.log(`Gateway balance: ${gatewayBalance} USDC`);
}

async function getGatewayBalance(): Promise<number> {
  const response = await fetch(`${gatewayApi}/v1/balances`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      token: "USDC",
      sources: [{ domain: 26, depositor: walletAddress }],
    }),
  });

  if (!response.ok) {
    throw new Error(
      `Gateway balance request failed: ${response.status} ${await response.text()}`,
    );
  }

  const result = (await response.json()) as {
    balances: Array<{ domain: number; balance: string }>;
  };

  return Number(
    result.balances.find(({ domain }) => domain === 26)?.balance ?? "0",
  );
}

async function waitForCircleTransaction(transactionId: string): Promise<void> {
  const terminalStates = new Set([
    "COMPLETE",
    "CONFIRMED",
    "FAILED",
    "DENIED",
    "CANCELLED",
  ]);

  while (true) {
    const response = await circleClient.getTransaction({ id: transactionId });
    const state = response.data?.transaction?.state;

    if (state && terminalStates.has(state)) {
      if (state !== "COMPLETE" && state !== "CONFIRMED") {
        throw new Error(`Circle Wallet transaction ended in state: ${state}`);
      }
      return;
    }

    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

Step 5. Pay for a resource

The first request to an x402-protected endpoint returns 402 Payment Required and a PAYMENT-REQUIRED header. Sellers often advertise Gateway options for many blockchains. Select the Arc Testnet GatewayWalletBatched option so the EIP-712 chainId matches the Circle Wallets ARC-TESTNET signer, then create the authorization and retry with a PAYMENT-SIGNATURE that includes the chosen option and the resource metadata from the 402 response.Add payForResource to pay.ts:

pay.ts

async function payForResource(url: string): Promise<unknown> {
  const unpaidResponse = await fetch(url);
  if (unpaidResponse.status !== 402) {
    throw new Error(
      `Expected 402 Payment Required, received ${unpaidResponse.status}.`,
    );
  }

  const paymentRequiredHeader = unpaidResponse.headers.get("PAYMENT-REQUIRED");
  if (!paymentRequiredHeader) {
    throw new Error("The endpoint did not return a PAYMENT-REQUIRED header.");
  }

  const paymentRequired = JSON.parse(
    Buffer.from(paymentRequiredHeader, "base64").toString("utf8"),
  ) as {
    x402Version: number;
    accepts: Array<{
      scheme: string;
      network: string;
      asset: string;
      amount: string;
      payTo: string;
      maxTimeoutSeconds: number;
      extra?: Record<string, unknown>;
    }>;
    resource?: unknown;
  };

  const arcNetwork = `eip155:${chain.chain.id}`;
  const gatewayOption = paymentRequired.accepts.find(
    (option) =>
      option.extra?.name === "GatewayWalletBatched" &&
      option.network === arcNetwork,
  );

  if (!gatewayOption) {
    throw new Error(
      `The endpoint does not support Gateway nanopayments on ${arcNetwork}.`,
    );
  }

  if (!paymentRequired.resource) {
    throw new Error("The endpoint did not return resource metadata.");
  }

  const paymentPayload = await batchScheme.createPaymentPayload(
    paymentRequired.x402Version,
    gatewayOption,
  );
  const paidResponse = await fetch(url, {
    headers: {
      "PAYMENT-SIGNATURE": Buffer.from(
        JSON.stringify({
          ...paymentPayload,
          accepted: gatewayOption,
          resource: paymentRequired.resource,
        }),
      ).toString("base64"),
    },
  });

  if (!paidResponse.ok) {
    throw new Error(
      `Payment failed: ${paidResponse.status} ${await paidResponse.text()}`,
    );
  }

  return paidResponse.json();
}

Step 6. Run the script

At the end of pay.ts, add a small entry point that calls the functions in order:

pay.ts

async function main(): Promise<void> {
  await ensureGatewayBalance();

  const data = await payForResource(protectedUrl);
  console.log("Paid response:");
  console.dir(data, { depth: null });
}

main().catch((error) => {
  console.error("Error:");
  console.dir(error, { depth: null });
  process.exit(1);
});

Start the protected endpoint from the seller quickstart before running this script. It should be available at http://localhost:3000/premium-data.

Run the script:

npm run pay

The seller returns the resource as soon as Gateway accepts the payment. Onchain settlement happens later when Gateway includes the payment in a batch (often several minutes). You do not need to wait for that to complete a successful pay. To inspect status later, query Search x402 Transfers with the EIP-3009 authorization nonce.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22.6+.
Obtained an EOA (externally owned account) wallet private key for signing transactions and payment authorizations.
Obtained testnet USDC from the Circle Faucet.
Funded your wallet with testnet ETH (or native gas token) for the one-time deposit transaction.

Nanopayments require an EOA wallet. Smart contract account (SCA) wallets are not supported for nanopayments because the batched settlement path verifies EIP-3009 payment authorizations offchain using ecrecover, which is incompatible with ERC-1271 contract signatures. This limitation is specific to nanopayments; standard Gateway transfers support ERC-1271 signatures.

Step 1. Set up your project

1.1. Create the project and install dependencies

mkdir nanopayments-buyer
cd nanopayments-buyer
npm init -y
npm pkg set type=module
npm pkg set scripts.pay="node --env-file=.env pay.ts"
npm install @circle-fin/x402-batching viem typescript
npm install --save-dev @types/node

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file:

npx tsc --init

Then, update the tsconfig.json file:

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

1.3. Set environment variables

Open .env in your editor and add:

PRIVATE_KEY=YOUR_PRIVATE_KEY

PRIVATE_KEY is the private key for the EOA you use to deposit USDC and sign nanopayment authorizations.

Open .env in your editor rather than writing values with shell commands, and add .env to your .gitignore. This prevents credentials from leaking into your shell history or version control.

The npm run pay command loads variables from .env using Node.js native env-file support.

This example uses one or more private keys for local testing. In production, use a secure key management solution and never expose or share private keys.

Step 2. Initialize the client

Create a new file pay.ts and initialize the GatewayClient with your chain and private key:

pay.ts

import { GatewayClient } from "@circle-fin/x402-batching/client";

const client = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

The chain parameter determines which blockchain the client connects to for deposits and withdrawals. See the SDK reference for all supported chain names.

Step 3. Deposit USDC into Gateway

Before you can make gasless payments, deposit USDC from your wallet into the Gateway Wallet contract. This is a one-time onchain transaction:

pay.ts

const balances = await client.getBalances();
console.log(`Gateway balance: ${balances.gateway.formattedAvailable} USDC`);

// 1 USDC = 1_000_000 base units (6 decimals)
if (balances.gateway.available < 1_000_000n) {
  console.log("Depositing 1 USDC...");
  const deposit = await client.deposit("1");
  console.log(`Deposit tx: ${deposit.depositTxHash}`);
}

getBalances() calls the Get Token Balances API endpoint. The deposit itself is an onchain transaction and does not use the Gateway API.After the deposit confirms, your Gateway balance can be used for gasless payments to any supported seller. See the discussion at Fast deposits about increasing deposit speeds.

Step 4. Pay for a resource

Add the payment logic to pay.ts. Call client.pay() with the URL of an x402-protected resource. The client handles the full payment flow automatically:

Sends the initial request to the URL.
Receives the 402 Payment Required response with payment details.
Signs an EIP-3009 authorization offchain (zero gas).
Retries the request with the PAYMENT-SIGNATURE header.

pay.ts

const url = "http://localhost:3000/premium-data";

const { data, status } = await client.pay(url);

console.log(`Status: ${status}`);
console.log("Response:", data);

Under the hood, pay() negotiates the 402 flow and submits the payment through the Settle x402 Payment API endpoint.

Don’t have a seller URL to test with? Set up a local test API in two minutes using the seller quickstart.

Step 5. Check your balance

Add balance checking after the payment using the Get Token Balances API endpoint:

pay.ts

const updated = await client.getBalances();
console.log(`Wallet USDC: ${updated.wallet.formatted}`);
console.log(`Gateway available: ${updated.gateway.formattedAvailable}`);

Step 6. Run the script

Run the complete script:

npm run pay

You should see the deposit transaction (if needed), the response from the paid resource, and your updated balance.

Step 7. Withdraw funds (optional)

You can withdraw USDC from Gateway back to your wallet at any time. Same-chain withdrawals are instant:

pay.ts

const result = await client.withdraw("5");
console.log(`Withdrew ${result.formattedAmount} USDC`);
console.log(`Tx: ${result.mintTxHash}`);

To withdraw to a different blockchain:

pay.ts

const crossChain = await client.withdraw("5", { chain: "baseSepolia" });
console.log(`Withdrew to ${crossChain.destinationChain}`);

Crosschain withdrawals require native gas tokens on the destination blockchain to cover the minting transaction.

Check support before paying

Before attempting a payment, you can verify that the target URL supports Gateway batching. The supports() method requests the target URL, checks for a 402 response, and inspects the PAYMENT-REQUIRED header for a compatible Gateway batching option:

const support = await client.supports(url);

if (!support.supported) {
  console.error("This URL does not support Gateway payments");
} else {
  const { data } = await client.pay(url);
}

This is useful when building clients that interact with APIs where Gateway support is not guaranteed.

​Prerequisites

​Step 1. Set up your project

​1.1. Create the project and install dependencies

​1.2. Configure TypeScript (optional)

​1.3. Set environment variables

​Step 2. Initialize the Circle Wallets client

​Step 3. Fund the wallet

​Step 4. Deposit USDC into Gateway

​Step 5. Pay for a resource

​Step 6. Run the script

​Prerequisites

​Step 1. Set up your project

​1.1. Create the project and install dependencies

​1.2. Configure TypeScript (optional)

​1.3. Set environment variables

​Step 2. Initialize the client

​Step 3. Deposit USDC into Gateway

​Step 4. Pay for a resource

​Step 5. Check your balance

​Step 6. Run the script

​Step 7. Withdraw funds (optional)

​Check support before paying

Prerequisites

Step 1. Set up your project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2. Initialize the Circle Wallets client

Step 3. Fund the wallet

Step 4. Deposit USDC into Gateway

Step 5. Pay for a resource

Step 6. Run the script

Prerequisites

Step 1. Set up your project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2. Initialize the client

Step 3. Deposit USDC into Gateway

Step 4. Pay for a resource

Step 5. Check your balance

Step 6. Run the script

Step 7. Withdraw funds (optional)

Check support before paying