API documentation

Product overview

AgentPay is a pay-per-request payment protocol for autonomous AI agents and APIs. Providers register services with a per-request price in stroops; agents call those services and every call is metered. Outstanding usage is billed and settled on Stellar through a Soroban escrow contract, giving both sides an auditable, low-fee settlement layer.

Architecture

Dashboard
This Next.js app. Manages services, API keys, webhooks and shows usage, events and stats.
Backend API
Express gateway for metering, billing quotes, audit log, webhooks and settlement orchestration.
Escrow contract
Soroban contract on Stellar that records usage, applies pricing tiers and settles balances.

Flow: agent → backend usage endpoint /api/v1/usage → usage counters → billing quote → settlement mirrored on-chain in the escrow contract.

How to use

Register a service by posting to /api/v1/services {"serviceId":"infer","priceStroops":100}
Record usage for an agent by posting to /api/v1/usage {"agent":"G…","serviceId":"infer","requests":3}
Inspect usage and billing from the Usage, Agents and Stats pages.
Subscribe to events with Webhooks and issue credentials under API Keys.

Full interactive reference: https://agentpay-backend-red.vercel.app/docs. Backend base URL: https://agentpay-backend-red.vercel.app.

Deployments

Stellar testnet

Network: Stellar testnet
Escrow contract: CAWQI63R…TLCAMXNU
Backend API: agentpay-backend-red.vercel.app
API reference: /docs /health

Escrow contract ID CAWQI63RISS2AXF2YSH77RQGUMVMXIAJUIDBW4DTVSTYU2L5TLCAMXNU — view on stellar.expert. Source: contracts, backend, frontend.

Endpoints

Companion to GET /api/v1/openapi.json — short prose for the most common endpoints.

For the complete request/response contract of every endpoint the dashboard calls, see the dashboard API integration reference.

For the hook contract itself, see the useApi FetchState reference.

POST /api/v1/usage: Record incremental usage for an (agent, serviceId) pair. Body: { agent, serviceId, requests }.
GET /api/v1/usage/:agent/:serviceId: Read the accumulated request total. Returns { agent, serviceId, total }.
POST /api/v1/settle: Drain the accumulator and return { requests, priceStroops, billedStroops }.
POST /api/v1/services: Register a service with priceStroops/request. Idempotent.
POST /api/v1/admin/{pause,unpause}: Toggle the global pause flag; GET /admin/status to read.

API documentation

Product overview

Architecture

Dashboard
This Next.js app. Manages services, API keys, webhooks and shows usage, events and stats.
Backend API
Express gateway for metering, billing quotes, audit log, webhooks and settlement orchestration.
Escrow contract
Soroban contract on Stellar that records usage, applies pricing tiers and settles balances.

Flow: agent → backend usage endpoint /api/v1/usage → usage counters → billing quote → settlement mirrored on-chain in the escrow contract.

How to use

Register a service by posting to /api/v1/services {"serviceId":"infer","priceStroops":100}
Record usage for an agent by posting to /api/v1/usage {"agent":"G…","serviceId":"infer","requests":3}
Inspect usage and billing from the Usage, Agents and Stats pages.
Subscribe to events with Webhooks and issue credentials under API Keys.

Full interactive reference: https://agentpay-backend-red.vercel.app/docs. Backend base URL: https://agentpay-backend-red.vercel.app.

Deployments

Stellar testnet

Network: Stellar testnet
Escrow contract: CAWQI63R…TLCAMXNU
Backend API: agentpay-backend-red.vercel.app
API reference: /docs /health

Escrow contract ID CAWQI63RISS2AXF2YSH77RQGUMVMXIAJUIDBW4DTVSTYU2L5TLCAMXNU — view on stellar.expert. Source: contracts, backend, frontend.

Endpoints

Companion to GET /api/v1/openapi.json — short prose for the most common endpoints.

For the complete request/response contract of every endpoint the dashboard calls, see the dashboard API integration reference.

POST /api/v1/usage

Record incremental usage for an (agent, serviceId) pair. Body: { agent, serviceId, requests }.

curl -X POST "https://agentpay-backend-red.vercel.app/api/v1/usage"   -H "Content-Type: application/json"   -d '{"agent":"agent-id","serviceId":"service-id","requests":1}'

GET /api/v1/usage/:agent/:serviceId

Read the accumulated request total. Returns { agent, serviceId, total }.

curl "https://agentpay-backend-red.vercel.app/api/v1/usage/agent-id/service-id"

POST /api/v1/settle

Drain the accumulator and return { requests, priceStroops, billedStroops }.

curl -X POST "https://agentpay-backend-red.vercel.app/api/v1/settle"   -H "Content-Type: application/json"   -d '{"agent":"agent-id"}'

POST /api/v1/services

curl -X POST "https://agentpay-backend-red.vercel.app/api/v1/services"   -H "Content-Type: application/json"   -d '{"name":"my-service","priceStroops":100}'

POST /api/v1/admin/{pause,unpause}

Toggle the global pause flag; GET /admin/status to read.

curl -X POST "https://agentpay-backend-red.vercel.app/api/v1/admin/pause"