How Agent Commerce Gateway works

Agent Commerce Gateway gives an existing API one controlled edge for agent traffic. The backend continues to own the useful work; the Gateway makes each request legible as a commercial transaction before that work begins.

This separation matters because an agent request is more than a new transport. It can carry a price, an authorization, a payment proof and retry risk. Putting those concerns in one boundary keeps protocol changes out of the application and gives operators a durable account of what happened.

#One boundary for agent channels

Native HTTP and MCP are current entry points. A2A and ACP are experimental profiles, AP2 is an experimental authorization profile, MPP is an experimental payment rail, and UCP remains planned. Those labels are deliberate: the standards are evolving, while the merchant integration should remain stable.

Each adapter translates its protocol into a canonical capability request. From that point on, the same validation, pricing, payment and receipt rules apply. Adding a channel therefore means adding an adapter, not teaching the backend another protocol.

#A capability becomes a contract

Integration starts with something the business already does: verify a document, enrich a company, calculate a quote, reserve inventory or run a bounded compute job. The merchant defines the accepted input, the backend call, the price and the channels that expose it. That contract is what every adapter exposes.

Validation happens at the edge, before protocol input reaches business logic. Invalid types, missing fields and resource limits fail in the same way regardless of the channel. A valid request is mapped to the HTTP shape the existing service already understands.

resources:
  company.verify:
    name: Company verification
    input:
      type: object
      properties:
        company_id: { type: string }
      required: [company_id]
      additionalProperties: false
    backend:
      type: http
      method: POST
      url: ${MERCHANT_API_BASE_URL}/v1/companies/verify
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.08"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

#One canonical transaction path

After mapping, the request enters a shared pipeline. A free lookup can skip payment; a paid and state-changing operation takes the longer route. The order stays explicit so payment cannot accidentally become a substitute for authorization, or a successful settlement be mistaken for successful delivery.

Pricing stays attached to the capability, not to the protocol. The agent can see the commercial terms before the merchant operation runs, while the backend remains unaware of how MCP or a payment rail expressed them.

#How a paid request moves

x402 and experimental MPP both settle through an x402 facilitator. The first request can return a machine-readable payment requirement. The agent authorizes payment and submits proof; the Gateway verifies it and reserves it against replay. Under the authorization flow, the x402 default, it calls the merchant backend before settling. With paymentFlow: upfront, the MPP default, it settles first. A failed backend call under the authorization flow leaves the payment unsettled; a refused or uncertain settlement withholds the backend response.

#Payment and delivery are separate facts

With upfront settlement, payment can succeed while the backend is unavailable. With the authorization flow, the backend can finish while settlement is refused or uncertain, withholding its response. In either flow, the response can be lost in transit. Recording these outcomes separately gives operators the information needed to recover.

The Gateway records payment, execution and delivery separately. Each paid resource uses its first enabled rail, without switching rails after an uncertain result. Operators can inspect the records, use agent-commerce reconcile to resolve outcomes from chain evidence, or record a verdict with agent-commerce resolve when that evidence is inconclusive.

#Durable state makes recovery possible

One SQLite receipt database preserves receipts, events, payment attempts, replay reservations, journal entries, AP2 holds, ACP claims and unpaid A2A tasks across restarts. The journal links payment, backend execution and receipts. Run one gateway per database; PostgreSQL support is planned for deployments needing a different persistence model.

A receipt gives buyer and merchant one safe reference for the whole operation. It can state the capability, settlement reference, backend outcome and delivery status without exposing credentials or raw payment material.

{
  "id": "receipt_3f6c…",
  "requestId": "req_9b1e…",
  "resourceId": "company.verify",
  "protocol": "http",
  "payment": {
    "status": "settled",
    "provider": "x402",
    "externalReference": "0x91e…42c",
    "amount": "0.08",
    "currency": "USDC",
    "network": "eip155:84532"
  },
  "deliveredAt": "2026-09-16T14:31:56.720Z",
  "backendStatus": 200,
  "durationMs": 239
}

#What stays under merchant control

The merchant keeps the backend, capability definitions, pricing, settlement destination, deployment environment and customer relationships. Agent Commerce Gateway is neither a marketplace nor a payment processor. It is the transaction layer around resources the business already owns.

Before accepting traffic, the operator can run agent-commerce doctor. It checks the active configuration as a working system: Gateway readiness, backend reachability, exposed protocols, payment configuration, storage and relevant external dependencies. The goal is to find a broken link before an agent reaches it with a paid request.

agent-commerce doctor --json

#Frequently asked questions