Agent Commerce
Star on GitHub

Overview

Integration guide

Everything you need to put the gateway in front of your API and let agents pay for it — in five steps.

An integration has two sides. As the merchant, you run the gateway in front of your API and decide what each endpoint costs and who can see it. As the agent (the buyer), you discover those resources, call them, and answer a payment challenge when one comes back. This tab covers both, end to end.

Let a coding agent do itClaude Code, Codex or Cursor can follow these steps for you, using the agent-commerce skill. See Integrate with AI.

Before you start

  • An HTTP API the gateway can reach
    Any existing JSON API. No SDK goes into your backend and nothing in it is rewritten.
  • Node.js ≥ 22, or Docker
    Node for the CLI and the gateway itself; Docker only for the bundled demo stack.
  • A wallet address you control
    This becomes payTo. It is an address only — the gateway never asks for a merchant key.
  • A network
    The local dev chain for development, a public testnet such as Base Sepolia or Solana devnet to prove real settlement, and a mainnet such as Base or Solana for real funds.

Merchant integration in five steps

  1. Describe your API

    Turn endpoints into resources in config.yaml — by hand, from OpenAPI, or with the wizard. See Describe your API.

  2. Accept payments

    Configure x402, or experimental MPP, with your settlement address, the network and a facilitator. See Accept payments.

  3. Expose to agents

    Enable HTTP, MCP, A2A or ACP and choose per resource where it appears. See Expose to agents.

  4. Run and verify

    Start the gateway with agent-commerce start, then check the config and running service with validate and doctor. See Run the gateway, and Deploy to a server for production.

  5. Go live

    Admin token, origins, TLS and rate limiting at your edge. See the go-live checklist.

A complete configuration

This is a whole, valid config.yaml: one paid endpoint, reachable over HTTP and MCP, settling real USDC on Base Sepolia through the public testnet facilitator. Replace the backend URL and MERCHANT_WALLET, and it is an integration.

config.yamlyaml
version: 1

merchant:
  id: my-store
  name: My Store
  publicBaseUrl: ${GATEWAY_PUBLIC_BASE_URL:-http://localhost:8080}

server:
  port: ${GATEWAY_PORT:-8080}
  host: 0.0.0.0
  adminToken: ${ADMIN_TOKEN}

storage:
  receipts:
    driver: sqlite
    path: ./data/receipts.sqlite

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

resources:
  premium_report:
    name: Premium Report
    description: A paid endpoint on your existing backend.
    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:84532
    rpcUrl: https://base-sepolia-rpc.publicnode.com   # health checks and reconcile
    payTo: ${MERCHANT_WALLET}           # no asset fields: the network's USDC
    maxTimeoutSeconds: 300
    facilitator:
      mode: remote
      url: https://x402.org/facilitator
      auth: { type: none }
bash
npm install @devlab.group/[email protected] @modelcontextprotocol/[email protected] @x402/[email protected] @x402/[email protected] [email protected]

export MERCHANT_API_BASE_URL=https://api.example.com
export MERCHANT_WALLET=0xYourWalletAddress
export ADMIN_TOKEN=$(openssl rand -hex 32)

npx @devlab.group/agent-commerce validate --config config.yaml
npx @devlab.group/agent-commerce start --config config.yaml

Agent integration

Connect an agentMCP, HTTP, A2A or ACP — discover and call resources.Handle a paymentCheck the 402 challenge, sign it, retry with the proof.AP2 mandatesProve a human approved this exact purchase.

Pick your path

I have an OpenAPI descriptionGenerate the resources and review them instead of typing YAML.MCP tools onlyA paid resource with no HTTP route at all.ACP checkoutMap the five checkout operations onto your checkout API.Embed in my Node serviceCompose the gateway yourself with createGateway.