API Reference

Base URL

All API requests should be made to:

https://api.billmyagent.ai/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 signer. They sign the payment 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>

Merchant Payout & Fees

BillMyAgent is non-custodial: payments settle directly to a payout wallet address you configure, so you receive 100% on-chain. The 1% platform fee is recorded as you transact and billed monthly via an invoice you pay separately. These endpoints require a Bearer (JWT) token.

GET/merchant/payout-settings

Get your payout addresses (per network) and current fee rate

Headers:

Authorization: Bearer <jwt-token>

PUT/merchant/payout-settings

Set one or more payout wallet addresses. Only the fields you send are changed.

Headers:

Authorization: Bearer <jwt-token>

Request Body:

{  "ethereum_address": "0x...",  "polygon_address": "0x...",  "base_address": "0x..."}

GET/merchant/fees

Your accrued platform-fee ledger plus a per-currency/status summary

Headers:

Authorization: Bearer <jwt-token>

GET/merchant/invoices

List your fee invoices (open, paid, overdue)

Headers:

Authorization: Bearer <jwt-token>

GET/merchant/invoices/:id

Invoice detail, plus an x402 payment instruction to pay it (for open/overdue invoices)

Headers:

Authorization: Bearer <jwt-token>

GraphQL API

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

https://api.billmyagent.ai/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"}

Try these endpoints interactively in the API Explorer.