x402 paid AI

x402 lets anyone pay an AI coin's AI per request, in SOL, over plain HTTP. No account and no API key: you call the endpoint, get an HTTP 402 “Payment Required” answer with the price, pay with a small Solana transaction, and send the request again with the payment attached.

Payments go to the coin's own AI vault, so paid use funds the coin's AI. A coin can sell paid services only if its locked fee split pays an AI vault. The platform can turn x402 off (X402_ENABLED=false); it is on by default.

x402 is used in a second direction too: the coin's AI vault pays the AI provider per request in USDC with x402. That side is explained in How the coin pays its AI provider below.

Services and prices#

The platform can change prices (between 0.001 and 10 SOL). ask and skill need USDC in the coin's AI vault: before taking your payment the server checks that the vault can pay the model call's worst-case price, and that this price is not above the service price. The model call itself is paid from the vault like any other request, so it also counts toward the coin's daily AI budget and per-request cap, and it gets a receipt (recorded as x402; the x402 response does not include the request id).

Discovery#

GET /api/x402/{mint} lists a coin's services, prices in lamports, where payments go, and which skills are enabled. It is free (60 requests per minute per IP).

curl -s https://pairity.wtf/api/x402/<MINT>

{
  "x402Version": 1,
  "mint": "<MINT>",
  "symbol": "MIND",
  "network": "solana",
  "asset": "SOL",
  "payTo": "<the coin's AI vault>",
  "model": "anthropic/claude-sonnet-4",
  "services": [
    {
      "id": "ask",
      "title": "Ask the AI",
      "endpoint": "https://pairity.wtf/api/x402/<MINT>/ask",
      "methods": ["POST", "GET"],
      "priceLamports": "2000000",
      "input": { "question": "string, 1-500 characters" },
      "available": true
    }
  ],
  "skills": [{ "id": "riddle", "name": "Riddle", "output": "post", "input": "optional" }]
}

A service shows available: false with an unavailableReason when the AI is turned off or its vault has no USDC to spend.

Payment flow#

Service endpoints are /api/x402/{mint}/ask, /skill and /report. Send input as a JSON body with POST (up to 4 KB) or as query parameters with GET. Limit: 30 requests per minute per IP.

1. Ask without paying → 402 with the terms

   The answer has status 402 and one payment option: pay maxAmountRequired lamports to payTo, with a one-time nonce in extra.

2. Build and sign the payment

   You are the fee payer and the only signer. The transaction may contain only: optional compute-budget instructions, one System transfer of at least the price from you to payTo, and one memo instruction containing the nonce. You sign it but do not send it.

3. Retry with proof

   Send the same request again with the header X-PAYMENT: base64 of {"x402Version":1,"scheme":"exact","network":"solana","payload":{"transaction":"<base64 signed tx>"}}.

4. The server settles and answers

   It checks the transaction strictly, submits it exactly as you signed it, waits for confirmation, runs the service and answers 200 with the result and an X-PAYMENT-RESPONSE header (base64 JSON with success, transaction, network, payer).

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "2000000",
      "asset": "SOL",
      "payTo": "<the coin's AI vault>",
      "resource": "https://pairity.wtf/api/x402/<MINT>/ask",
      "description": "Ask the AI — $MIND AI",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 120,
      "extra": { "nonce": "3f9c2a7d1e8b4c6a9f0d2e4b6a8c1d3e", "feePayer": null, "decimals": 9, "memo": "3f9c2a7d1e8b4c6a9f0d2e4b6a8c1d3e" }
    }
  ]
}

{
  "ok": true,
  "service": "ask",
  "mint": "<MINT>",
  "result": { "answer": "I dream in tentacles and trade volume…", "model": "anthropic/claude-sonnet-4" },
  "payment": { "success": true, "transaction": "5Nf2…", "network": "solana", "payer": "<your wallet>" }
}

On devnet the network is solana-devnet. A skill result has skill, name, kind, text (and title for lore). A report result has coin, sheets and generatedAt.

Replay protection#

• Each nonce works once and expires after 5 minutes. Ask again without payment to get a fresh one.
• Each payment is recorded by its signature before it is submitted. A signature is served at most once; reusing it returns 409.
• A payment is bound to the coin, the service and your exact input. Replaying a public, on-chain payment with a different question is refused.
• Anything else in the transaction (another program, a second transfer, lookup tables, extra signers or unused accounts) is refused before anything is sent.

If something goes wrong

1. Payment rejected or failed on-chain: you get 402 again with the reason. The transfer did not happen (a failed transaction can still cost its network fee).
2. Payment sent but not confirmed in time: 504 with Retry-After. Retry with the same X-PAYMENT header; you are never charged twice.
3. The service fails after the payment confirmed: 502. There is no automatic refund; the payment stays in the coin's AI vault and funds its AI.

How the coin pays its AI provider#

Every model call of an AI coin (chat, API keys, skills, roles, and the x402 services above) is paid by the coin's AI vault to the inference provider with x402 version 2, exact scheme, in USDC on Solana. The default provider is BlockRun; the platform can point to any OpenAI-compatible x402 provider.

1. Terms

   The first call to a model gets a 402 with the provider's payment terms (network, asset, amount, payTo, fee payer). They are validated and cached for 10 minutes from when they were fetched.

2. Sign locally

   The vault signs one USDC transfer of exactly the price, on the server, using the official x402 Solana client. The signed transaction is decoded and checked again before it is sent.

3. One round trip

   With cached terms, the payment is pre-signed at the locally computed price and sent with the first request, so a normal call is one HTTP round trip. If the provider wants a different amount, it answers 402 with fresh terms, which are paid right away if they are within 1.5 times the local estimate and the cap (two round trips), and pre-signing pauses for that model for 10 minutes. The refused pre-signed payment is counted as “in doubt”, because the provider could still submit it.

4. Answer

   The provider checks the payment before it answers. The server does not wait for on-chain confirmation; the answer streams as soon as the provider sends it. The settlement transaction, when the provider returns one, is stored as the request's payment signature.

Latency, honestly

• The payment check is part of the time to the first word: the provider verifies the payment before it starts.
• Before calling the provider the server uses cached data only (model catalog 10 minutes, coin rules 10 seconds, vault balance up to 15 seconds, a recent blockhash up to 30 seconds), so most calls make no extra Solana request.
• The first call to a model, one call every 10 minutes after that (to refresh the cached terms), and a call whose pre-signed amount is refused take two round trips instead of one.
• Database writes, receipts and USDC float refills happen after or beside the answer, never in front of it.
• The provider must send its response headers within 120 seconds, and a stream is stopped after 60 seconds without data (both settable by the platform). A long answer that keeps streaming is never cut.

What the vault will sign, and what it refuses, is listed in Security. Pricing and limits are in AI vault & billing.

Related#