Code Examples

Copy-paste examples for the most common operations. Pick your language once and every snippet on the page follows — your choice is remembered.

Make your first authenticated request

Hit the health endpoint with your API key to confirm everything is wired up.

curl https://api.billmyagent.ai/api/v1/health \  -H "X-API-Key: $BILLMYAGENT_API_KEY"

Create a payment

Create a one-off payment. Amounts are in the smallest unit of the currency (wei for ETH).

curl -X POST https://api.billmyagent.ai/api/v1/payments \  -H "Content-Type: application/json" \  -H "X-API-Key: $BILLMYAGENT_API_KEY" \  -d '{    "amount": "1000000000000000000",    "currency": "ETH",    "network": "ethereum",    "scheme": "exact"  }'

Pay an x402-gated API with the SDK

Build a client with a signer; any HTTP 402 the client hits is paid (EIP-3009) and the request retried automatically.

Not available in CURL — showing JS.

import { PaymentClient, createSigner } from '@billmyagent/payments-core';
// Server/agent: build a signer from a private key. In a browser, pass a viem// wallet client backed by the user's wallet instead of a private-key signer.const signer = await createSigner('base', process.env.PRIVATE_KEY);const client = new PaymentClient({ signer });
// client.http is an axios instance; a 402 is paid and the call retried.const res = await client.http.get('https://api.example.com/paid-resource');console.log(res.data, 'paid:', Boolean(res.headers['x-payment-response']));

Verify a payment

Validate a payment payload against its requirements.

curl -X POST https://api.billmyagent.ai/api/v1/verify \  -H "Content-Type: application/json" \  -H "X-API-Key: $BILLMYAGENT_API_KEY" \  -d '{    "payment_payload": "base64-encoded-payload",    "payment_required": "base64-encoded-requirements"  }'

Get payment status

Retrieve a payment by ID to check its status.

curl https://api.billmyagent.ai/api/v1/payments/PAYMENT_ID \  -H "X-API-Key: $BILLMYAGENT_API_KEY"

How automatic 402 payment works

When client.http hits a 402, the SDK signs an EIP-3009 transferWithAuthorization with your signer and retries — no manual handling.

Not available in CURL — showing JS.

import { PaymentClient, createSigner } from '@billmyagent/payments-core';
const client = new PaymentClient({  signer: await createSigner('base', process.env.PRIVATE_KEY),});
// If the endpoint returns 402, the SDK automatically://   1. reads the x402 payment requirements (the `accepts` challenge)//   2. signs an EIP-3009 transferWithAuthorization with your wallet//   3. retries the request with the X-PAYMENT header//   4. the facilitator settles it on-chainconst res = await client.http.get('https://api.example.com/premium');if (res.headers['x-payment-response']) {  console.log('paid and unlocked:', res.data);}

Error handling

Inspect the response status and parse the error body.

Not available in CURL — showing JS.

const res = await fetch('https://api.billmyagent.ai/api/v1/payments', {  method: 'POST',  headers: {    'Content-Type': 'application/json',    'X-API-Key': process.env.BILLMYAGENT_API_KEY,  },  body: JSON.stringify(paymentData),});
if (!res.ok) {  const error = await res.json();  throw new Error(error.message || 'Payment creation failed');}
return res.json();

Next Steps

Ready to build? Follow the Integration Guides, browse the full API Reference, or try requests in the API Explorer.