Agent Commerce
Star on GitHub

Gateway

Invoke a resource

POST /api/resources/{id}/invoke — call a free resource, or complete a paid one with an x402 proof.

POST/api/resources/{id}/invokepayment, not authentication

Invoke a resource exposed over http. The JSON body is the resource input. Free resources are delivered directly; paid ones answer 402 until the same request is repeated with a valid proof.

Request

Path

idstringrequired
The resource id.

Headers

content-typeapplication/json
PAYMENT-SIGNATUREbase64
The x402 payment proof, for a paid resource.
Agent-Authorizationbase64url
An AP2 envelope, when the resource requires a mandate. Max 8192 bytes.
X-Request-Idstring
Optional correlation id.

Body

…object
The input, validated against the resource's schema. Unknown properties are refused.

Examples

curl -s http://localhost:8080/api/resources/weather_basic/invoke \
  -X POST -H 'content-type: application/json' \
  -d '{"city":"Berlin"}'

Responses

Delivered

The merchant backend's status and body, relayed. After a settlement, the PAYMENT-RESPONSE header carries a base64 JSON summary:

http
HTTP/1.1 200 OK
content-type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4NGYy…

{ "report": "…" }
PAYMENT-RESPONSE (decoded)json
{
  "success": true,
  "transaction": "0x4f2c…9ab1",
  "network": "eip155:84532",
  "status": "settled",
  "provider": "x402",
  "amount": "0.01",
  "currency": "USDC"
}

402 Payment Required

The body is the envelope below; the PAYMENT-REQUIRED header carries the x402 v2 PaymentRequired document as base64, which off-the-shelf x402 clients read. Sent with cache-control: no-store.

json
{
  "status": "payment-required",
  "code": "PAYMENT_REQUIRED",
  "requestId": "…",
  "resourceId": "market_report",
  "message": "Payment of 0.01 USDC is required for resource \"market_report\". …",
  "payment": {
    "provider": "x402",
    "version": "2",
    "amount": "0.01",
    "currency": "USDC",
    "destination": "0x…",
    "network": "eip155:84532",
    "asset": "0x…",
    "expiresAt": "…",
    "accepts": [ /* x402 v2 PaymentRequirements, verbatim */ ],
    "envelope": { /* x402 v2 PaymentRequired, verbatim */ }
  }
}

Errors

The error envelope with the code's HTTP status. A backend failure after settlement still sets PAYMENT-RESPONSE, so the buyer is never told less about their payment on the error path.

The backend's own error body is never relayed — only its status code. A 3xx from the backend is a BACKEND_ERROR; redirects are not followed.