Charging AI agents per API call with x402 on Solana: notes from building Rugsight

October 31, 2026 · 3 min read · by the Rugsight team

Rugsight has two kinds of customers: people who paste a token into a web page, and AI agents that call an API before they buy, swap or recommend a Solana token. People can pay 1 USDC with Solana Pay. For agents, we wanted something with no sign-up, no API key and no monthly plan. We used x402: the server answers 402 Payment Required with a price, and the client pays in the next request.

This post covers how the flow works on Solana, what we chose, and the things that tripped us up. It's written for developers; there's nothing to buy here.

The flow

The agent calls GET /api/v1/report?mint=<mint> with no payment.
The server returns HTTP 402. For x402 v2, the payment requirements go in a base64 JSON PAYMENT-REQUIRED header; we also return the v1 JSON body for older clients. The requirements say: scheme exact, network Solana mainnet, asset USDC, amount 30000 (0.03 USDC in 6-decimal units), and the address to pay.
The client builds a Solana transaction that transfers exactly that amount of USDC, signs it as the payer, and resends the request with the payload in a PAYMENT-SIGNATURE (v2) or X-PAYMENT header.
The server asks a facilitator to /verify the payload.
If it's valid, the server builds the report.
Only then does it ask the facilitator to /settle, which submits the transaction on-chain.
The server returns 200 with the report and a PAYMENT-RESPONSE receipt header.

The order of steps 5 and 6 matters. If the report can't be built (an RPC outage, an invalid mint), we never settle, so the agent is never charged for an error. Verify first, do the work, settle last.

Why a facilitator

On Solana, the facilitator can also be the fee payer: it co-signs and pays the SOL network fee, so the agent's wallet only needs USDC. That removes the most common onboarding failure ("you need SOL for gas"). We use the PayAI facilitator; its fee-payer address is part of the payment requirements so the client can build the transaction correctly.

The facilitator also checks things you don't want to re-implement: that the transfer instruction matches the requirements, that the amount and mint are right, and that the transaction will simulate.

Things that went wrong

The pay-to token account didn't exist. On Solana, USDC goes to the treasury's associated token account (ATA), not the wallet itself. Our treasury had never held USDC, so its ATA didn't exist, and every payment failed at simulation. The fix is just to create the account (send any amount of USDC to it once), but nothing in the 402 response tells a client why it failed. We now expose x402PayToReady in /api/health, so the problem shows up before a customer finds it.

Local pre-checks save facilitator calls. Before calling /verify we decode the transaction and check the obvious things ourselves: the right program, mint, destination and amount. Garbage payloads get a fast 402 with a clear error instead of a round trip.

v1 and v2 clients both exist in the wild. Supporting both headers and both body formats cost a few dozen lines and avoided a lot of "it doesn't work with my client" debugging.

Discovery is half the product. An API that agents can pay for is useless if agents can't find it. We publish /.well-known/x402, an OpenAPI document with the price on each paid route, llms.txt, and an MCP server with a free tool and a paid tool. The 402 response also carries a bazaar extension with input and output schemas, which facilitator directories use to list services after their first settled payment.

Pricing

0.03 USDC per report is low enough that an agent can check every token it touches, and high enough to cover the RPC and market-data calls behind a full report. The basic score (grade, verdict, flag codes) stays free at /api/score/<mint>, so an agent can triage for free and only pay when it needs the detail.

Try it

Free score: curl https://rugsight.rugsight.workers.dev/api/score/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
See the 402: curl -i "https://rugsight.rugsight.workers.dev/api/v1/report?mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
Clients: npm i rugsight, pip install rugsight, and Vercel AI SDK tools. The source is on GitHub (MIT).

If you're building an agent that trades or recommends Solana tokens, the docs show how to plug in a payment-aware fetch.

Rugsight is an automated technical tool. Not financial advice.