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": "base",    "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

Payment Intents / Payment Links

Create a payment intent to get a shareable hosted checkout_url. A buyer opens the link, connects a wallet, and pays USDC on-chain; funds settle directly to your payout wallet (strictly non-custodial). Links are single-use, expire (default 7 days, max 30), and are non-refundable (refunds are handled merchant↔buyer off-platform). Settlement is on base and polygon (USDC), plus base-sepolia for testing — Ethereum is not currently supported. These endpoints use X-API-Key auth.

POST/payment-intents

Create a payment intent and get a hosted checkout URL

Request Body:

{  "amount": "25.00",  "network": "base",  "currency": "USDC",  "description": "Pro plan — March",  "metadata": { "order_id": "order_123" },  "expires_in_seconds": 604800,  "idempotency_key": "unique-key-123"}

Field Descriptions:

amount (string, required): Decimal string, range [0.01, 1000000]
network (string, required): base, base-sepolia, or polygon
currency (string, optional): Defaults to USDC
description (string, optional): Shown on the checkout page
metadata (object, optional): Key-value pairs echoed back on the intent
expires_in_seconds (integer, optional): Default 604800 (7 days), max 2592000 (30 days)
idempotency_key (string, optional): Prevents duplicate intents

Response (201 Created):

{  "id": "550e8400-e29b-41d4-a716-446655440000",  "amount": "25.00",  "currency": "USDC",  "network": "base",  "scheme": "exact",  "recipient": "0x...",  "status": "requires_payment",  "description": "Pro plan — March",  "metadata": { "order_id": "order_123" },  "tx_hash": null,  "payer": null,  "checkout_url": "https://api.billmyagent.ai/checkout/550e8400-e29b-41d4-a716-446655440000",  "expires_at": "2026-07-08T20:00:00Z",  "created_at": "2026-07-01T20:00:00Z",  "settled_at": null,  "canceled_at": null}

Status values: requires_payment → processing → settled, or expired / canceled.

Returns 422 no_payout_address if you have no payout address configured for that network. Set one via PUT /merchant/payout-settings.

GET/payment-intents/:id

Retrieve a payment intent by ID (poll status for settled)

GET/payment-intents

List your payment intents

POST/payment-intents/:id/cancel

Cancel an unpaid intent. Sets status to canceled and invalidates its link

Authentication Endpoints

POST/auth/register

Request Body:

{  "email": "[email protected]",  "password": "secure-password",  "name": "John Doe",  "organization": "Acme Corp"}

POST/auth/login

Request Body:

{  "email": "[email protected]",  "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.