How-to: Sign a seller proof

Construct a Facilitator-Seller-Proof header for keyless Facilitator Service requests. The proof carries an EIP-712 signature that proves you control payTo and binds the request to a specific purpose and body.

Prerequisites

Before you begin, ensure that you’ve:

Read The keyless trial so you understand the trial allowance
Obtained the private key controlling payTo, or a deployed ERC-1271 smart contract account at payTo
Installed viem, or a comparable EIP-712 signing library

Steps

Construct the EIP-712 domain

The domain anchors the signature to Facilitator Service.

sign-proof.ts

const domain = {
  name: "Circle Facilitator Seller Request",
  version: "1",
  chainId: 5042002, // EIP-155 chain ID for the payment's network
};

Set chainId to the numeric EIP-155 chain ID for the network you’re settling on.

Define the typed data

The SellerRequest struct is what Facilitator Service reconstructs and verifies against the signature.

sign-proof.ts

const types = {
  SellerRequest: [
    { name: "purpose", type: "string" },
    { name: "method", type: "string" },
    { name: "bodyHash", type: "bytes32" },
    { name: "network", type: "string" },
    { name: "payTo", type: "address" },
    { name: "nonce", type: "bytes32" },
    { name: "issuedAt", type: "uint64" },
    { name: "expiresAt", type: "uint64" },
  ],
};

Populate the message

sign-proof.ts

import { keccak256, toBytes, toHex } from "viem";

const nonce = crypto.getRandomValues(new Uint8Array(32));
const issuedAt = Math.floor(Date.now() / 1000);

const message = {
  purpose: "settle", // "verify", "settle", "status", or "claim"
  method: "POST", // uppercase HTTP method
  bodyHash: keccak256(toBytes(body)), // keccak256 of raw HTTP body, GET hashes empty bytes
  network: "eip155:5042002",
  payTo: "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
  nonce: toHex(nonce),
  issuedAt: BigInt(issuedAt),
  expiresAt: BigInt(issuedAt + 300),
};

The signed message must meet these rules:

purpose must match the route you’re calling.
On /verify and /settle, network and payTo must equal the request body’s paymentRequirements.network and paymentRequirements.payTo. A mismatch returns HTTP 401.
issuedAt may be at most 30 seconds ahead of the current time.
expiresAt must be later than the current time and no more than 5 minutes after issuedAt.
A nonce is unique across purposes in one (network, payTo). Exact retries reuse the nonce. Reuse with a different digest returns HTTP 401.

Sign the typed data

sign-proof.ts

import { privateKeyToAccount } from "viem/accounts";

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

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

EOA signatures are recovered to payTo. Deployed smart contract accounts at payTo are validated through ERC-1271.

Base64url-encode the envelope

The envelope carries the signature and the fields Facilitator Service needs to reconstruct what was signed.

sign-proof.ts

const envelope = {
  version: 1,
  signature,
  network: message.network,
  payTo: message.payTo,
  nonce: message.nonce,
  issuedAt: Number(message.issuedAt),
  expiresAt: Number(message.expiresAt),
};

const header = Buffer.from(JSON.stringify(envelope)).toString("base64url");

Send header as the Facilitator-Seller-Proof header on your Facilitator Service request.

Circle CLI

Agent marketplace

x402 facilitators

How-to: Sign a seller proof

Prerequisites

Steps

​Prerequisites

​Steps

Prerequisites

Steps