Skip to main content
Want an AI agent to pay for an API call? Protect a route with x402: your server returns an HTTP 402 with the price and payment requirements, the buyer authorizes payment, and your server uses a facilitator to verify and settle it before delivering the resource. PayAI lets you start accepting ordinary exact payments on Mainnet without creating a portal account or obtaining an API key. You supply a receiving wallet and the route you want to charge for. The free allowance gets the integration started; an agent can later buy credits and a key programmatically, without sending a human through signup.

​
Choose the shortest path to a working payment

For a first integration, choose one network, one asset and one route. The Base example charges 0.01 USDC (10000 atomic units); the Solana example charges 0.001 USDC (1000 atomic units). Keep the buyer’s explicit cap equal to the intended price. Do not raise it silently.

​
x402, Stripe, or both?

Use x402 when an agent needs to buy a bounded API call, tool action, data result or other HTTP resource. Keep your existing commerce stack for carts, subscriptions, tax, refunds, fulfillment and customer billing. They can coexist: continue using Stripe or another processor for human and customer commerce, and add x402 only to machine-facing routes that benefit from per-request payment. Stripe describes support for both MPP and x402 in its machine-payments overview. PayAI’s route in this guide is x402; this page does not claim that PayAI implements MPP.

​
What you need—and what you do not

  • A receiving wallet address. Keep its private key out of the API server unless a specific feature requires signing.
  • The framework integration for your service, and a price for each paid operation.
  • A disposable, funded buyer wallet to verify the complete flow. A 402 response alone does not prove a payment settled.
  • On Solana, the merchant’s USDC associated token account (ATA) must exist. Creating it requires a setup fee payer with SOL. PayAI sponsors settlement gas; account setup and later recovery transfers are separate operations.
You do not need a PayAI portal signup or facilitator API key for the ordinary exact starter flow. Do not add a signup step just because an SDK supports credentials. The current starter allowance is 1,000 lifetime free credits per new receiving wallet, subject to shared host/IP limits. This is a credit allowance, not a promise of 1,000 settlements. Rates depend on settlement gas plus 30%; see pricing and the live /supported response. Testnets are free.

​
Add payments without rebuilding your application

  1. Choose a bounded operation: a report, lookup, inference request or premium API response.
  2. Apply x402 middleware to that route. Leave health checks and public documentation free.
  3. Configure the receiving address, network, asset and price. Connect the standard x402 facilitator client to PayAI using the @payai/facilitator package, or the equivalent configuration in your language.
  4. Keep existing API keys and subscriptions for existing customers. Offer x402 as another access path; do not remove authorization from private data or user-specific operations.
  5. Deploy the service over HTTPS and run the paid-path checks below.
For protocol context, use the official x402 seller quickstart and facilitator directory. PayAI already appears in both; these links are upstream references, not a separate PayAI protocol. Payment proves payment, not permission to access another customer’s data. For long-running jobs or requests with side effects, make job creation and delivery idempotent. Do not blindly authorize another payment after a timeout.

​
Prove the paid path, not just the implementation

The runnable Base and Solana examples include guarded smoke buyers and reconciliation commands. Before calling an integration complete, retain evidence of:
  • An unpaid request returning 402 with the expected recipient, asset, network and price.
  • A buyer authorization within an explicit spending cap.
  • A successful paid HTTP response and the matching finalized on-chain settlement with the exact asset, payer, recipient and amount. Balance-delta reporting is additional evidence when the chain and RPC can provide it accurately.
  • Recovery of disposable test funds, where you control both wallets. Recovery has its own network fee; a merchant refund is not automatic.
If the HTTP response is lost, reconcile the original authorization before trying again. Follow capacity and settlement recovery; do not treat an ambiguous response as a failed payment.

​
Scale without a signup handoff

When the starter allowance is no longer enough, an agent can buy a facilitator key and credits over x402. The paying wallet becomes the account identity: no pre-created portal account is required, although a wallet-owned account is created by vending. Store the returned secret immediately and configure server authentication. Vending starts at $1 and purchased credits are non-refundable. A wallet already linked to a human portal account receives credits only; manage its keys in that portal. The portal remains an optional interface for people who want it.

​
Make your paid API discoverable

Publish clear route descriptions, input/output schemas, pricing and a working example. Add the Bazaar discovery extension so compatible agents can discover the resource. This helps an agent understand what it can buy; it does not guarantee search placement or traffic. If a coding agent is implementing the integration, give it this guide and the Build with AI entry point. They lead to framework-specific instructions and machine-readable documentation without changing the application’s requirements.