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();

Payment Links / Hosted Checkout

Create a payment intent to get a shareable hosted checkout_url, then poll getPaymentIntent until status is settled. Funds settle directly to your payout wallet (non-custodial, USDC on Base or Polygon). Links are single-use, expire (default 7 days, max 30), and are non-refundable — refunds are handled merchant↔buyer off-platform.

Node

import { PaymentClient } from '@billmyagent/payments-core';
const client = new PaymentClient({ apiKey: process.env.BILLMYAGENT_API_KEY });
// 1. Create the intent and share the hosted checkout link.const intent = await client.createPaymentIntent({  amount: '25.00',   // decimal string, [0.01, 1000000]  network: 'base',   // 'base' | 'base-sepolia' | 'polygon'  description: 'Pro plan — March',});console.log('Send this link:', intent.checkout_url); // client.getCheckoutUrl(intent.id)
// 2. Poll until settled (or use webhooks).async function waitForSettlement(id) {  for (;;) {    const current = await client.getPaymentIntent(id);    if (current.status === 'settled') return current;    if (current.status === 'expired' || current.status === 'canceled') {      throw new Error(current.status);    }    await new Promise((r) => setTimeout(r, 5000));  }}await waitForSettlement(intent.id);

Python

import os, timefrom billmyagent import PaymentClient
client = PaymentClient(api_key=os.environ['BILLMYAGENT_API_KEY'])
# 1. Create the intent and share the hosted checkout link.intent = client.create_payment_intent(    amount='25.00',   # decimal string, [0.01, 1000000]    network='base',   # 'base' | 'base-sepolia' | 'polygon'    description='Pro plan — March',)print('Send this link:', intent['checkout_url'])  # client.checkout_url(intent['id'])
# 2. Poll until settled (or use webhooks).while True:    current = client.get_payment_intent(intent['id'])    if current['status'] == 'settled':        break    if current['status'] in ('expired', 'canceled'):        raise RuntimeError(current['status'])    time.sleep(5)

Next Steps

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