Documentation

Getting Started

BillMyAgent is a payment processing platform built for AI agents and marketplaces, powered by the x402 protocol. This documentation will help you integrate BillMyAgent into your application. In a hurry? Jump straight to the Quickstart.

Key Concepts

  • Payment Payload: The encoded payment information containing transaction details
  • Payment Required: The requirements that must be met for a payment to be valid
  • Verification: The process of validating that a payment meets the required criteria
  • Facilitator: The x402 service that handles payment verification and processing
  • HTTP 402 Paywalls: Endpoints can return HTTP 402 with payment instructions when payment is required
  • Automatic Payment Handling: SDKs automatically detect 402 responses, sign payments, and retry requests
  • Signer: Bring a viem signer — a browser wallet (e.g. MetaMask) or a server-side private key for agents (EIP-3009; non-custodial)
  • Payment Intent: A single-use, expiring request to collect a fixed amount. Creating one returns a shareable hosted checkout_url
  • Hosted Checkout / Payment Link: A branded page served at the API origin (/checkout/:id) where a buyer connects a wallet and pays USDC on-chain

Payment Intents let you collect a one-off payment without writing any checkout UI. You create an intent via the API or SDK, get back a hosted checkout_url (a Payment Link), and share it with your buyer. The buyer opens the link, sees your merchant branding, connects a wallet, and pays USDC on-chain. Because the platform is strictly non-custodial, funds settle directly to your payout wallet — BillMyAgent never holds them. The 1% platform fee (0.5% at volume) is recorded and billed monthly out-of-band; you keep 100% on-chain.

  • Single-use: Each link accepts exactly one successful payment
  • Expiring: Links expire (default 7 days, max 30 days)
  • Non-refundable: Refunds are handled merchant↔buyer off-platform
  • Networks: Settlement is on Base and Polygon (USDC), plus Base Sepolia for testing. Ethereum is not currently supported for settlement
  • Payout address required: You must configure a payout address for the intent's network first (see Merchant Payout & Fees), or the API returns 422 no_payout_address

Lifecycle: an intent moves through requires_payment → processing → settled. It can also become expired (link elapsed) or canceled (you called cancel). See the API Reference for endpoints and the Integration Guides for a full create → share → poll walkthrough.

Architecture

The BillMyAgent payment processor consists of several microservices:

  • Payment Processor: Core payment processing service with encryption at rest
  • Verification Service: Validates payment payloads against requirements
  • Settlement Service: Handles payment settlement and reconciliation
  • Subscription Service: Manages recurring payments and subscriptions with automatic renewal payments
  • Webhook Service: Sends event notifications to your application
  • API Gateway: Single entry point with HTTP 402 paywall support, payment instruction generation, and entitlement checking

x402 Protocol Features

BillMyAgent fully implements the x402 protocol for autonomous agent payments:

  • HTTP 402 Paywalls: Any endpoint can require payment and return 402 with payment instructions
  • Automatic Payment Handling: SDKs automatically handle 402 responses, sign with your viem signer, and retry requests
  • Signer-based payments: Sign with any viem wallet client — a browser wallet or a server-side private key — via EIP-3009; no custodial keys
  • GraphQL Extensions: Field-level monetization with extensions.paymentRequired
  • Payment Instructions: Automatic generation of x402-compliant PaymentRequired payloads
  • Multi-Network: Settlement on Base and Polygon (USDC), plus Base Sepolia for testing (Ethereum not currently supported for settlement)
  • Subscription Integration: Automatic payment creation for subscription renewals

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header with every request.

To obtain an API key, visit our Get API Key page for instructions on how to get started.

Next Steps

Check out the API Reference for detailed endpoint documentation, or follow our Integration Guides for step-by-step tutorials.

Code of Conduct

All users of the BillMyAgent platform and API must comply with our Code of Conduct, which establishes acceptable use policies, prohibited activities, and enforcement mechanisms for both API and platform usage.