POST /agent/checkout
Create a checkout session. Returns a self-describing payment_required that says exactly what to pay and the literal next call to make.
Creates a checkout session for a cart. The response is self-describing: the
payment_required block says what to pay and how, and its next field is the literal call
to make — the agent doesn't need these docs to proceed.
Request
{
"agent_id": "11111111-1111-1111-1111-111111111111",
"items": [{ "sku": "widget", "qty": 2 }],
"buyer_intent": "free text describing why",
"mandate": { "type": "veto", "token": "<compact JWS>" },
"rail": "x402",
"idempotency_key": "client-supplied"
}| Field | Required | Notes |
|---|---|---|
agent_id | ✅ | Who is buying — used for reputation + rate limits. |
items | ✅ | [{ sku, qty }]; at least one line. |
buyer_intent | optional | Free text; used by intent policy rules. |
mandate | optional | Polymorphic; see Mandates. |
rail | optional | Defaults to the first supported rail. |
idempotency_key | optional | Recommended — agents retry. |
Response — 200
{
"session_id": "…",
"state": "awaiting_payment",
"total": { "currency": "USD", "subtotal": "25.00", "tax": "0.00", "total": "25.00" },
"payment_required": {
"rail": "x402",
"amount": "25.00",
"currency": "USD",
"chain": "base",
"asset": "USDC",
"payTo": "0x...",
"amountBaseUnits": "25000000",
"validUntil": 1750000000,
"description": "Pay 25.00 USDC on base to 0x... then settle.",
"next": "POST /agent/checkout/{session_id}/settle body { payment }"
},
"expires_at": 1750000900
}Status codes
| Status | Meaning |
|---|---|
200 | Created. |
400 | Bad request — reason_codes say which field (e.g. AGENT_ID_REQUIRED, ITEMS_REQUIRED). |
404 | Unknown SKU (SKU_UNKNOWN). |
409 | Idempotency conflict — same key, different body (IDEMPOTENCY_KEY_REUSED). |
422 | Rail not supported / item unavailable (SKU_UNAVAILABLE, RAIL_NOT_ALLOWED). |
Next: settle the session.
GET /agent/catalog
The product list. Each item carries a sku, name, exact-decimal price, availability, and optional description, category, unit, and metadata.
POST /agent/checkout/{id}/settle
Submit payment and run the acceptance gate. Returns one of accepted (200), hold (202), payment_invalid (402), or rejected (403) — and replays terminal results verbatim for idempotent retries.