Agent Commerce
Star on GitHub

Public networks

Base mainnet

Real funds on Base, with every mainnet guardrail set explicitly rather than left to a default.

Real fundsRead Networks & facilitators first. Only the port, the receipt store path and the RPC URL have fallbacks. Every other ${VAR} has none, so a missing one fails config loading instead of resolving to something plausible.
examples/base-mainnet/config.yamlyaml
version: 1

merchant:
  id: base-mainnet-example
  name: Base Mainnet Example
  publicBaseUrl: ${GATEWAY_PUBLIC_BASE_URL}

server:
  port: ${GATEWAY_PORT:-8080}
  host: 0.0.0.0
  # Required here: operator routes carry the commerce ledger. Without
  # adminToken they 404, and you cannot read your own receipts over HTTP.
  adminToken: ${ADMIN_TOKEN}
  allowedOrigins: []

storage:
  receipts:
    driver: sqlite
    path: ${RECEIPT_STORE_PATH:-./data/receipts.sqlite}

protocols:
  http:
    enabled: true
  mcp:
    enabled: true
    mountPath: /mcp

resources:
  premium_report:
    name: Premium Report
    description: One paid endpoint, settled in USDC on Base.
    input:
      type: object
      properties: {}
      additionalProperties: false
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/report
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.01"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

payments:
  x402:
    enabled: true
    network: eip155:8453                         # required. Base mainnet
    rpcUrl: ${X402_RPC_URL:-https://base.drpc.org} # health checks and reconcile
    asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  # USDC on Base
    assetName: "USD Coin"                        # the EIP-712 domain, not "USDC"
    assetVersion: "2"
    assetDecimals: 6
    payTo: ${MERCHANT_WALLET}                    # required. Your wallet.
    maxTimeoutSeconds: 600
    allowMainnet: ${ALLOW_X402_MAINNET}          # required, and required to be true
    facilitator:
      mode: remote                               # required. `local` is refused
      # required, and must be https. `cdp` auth works only with this URL
      url: https://api.cdp.coinbase.com/platform/v2/x402
      auth:
        type: cdp                                # needs @coinbase/x402
        apiKeyId: ${CDP_API_KEY_ID}
        apiKeySecret: ${CDP_API_KEY_SECRET}
      # For any facilitator that takes a static token, set its url and use:
      #   auth:
      #     type: bearer
      #     token: ${X402_FACILITATOR_TOKEN}

What you need

Variable
MERCHANT_WALLETyour wallet address or a contract address; see Paying into a contract
ALLOW_X402_MAINNET=truethe explicit opt-in; never a default
CDP_API_KEY_ID, CDP_API_KEY_SECRETcdp requires the optional @coinbase/x402 peer and CDP's URL, already configured. Or a bearer token with auth.type: bearer, which needs no extra package; set its facilitator's https url
ADMIN_TOKENrequired here: it guards the receipt routes, which carry your ledger
GATEWAY_PUBLIC_BASE_URLwhere agents reach you
MERCHANT_API_BASE_URLyour backend, which the paid resource calls
A Base RPChealth checks and reconcile; use a dedicated RPC to avoid readiness failures from public-endpoint outages

To run without a facilitator credential, see Base mainnet (PayAI), which sets allowUnauthenticatedFacilitator.

Paying into a contract

MERCHANT_WALLET sets the x402 payTo, which can be a contract such as a revenue splitter on Base. USDC's EIP-3009 transferWithAuthorization invokes no recipient callback, so the contract needs no receive handler. Before using one:

  • Confirm it can send USDC onward, for example through a distribute function; otherwise the funds stay at that address.
  • Verify the contract's deployment on every offer's network. An EOA's key controls its address across EVM chains; contract code must be deployed on each chain. Reusing ${MERCHANT_WALLET} for Base and Polygon sends both networks' payments to the same address. Confirm that the intended contract and its withdrawal logic exist on both.

Validate before anything else

bash
ALLOW_X402_MAINNET=true \
MERCHANT_WALLET=0xYourWallet \
GATEWAY_PUBLIC_BASE_URL=https://your.gateway \
ADMIN_TOKEN=... \
MERCHANT_API_BASE_URL=http://localhost:3000 \
CDP_API_KEY_ID=... CDP_API_KEY_SECRET=... \
  npm run agent-commerce -- validate --config examples/base-mainnet/config.yaml
Drop any one of themconsole
FAIL  CONFIG_INVALID: Unresolved environment variable "${ALLOW_X402_MAINNET}" referenced at config path "$.payments.x402.allowMainnet"
      details: {"variable":"ALLOW_X402_MAINNET","path":"$.payments.x402.allowMainnet"}

With every value set, doctor reports the deployment as LIVE MAINNET MODE - REAL FUNDS.

Prove it settles

bash
export ALLOW_X402_MAINNET=true
export X402_SMOKE_TARGETS=base
export X402_MAINNET_BUYER_PRIVATE_KEY=0x...   # funded with USDC on Base
export X402_MAINNET_MERCHANT_ADDRESS=0x...
export X402_FACILITATOR_URL=https://...
export CDP_API_KEY_ID=... CDP_API_KEY_SECRET=...   # or X402_FACILITATOR_TOKEN
npm run test:mainnet

Each successful x402 smoke run spends X402_SMOKE_AMOUNT (default 0.01) of real USDC. The suite skips unless X402_SMOKE_TARGETS names base, then fails if the opt-in, buyer key, merchant address or facilitator URL is missing. Facilitator credentials are optional. ALLOW_MPP_MAINNET=true enables the separate, paid MPP smoke suite. These suites never run in CI, keeping mainnet keys out of repository secrets.

The smoke suite checks that:

  1. the guard refuses a config that has not opted in;
  2. the deployment reports itself as live mainnet;
  3. a payment settles on Base;
  4. the receipt carries the settlement reference and a 2xx backend status;
  5. the resource is delivered exactly once;
  6. the same authorization presented again is refused, and the backend is not called again;
  7. configured payment secrets are absent from captured gateway logs.

The USDC Transfer is read back from the transaction receipt. See smoke tests.

Source: examples/base-mainnet