API Reference

Base URL

All API requests should be made to:

http://localhost:3001/api/v1

Authentication

Include your API key in the request header:

X-API-Key: your-api-key-here

HTTP 402 Payment Required

Some endpoints may return 402 Payment Required when payment is needed to access the resource. The response includes payment instructions that can be used to complete the payment.

402 Response Format:

{
  "error": "Payment Required",
  "message": "Payment required to access this endpoint",
  "payment_required": "base64-encoded-payment-required",
  "payment_instruction": {
    "amount": "1.00",
    "currency": "USDC",
    "network": "ethereum",
    "scheme": "exact",
    "recipient": "0x...",
    "token_contract": "0x...",
    "expires_at": "2024-01-01T00:00:00Z"
  },
  "retry_url": "/api/v1/endpoint?payment_id=..."
}

Note: Our SDKs automatically handle 402 responses when configured with a wallet adapter. They will prompt for payment signing and retry the request automatically.

Endpoints

POST/payments

Create a new payment

Request Body:

{
  "amount": "1000000000000000000",
  "currency": "ETH",
  "network": "ethereum",
  "scheme": "exact",
  "payment_payload": "...",
  "payment_required": "..."
}

GET/payments/:id

Retrieve payment details by ID

POST/verify

Verify a payment payload

Request Body:

{
  "payment_payload": "base64-encoded-payload",
  "payment_required": "base64-encoded-requirements"
}

GET/health

Health check endpoint

Authentication Endpoints

POST/auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "secure-password",
  "name": "John Doe",
  "organization": "Acme Corp"
}

POST/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "secure-password"
}

GET/auth/me

Get current user (requires Bearer token)

Headers:

Authorization: Bearer <jwt-token>

API Key Management

POST/api-keys

Create a new API key (requires Bearer token)

Headers:

Authorization: Bearer <jwt-token>

Request Body:

{
  "name": "Production API Key"
}

GET/api-keys

List your API keys (requires Bearer token)

Headers:

Authorization: Bearer <jwt-token>

GraphQL API

In addition to REST endpoints, BillMyAgent also provides a GraphQL API at:

http://localhost:3001/graphql

Response Format

All successful responses follow this format:

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}