Testnet: https://xapg.io · Mainnet: https://mainnet.xapg.io. Use credentials issued for the selected environment; read /payment-environment-config before signing.
Agent payment approval API
Wallet Demo calls POST /verify and POST /settle. For external x402 resources, xAPG forwards the signed payment; the merchant owns verification and settlement.
Approval accepted.scheme must be exact. paymentRoute defaults to external_x402; use xapg_resource only for XAPG Testnet resources.
| Endpoint | Body | Result |
|---|---|---|
POST /agent/approvals | resourceUrl, accepted, paymentRoute? | Creates an approval; returns id and wallet request state |
GET /agent/approvals/:id | — | Reads status, readyToResume and walletRequestStatus |
POST /agent/approvals/:id/signature | paymentPayload | Approves after validating the wallet signature |
POST /agent/approvals/:id/reject | reason? | Rejects a pending approval |
POST /agent/approvals/:id/consume | — | Returns paymentPayload once |
Each Agent payment requires wallet approval and a payment-specific signature. Testnet uses Base Sepolia and test USDC; Mainnet uses Base and real USDC. Agent API keys, OAuth or browser sessions authenticate approval reads and create/reject/consume. Browser mutations require CSRF; payment signature submission requires a browser session. Institution API keys do not authenticate these routes.
Approval request and continuation
POST /agent/approvals
Authorization: Bearer <AGENT_API_KEY_OR_OAUTH_TOKEN>
Content-Type: application/json
{
"resourceUrl": "https://merchant.example/resource",
"accepted": "<complete exact requirements from merchant>",
"paymentRoute": "external_x402"
}Structure only: accepted must be an object, not the placeholder string. The server returns HTTP 201 with id, status, expiresAt, approvalUrl, walletRequestStarted, walletRequestStatus, walletSession, continuationMode and paymentRoute. Save id; poll GET /agent/approvals/:id with backoff. Resume only when readyToResume is true, then consume once and persist the returned paymentPayload before forwarding it to the merchant.
Consume returns id, resourceUrl, accepted, paymentPayload and paymentRoute. HTTP 409 means pending or unavailable; HTTP 422 reports wallet approval failure. A lost consume response requires reconciliation with the saved approval; creating a new approval can release another authorization. Consume is authorization release, not proof of payment or merchant delivery.