AgentPay logoAgentPay
Discord

Architecture overview

AgentPay is built as a REST API plus optional dashboard and official SDKs. This section describes how the pieces fit together and how data flows from your agent to settlement on-chain.

Components

  • AgentPay API — Fastify-based REST service. Handles API key creation, wallet lifecycle, and the POST /v1/pay flow. Optionally backed by PostgreSQL (Supabase) for persistence of keys, wallets, and spend events.
  • x402 facilitator — External service (e.g. OpenFacilitator) that performs verification and settlement of payments. The API forwards payment payloads to the facilitator's /verify and /settle endpoints.
  • Dashboard — Next.js app with NextAuth (GitHub). Multi-tenant: each user gets an API key; keys and spend are scoped per user. Connects to the same database as the API for user and key storage.
  • SDKs — TypeScript and Python clients that wrap HTTP with 402 interception: on 402, they call the AgentPay API to pay, then retry the original request with the returned signature.

Request flow (paying a 402 API)

  1. Your agent uses the SDK to call a paid API (e.g. client.get(url)).
  2. The paid API responds with 402 and a Payment-Required header (base64-encoded requirements).
  3. The SDK sends the header and request URL to POST /v1/pay with your X-Api-Key.
  4. The API resolves your API key, loads a wallet for the required network (e.g. Base), and builds a payment payload. It calls the facilitator's /verify then /settle.
  5. On success, the API records a spend event (if DB is configured) and returns paymentSignature. The SDK retries the original request with this signature; the paid API returns 200.

Data and persistence

With DATABASE_URL set, the API stores API keys (hashed), wallets (per key and network), and spend events. The dashboard uses the same database for users, sessions, and encrypted API keys. Without a database, key and wallet creation may still work in memory for development, but persistence and spend history are not guaranteed—see your deployment guide for details.

Networks and assets

Currently the stack targets Base and USDC. The facilitator and payment requirements (e.g. network, asset) determine the exact contract and settlement flow. Custom domains and alternate facilitators are supported via environment configuration on the API.