SDK Reference

This page documents the public API of the @circlefin/x402-batching package, which provides buyer and seller integrations for Circle Gateway nanopayments.

npm install @circlefin/x402-batching

Buyer APIs

`GatewayClient`

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

The primary client for buyers. Handles deposits, gasless payments, withdrawals, and balance queries.

Constructor

new GatewayClient(config: GatewayClientConfig)

Parameter	Type	Required	Description
`config.chain`	`SupportedChainName`	Yes	Blockchain to connect to (for example, `'arcTestnet'`, `'baseSepolia'`)
`config.privateKey`	`Hex`	Yes	Private key for signing (`'0x...'`)
`config.rpcUrl`	`string`	No	Custom RPC URL (overrides the default for the chain)

Properties

Property	Type	Description
`address`	`Address`	The account’s wallet address
`chainName`	`string`	Human-readable chain name
`domain`	`number`	Gateway domain identifier
`publicClient`	`PublicClient`	viem public client instance
`walletClient`	`WalletClient`	viem wallet client instance

`deposit(amount, options?)`

Deposits USDC from your wallet into the Gateway Wallet contract. This is an onchain transaction that requires gas.

Parameter	Type	Required	Description
`amount`	`string`	Yes	Amount in decimal USDC (for example, `'10.5'`)
`options.approveAmount`	`string`	No	ERC-20 approval amount (defaults to `amount`)

Returns Promise<DepositResult>:

interface DepositResult {
  approvalTxHash?: Hex;
  depositTxHash: Hex;
  amount: bigint;
  formattedAmount: string;
}

`pay<T>(url, options?)`

Pays for an x402-protected resource. Handles the full 402 negotiation flow automatically: sends the request, receives payment requirements, signs the authorization, and retries with the payment header.

Parameter	Type	Required	Description
`url`	`string`	Yes	URL of the x402-protected resource
`options`	`RequestInit`	No	Standard fetch options (method, body, headers)

Returns Promise<PayResult<T>>:

interface PayResult<T> {
  data: T;
  amount: bigint;
  formattedAmount: string;
  transaction: string;
  status: number;
}

`withdraw(amount, options?)`

Withdraws USDC from Gateway to your wallet. Supports same-chain (instant) and crosschain withdrawals.

Parameter	Type	Required	Description
`amount`	`string`	Yes	Amount in decimal USDC
`options.chain`	`SupportedChainName`	No	Destination blockchain (defaults to same chain)
`options.recipient`	`Address`	No	Recipient address (defaults to your address)

Returns Promise<WithdrawResult>:

interface WithdrawResult {
  mintTxHash: Hex;
  amount: bigint;
  formattedAmount: string;
  sourceChain: string;
  destinationChain: string;
  recipient: Address;
}

`getBalances(address?)`

Returns both the wallet’s USDC balance and the Gateway balance.

Parameter	Type	Required	Description
`address`	`Address`	No	Address to query (defaults to the client’s address)

Returns Promise<Balances>:

interface Balances {
  wallet: { balance: bigint; formatted: string };
  gateway: GatewayBalance;
}

interface GatewayBalance {
  total: bigint;
  available: bigint;
  withdrawing: bigint;
  withdrawable: bigint;
  formattedTotal: string;
  formattedAvailable: string;
}

`supports(url)`

Checks whether a URL supports Gateway batching before attempting payment.

Parameter	Type	Required	Description
`url`	`string`	Yes	URL to check

Returns Promise<SupportsResult>:

interface SupportsResult {
  supported: boolean;
  requirements?: Record<string, unknown>;
  error?: string;
}

`BatchEvmScheme`

import { BatchEvmScheme } from "@circlefin/x402-batching/client";

A SchemeNetworkClient implementation for Circle Gateway batched payments. Use this when integrating with an existing x402Client instance or building a custom payment flow.

Constructor

new BatchEvmScheme(signer: BatchEvmSigner)

Parameter	Type	Required	Description
`signer`	`BatchEvmSigner`	Yes	Object with `address` and `signTypedData` function

`createPaymentPayload(x402Version, paymentRequirements)`

Creates a signed payment payload by constructing and signing an EIP-3009 TransferWithAuthorization message.

Parameter	Type	Required	Description
`x402Version`	`number`	Yes	x402 protocol version (use `2`)
`paymentRequirements`	`PaymentRequirements`	Yes	Requirements from the `402` response

Returns Promise<PaymentPayload>.

`registerBatchScheme`

import { registerBatchScheme } from "@circlefin/x402-batching/client";

Helper that registers a BatchEvmScheme with an x402Client:

registerBatchScheme(client, { signer: account });

Seller APIs

`createGatewayMiddleware`

import { createGatewayMiddleware } from "@circlefin/x402-batching/server";

Creates Express-compatible middleware that handles x402 payment negotiation, verification, and settlement.

Configuration

createGatewayMiddleware(config: GatewayMiddlewareConfig)

Parameter	Type	Required	Description
`config.sellerAddress`	`string`	Yes	Your wallet address for receiving payments
`config.networks`	`string \| string[]`	No	Networks to accept (defaults to all supported)
`config.description`	`string`	No	Resource description included in `402` responses

`require(price)`

Returns Express middleware that requires payment for the route.

Parameter	Type	Description
`price`	`string`	Price in USD (for example, `'$0.01'` or `'0.01'`)

The middleware attaches payment information to req.payment:

interface PaymentInfo {
  verified: boolean;
  payer: string;
  amount: string;
  network: string;
  transaction?: string;
}

`BatchFacilitatorClient`

import { BatchFacilitatorClient } from "@circlefin/x402-batching/server";

A FacilitatorClient implementation that communicates with Circle Gateway’s x402 endpoints. Use this for custom server frameworks or when you need fine-grained control over verification and settlement.

Constructor

new BatchFacilitatorClient(config?: BatchFacilitatorConfig)

`verify(payload, requirements)`

Verifies a payment signature through the Gateway API.

Parameter	Type	Description
`payload`	`PaymentPayload`	The payment payload from the client
`requirements`	`PaymentRequirements`	The payment requirements you declared

Returns Promise<VerifyResponse>:

interface VerifyResponse {
  isValid: boolean;
  invalidReason?: string;
  payer?: string;
}

`settle(payload, requirements)`

Submits a payment for batched settlement through the Gateway API. This is the recommended method for production flows because it has low latency and guarantees settlement.

Parameter	Type	Description
`payload`	`PaymentPayload`	The payment payload from the client
`requirements`	`PaymentRequirements`	The payment requirements you declared

Returns Promise<SettleResponse>:

interface SettleResponse {
  success: boolean;
  errorReason?: string;
  payer?: string;
  transaction: string;
}

`getSupported()`

Fetches the payment kinds (networks and contract addresses) supported by Gateway. Returns Promise<SupportedResponse>:

interface SupportedResponse {
  kinds: Array<{
    x402Version: number;
    scheme: string;
    network: string;
    extra?: { verifyingContract?: string };
  }>;
}

Utilities

`supportsBatching`

import { supportsBatching } from "@circlefin/x402-batching";

Checks whether a PaymentRequirements object supports Gateway batched settlement. Returns true if the requirements include the GatewayWalletBatched scheme.

`isBatchPayment`

import { isBatchPayment } from "@circlefin/x402-batching/server";

Server-side alias for supportsBatching. Use this in facilitator routing logic to determine whether a payment should be routed to Gateway.

`getVerifyingContract`

import { getVerifyingContract } from "@circlefin/x402-batching";

Extracts the Gateway Wallet contract address from a PaymentRequirements object.

Constants

import {
  CIRCLE_BATCHING_NAME,
  CIRCLE_BATCHING_VERSION,
  CIRCLE_BATCHING_SCHEME,
} from "@circlefin/x402-batching";

Constant	Value	Description
`CIRCLE_BATCHING_NAME`	`'GatewayWalletBatched'`	EIP-712 domain name used for batch payment signatures
`CIRCLE_BATCHING_VERSION`	`'1'`	EIP-712 domain version
`CIRCLE_BATCHING_SCHEME`	`'exact'`	x402 payment scheme identifier

Chain configuration

import {
  CHAIN_CONFIGS,
  GATEWAY_DOMAINS,
} from "@circlefin/x402-batching/client";

CHAIN_CONFIGS: Full configuration (USDC address, Gateway Wallet address, RPC URL) for all supported blockchains.
GATEWAY_DOMAINS: Domain IDs for EIP-712 signing, keyed by chain name.

Bridge Kit

CCTP

Gateway

Buyer APIs

`GatewayClient`

Constructor

Properties

`deposit(amount, options?)`

`pay<T>(url, options?)`

`withdraw(amount, options?)`

`getBalances(address?)`

`supports(url)`

`BatchEvmScheme`

Constructor

`createPaymentPayload(x402Version, paymentRequirements)`

`registerBatchScheme`

Seller APIs

`createGatewayMiddleware`

Configuration

`require(price)`

`BatchFacilitatorClient`

Constructor

`verify(payload, requirements)`

`settle(payload, requirements)`

`getSupported()`

Utilities

`supportsBatching`

`isBatchPayment`

`getVerifyingContract`

Constants

Chain configuration

Bridge Kit

CCTP

Gateway

​Buyer APIs

​GatewayClient

​Constructor

​Properties

​deposit(amount, options?)

​pay<T>(url, options?)

​withdraw(amount, options?)

​getBalances(address?)

​supports(url)

​BatchEvmScheme

​Constructor

​createPaymentPayload(x402Version, paymentRequirements)

​registerBatchScheme

​Seller APIs

​createGatewayMiddleware

​Configuration

​require(price)

​BatchFacilitatorClient

​Constructor

​verify(payload, requirements)

​settle(payload, requirements)

​getSupported()

​Utilities

​supportsBatching

​isBatchPayment

​getVerifyingContract

​Constants

​Chain configuration

Buyer APIs

`GatewayClient`

Constructor

Properties

`deposit(amount, options?)`

`pay<T>(url, options?)`

`withdraw(amount, options?)`

`getBalances(address?)`

`supports(url)`

`BatchEvmScheme`

Constructor

`createPaymentPayload(x402Version, paymentRequirements)`

`registerBatchScheme`

Seller APIs

`createGatewayMiddleware`

Configuration

`require(price)`

`BatchFacilitatorClient`

Constructor

`verify(payload, requirements)`

`settle(payload, requirements)`

`getSupported()`

Utilities

`supportsBatching`

`isBatchPayment`

`getVerifyingContract`

Constants

Chain configuration