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, 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 response, the price and whether the action changes state. 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.

id: company.verify
input:
  company_id: string
price:
  amount: "0.08"
  currency: USDC
execution:
  method: POST
  path: /v1/companies/verify
  operation_key: request_id

#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

In the current x402 path, the first request can return a machine-readable payment requirement. The agent authorizes payment and submits proof. The Gateway verifies that proof, reserves replay protection, settles the payment and only then invokes the merchant operation.

#Payment and delivery are separate facts

Distributed systems produce awkward outcomes. A settlement can succeed while the backend is unavailable; the backend can complete while the response disappears; a provider can leave settlement uncertain. Calling all of these cases “failed” removes the information needed to recover safely.

The Gateway records payment, execution and delivery independently. It will not silently try another payment rail while the first attempt is uncertain, because that could charge the buyer twice. Operators see the actual state and can reconcile it without guessing.

#Durable state makes recovery possible

Receipts, events, payment attempts and replay reservations survive a process restart. The current single-node runtime uses SQLite; a later PostgreSQL path is intended for deployments that need a different persistence model. In either case, the purpose is the same: a paid request must not disappear because one process stopped.

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.

{
  "receipt_id": "rcpt_01JY8M4N",
  "request_id": "req_01JY8M1Q",
  "capability": "company.verify",
  "payment": { "state": "settled", "rail": "x402" },
  "execution": { "state": "completed", "status": 200 },
  "delivery": { "state": "delivered" }
}

#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 --output json

#Frequently asked questions