How-to: Sign EIP-3009 payment authorizations

Authorize Circle Gateway to transfer USDC from your Gateway balance by signing an EIP-3009 TransferWithAuthorization message directly. Sign manually when integrating a custom payment workflow, building a non-JavaScript client, or debugging what the SDK handles automatically.

Prerequisites

Before you begin, ensure that you’ve:

Generated an EVM wallet private key for signing.
Deposited USDC into a Gateway Wallet contract (see the buyer quickstart).
Familiarized yourself with EIP-712 typed data signing.
Installed the viem library (npm install viem).

Steps

Construct the EIP-712 domain

Gateway uses a custom EIP-712 domain named GatewayWalletBatched. This is specific to Gateway’s batching feature and is not the standard USDC domain.

sign.ts

const domain = {
  name: "GatewayWalletBatched",
  version: "1",
  chainId: 5042002, // Arc Testnet — replace with your target chain's EVM chain ID
  verifyingContract: "0x0077777d7EBA4688BDeF3E311b846F25870A19B9", // GatewayWallet on Arc Testnet
};

The verifyingContract is the GatewayWallet contract address for the blockchain you are transacting on. Find the address for your target blockchain in the EVM contract addresses reference. You can also retrieve it programmatically using getVerifyingContract() from the SDK or from the 402 response’s accepts array (in the extra.verifyingContract field).

The chainId must be the standard EVM chain ID for your target network (for example, 5042002 for Arc Testnet), not the Gateway domain identifier. Using the wrong chain ID causes the signature to fail silently.

Define the typed data

The TransferWithAuthorization type follows the EIP-3009 specification:

sign.ts

const types = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" },
  ],
};

Populate the message fields.USDC uses 6 decimal places: $1.00 = 1000000, $0.01 = 10000, $0.001 = 1000. Always convert dollar amounts to base units before signing.

sign.ts

import { randomBytes } from "crypto";

const message = {
  from: "0xYOUR_ADDRESS", // Your wallet address (the payer)
  to: "0xSELLER_ADDRESS", // The seller's wallet address
  value: 10000n, // Amount in USDC base units (0.01 USDC = 10000)
  validAfter: 0n, // Signature is valid immediately
  validBefore: BigInt(Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 5), // Valid for 5 days
  nonce: `0x${randomBytes(32).toString("hex")}`, // Unique random nonce
};

The validBefore timestamp must be at least 3 days in the future. Gateway rejects signatures with shorter validity periods to ensure there is enough time to include them in a settlement batch.

Sign the typed data

Use the viem library’s signTypedData to produce the EIP-712 signature:

sign.ts

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const signature = await account.signTypedData({
  domain,
  types,
  primaryType: "TransferWithAuthorization",
  message,
});

console.log("Signature:", signature);

Assemble and send the payment payload

Encode the payment payload as base64 JSON and attach it to your HTTP request in the Payment-Signature header. The server-side facilitator settles this payment through the Settle x402 Payment API endpoint:

sign.ts

const paymentPayload = {
  x402Version: 2,
  payload: {
    authorization: {
      from: message.from,
      to: message.to,
      value: message.value.toString(),
      validAfter: message.validAfter.toString(),
      validBefore: message.validBefore.toString(),
      nonce: message.nonce,
    },
    signature,
  },
  resource: "...", // from 402 response
  accepted: {}, // the payment option chosen
};

const encoded = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");

const response = await fetch("http://localhost:3000/premium-data", {
  headers: {
    "Payment-Signature": encoded,
  },
});

console.log("Status:", response.status);
console.log("Body:", await response.json());

Alternative: sign through the x402 client scheme

If you are integrating with an existing x402 client (such as @x402/core), use BatchEvmScheme instead of constructing the payload manually. It handles domain construction, nonce generation, and payload encoding:

sign-x402.ts

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

const batchScheme = new BatchEvmScheme({
  address: account.address,
  signTypedData: async (params) => account.signTypedData(params),
});

// Get requirements from a 402 response
const res = await fetch(url);
const header = res.headers.get("PAYMENT-REQUIRED");
const { accepts } = JSON.parse(Buffer.from(header, "base64").toString());
const gatewayOption = accepts.find(
  (opt) => opt.extra?.name === "GatewayWalletBatched",
);

// Create the payment payload
const payload = await batchScheme.createPaymentPayload(2, gatewayOption);

// Retry with the payload
const finalResponse = await fetch(url, {
  headers: {
    "Payment-Signature": Buffer.from(
      JSON.stringify({ ...payload, accepted: gatewayOption }),
    ).toString("base64"),
  },
});

Troubleshoot rejected signatures

Gateway returns invalid_signature for any EIP-712 domain or field mismatch without specifying which field is wrong. If your signature is rejected, check every item in this list:

Domain name must be exactly "GatewayWalletBatched". Common mistakes include "GatewayWallet", "Gateway", and "USDC".
verifyingContract must be the GatewayWallet contract address, not the USDC token address or GatewayMinter. See EVM contract addresses for the correct address on each blockchain.
chainId must be the standard EVM chain ID (for example, 5042002 for Arc Testnet). Do not use the Gateway domain identifier.
nonce must be a unique random 32-byte value for every payment. Reusing a nonce causes the same invalid_signature error.
validBefore must be at least 3 days in the future. Shorter validity periods are rejected with authorization_validity_too_short.
value must be in USDC base units (6 decimals). Passing a dollar amount instead of base units causes an amount mismatch.
from must match the address derived from the private key that signed the message.

For the full list of error codes, see the error reference.

The EIP-712 domain for payment authorizations (GatewayWalletBatched) is different from the domain used for Gateway withdrawal and crosschain transfer operations (GatewayWallet). If you are building manual signing for both payments and withdrawals, use the correct domain for each operation. The SDK’s client.withdraw() and client.pay() methods handle this automatically.

Circle CLI

Agent marketplace

x402 facilitators

How-to: Sign EIP-3009 payment authorizations

Prerequisites

Steps

Alternative: sign through the x402 client scheme

Troubleshoot rejected signatures

​Prerequisites

​Steps

​Alternative: sign through the x402 client scheme

​Troubleshoot rejected signatures

Prerequisites

Steps

Alternative: sign through the x402 client scheme

Troubleshoot rejected signatures