AgentPay logoAgentPay
Discord

API Reference

The AgentPay API is a RESTful service that handles API key creation, wallet lifecycle, payment execution for 402 flows, and spend history. The base URL for the hosted service is https://api.agentpay.solutions; for self-hosted deployments use your own API URL. Authentication is via the X-Api-Key header for all endpoints except health and API key creation.

Authentication

Include your API key on every request that requires authentication: X-Api-Key: pk_.... The key is created once via POST /api-keys or from the dashboard. See API Keys for creation and security practices.

Endpoints

MethodPathAuthDescription
GET/—Simple health: { "ok": true, "service": "agentpay-api" }
GET/health—Detailed status: database, facilitator, RPC configuration
POST/api-keys—Create API key. Body: label (optional), key (optional). With X-Internal-Secret, body may include organization_id and plan for payment limits. Returns id, label, key (plaintext once).
GET/wallets/meX-Api-KeyList wallets for the authenticated key. Returns { "wallets": [...] }.
POST/walletsX-Api-KeyCreate wallet. Body: { "network": "base" }. Returns id, wallet_id, network, address (when CDP configured).
DELETE/wallets/:idX-Api-KeyDelete a wallet by id. Returns 204 or 404 if not found.
POST/v1/payX-Api-KeyExecute payment for 402. Body: paymentRequiredHeader (required), requestUrl, idempotencyKey. Returns paymentSignature, settled, transaction.
GET/v1/spendX-Api-KeyList spend events. Query: limit (optional, default 100, max 500). Returns { "events": [...] }.

Errors

Failed requests return an appropriate HTTP status and a JSON body with an error string. 402 responses may include a facilitator object with details from the x402 facilitator. 429 is returned when the monthly payment limit for the key's plan is reached (body includes upgradeUrl). For a full list of status codes and troubleshooting, see Errors & troubleshooting.

Related