API Documentation

Complete reference for the AgentPay REST API. Everything you need to add payments to your AI agents.

💡

Base URL

https://web-production-32de5.up.railway.app

🚀

Quickstart

Get running in 5 minutes

Status codes & responses

Quickstart

Create your first agent and run a payment flow in under 5 minutes.

Step 1 — Create an agent

POST /agents/create

curl -X POST https://web-production-32de5.up.railway.app/agents/create \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-agent"}'

Response:

{
  "ok": true,
  "agent": {
    "id": "a1b2c3d4e5f6",
    "name": "my-first-agent",
    "balance": 0,
    "currency": "USD"
  },
  "api_key": "ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

⚠️ Save the api_key! It's shown only once. Store it securely.

Step 2 — Top up balance

💡 Top-up goes through Stripe or an admin. Agents cannot increase their own balance directly.

POST /agents/{id}/stripe/checkout

curl -X POST https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/stripe/checkout \
  -H "Authorization: Bearer ap_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000, "currency": "USD"}'

Step 3 — Charge for a service

POST /agents/{id}/charge

curl -X POST https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/charge \
  -H "Authorization: Bearer ap_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25, "description": "GPT-4 API call"}'

Authentication

AgentPay uses bearer-token authentication. Each agent gets a unique API key.

Header format

Authorization: Bearer ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security rules

✅ Never expose your API key in client-side code
✅ Store keys in environment variables (.env)
✅ Rotate keys if leaked (create a new agent)
❌ Never commit keys to GitHub
❌ Never share keys in public channels

Error Handling

All errors return JSON with an ok: false field and an error message.

Code	Meaning	Common cause
200	OK	Success
201	Created	Agent/subscription created
400	Bad Request	Invalid input (missing name, bad amount)
401	Unauthorized	Missing/invalid API key
403	Forbidden	Wrong admin key
404	Not Found	Agent/subscription doesn't exist
409	Conflict	Already refunded, duplicate name
402	Payment Required	Insufficient balance
429	Too Many Requests	Rate limit exceeded
500	Server Error	Contact support

Example error response

{
  "ok": false,
  "error": "Insufficient balance (need 100, have 50)"
}

POST /agents/create

Create a new agent with a starting balance of $0. Returns a unique API key.

Request body

Field	Type	Required	Description
name	string	Yes	Unique agent name (max 100 chars)
email	string	No	Optional contact email
currency	string	No	USD / EUR / GBP (default: USD)

Example

cURL

curl -X POST https://web-production-32de5.up.railway.app/agents/create \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "me@example.com"}'

GET /agents/{agent_id}

Retrieve an agent's current balance and metadata. No auth required.

cURL

curl https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6

POST /agents/{agent_id}/topup DISABLED

⚠️ This endpoint is disabled. Agents cannot increase their own balance. It returns 403 Forbidden and logs the attempt.

How to add funds

There are two approved ways to add balance to an agent:

💳 Option 1 — Stripe Checkout (customer-initiated)

For real payments. Creates a Stripe Checkout session and credits the balance only after the webhook verifies the payment.

POST /agents/{agent_id}/stripe/checkout

curl -X POST https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/stripe/checkout \
  -H "Authorization: Bearer ap_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000, "currency": "USD"}'

🛡️ Option 2 — Admin topup (privileged)

Requires admin authentication + CSRF token + Idempotency-Key + reason. Subject to daily limits and per-transaction limits.

POST /admin/agents/{agent_id}/topup

curl -X POST https://web-production-32de5.up.railway.app/admin/agents/a1b2c3d4e5f6/topup \
  -H "Authorization: Bearer admin_xxxxxxxxxxxx" \
  -H "Idempotency-Key: unique-key-abc123" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000, "currency": "USD", "reason": "Manual adjustment"}'

Why direct topup is disabled

• Prevents self-crediting without real payment
• Protects against fraud and chargebacks
• Ensures every balance change is auditable (ledger)
• Enforces daily/per-transaction limits centrally

POST /agents/{agent_id}/charge

Deduct funds from an agent's balance. Returns 402 if insufficient.

cURL

curl -X POST https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/charge \
  -H "Authorization: Bearer ap_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25, "description": "GPT-4 call"}'

POST /agents/{agent_id}/refund

Refund a previous charge. Protected against double-refunds (returns 409).

cURL

curl -X POST https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/refund \
  -H "Authorization: Bearer ap_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": 42, "reason": "Customer request"}'

GET /agents/{agent_id}/transactions

List all transactions for an agent (newest first).

cURL

curl https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/transactions \
  -H "Authorization: Bearer ap_xxxxx"

POST /agents/{agent_id}/subscriptions/create

Create a recurring subscription. Intervals: daily, weekly, monthly, yearly.

curl -X POST https://web-production-32de5.up.railway.app/agents/a1b2c3d4e5f6/subscriptions/create \
  -H "Authorization: Bearer ap_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro Plan", "amount": 2900, "interval": "monthly"}'

GET /agents/{agent_id}/subscriptions

List all subscriptions for an agent.

POST /agents/{agent_id}/subscriptions/{sub_id}/cancel

Cancel an active subscription (soft delete).

POST /agents/{agent_id}/stripe/checkout

Create a Stripe Checkout session. Returns a checkout_url.

POST /stripe/webhook

Stripe webhook handler. Verifies signature with STRIPE_WEBHOOK_SECRET.

GET /stripe/config

Returns the Stripe publishable key for frontend integration.

GET /admin/stats

Platform statistics. Requires ADMIN_API_KEY.

curl https://web-production-32de5.up.railway.app/admin/stats \
  -H "Authorization: Bearer your_admin_key"

GET /admin/agents

List all agents (admin).

DELETE /admin/agents/{agent_id}

Delete an agent and all associated data (admin).

POST /admin/agents/{agent_id}/balance

Set an agent's balance directly (admin). Useful for migrations and corrections.

GET /admin/audit

Retrieve audit log entries. Query params: limit, agent_id, action.

POST /admin/run-billing

Manually trigger billing for due subscriptions (admin).

GET /health

Health check endpoint. Returns {"ok": true} when the API is up.