Quickstart

Go from zero to a verified payment in about five minutes. Pick your language below — it applies to every snippet.

  1. 1. Get an API key

    Create a free account and generate a key in the Admin Portal. See Get API Key for the full walkthrough. Keys look like sk_live_… — store it as an environment variable:

    export BILLMYAGENT_API_KEY=sk_live_your_key_here

  2. 2. Make your first authenticated request

    Confirm your key works by calling the health endpoint.

    Make your first authenticated request

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

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

  3. 3. Create a payment

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

    Create a payment

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

    Shell
    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"  }'

  4. 4. Let the SDK handle 402 for you

    When an endpoint requires payment it returns 402 Payment Required. With a signer configured, the SDK signs and retries automatically — no manual payload juggling.

    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.

    JavaScript
    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);}

  5. 5. Create a payment link

    No checkout UI to build? Create a payment intent and share the hosted checkout_url. The buyer connects a wallet and pays USDC on-chain; funds settle directly to your payout wallet (non-custodial). Set a payout address for the network first, or you'll get 422 no_payout_address. Then poll getPaymentIntent until status is settled.

    Shell
    curl -X POST https://api.billmyagent.ai/api/v1/payment-intents \  -H "Content-Type: application/json" \  -H "X-API-Key: $BILLMYAGENT_API_KEY" \  -d '{ "amount": "25.00", "network": "base", "description": "Pro plan" }'
# → 201 with a "checkout_url" — send that link to your buyer.

Next steps