Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thespawn.io/llms.txt

Use this file to discover all available pages before exploring further.

Use this path when your service has per-request value and you want agents to pay without API keys, signup, or monthly plans.

​
Job

You want a caller to try the service, see the price, pay when ready, and receive a receipt. The caller may not know what x402 is. Start with the outcome: 
Run a free preview, then show exact payment terms for the paid call.

​
Prerequisites

  • A service endpoint with one free demo or preview mode.
  • A paid endpoint that returns HTTP 402 before payment.
  • Exact network, asset, amount, and recipient address for the paid call.
  • Wallet/payment implementation only after the preview and unpaid 402 contract are working.

​
Verified example

Social Intel API exposes a paid search endpoint and a free demo path. The demo proves the result shape before a caller sees the x402 payment challenge. Free direct demo: 
curl -sS "https://socialintel.dev/v1/search?limit=3&query=fitness&country=US&demo=true"
Unpaid HTTP request: 
curl -i https://socialintel.dev/v1/search \
  -H "Content-Type: application/json" \
  --data '{"query":"yoga","country":"US","limit":1}'
Expected result: HTTP 402 with payment requirements. The verified response included PAYMENT-REQUIRED, accepted Base USDC and Solana USDC, amount 500000 base units, and a payTo address. The free demo and the paid endpoint should use the same input shape, otherwise the demo does not reduce payment risk. Expected unpaid signal: 
HTTP/2 402
PAYMENT-REQUIRED
amount: 500000
asset: USDC
network: base
Redact addresses in bug reports unless the address is already meant to be public.

​
What just happened

x402 turns price into an HTTP response. The service does not need to ask the user to create an account first. A client can parse the accepted networks, token, amount, destination, and timeout, then decide whether it is allowed to pay. The demo comes before the 402 challenge because the buyer needs evidence before wallet policy matters. A good paid endpoint therefore has two proofs: the free response proves output shape, and the unpaid paid request proves exact payment terms.

​
The useful 402 body

Your 402 response should include:
FieldWhy
resource URL and descriptionThe caller knows what it is paying for.
accepted networks and assetsWallet policy can decide whether payment is possible.
base-unit amountWallet signing uses exact token units.
payToThe destination is explicit.
demo URL or demo flagNon-crypto users can preview output.
input/output schemaAgents know how to shape the paid request.
receipt behaviorCallers know what proof they get after payment.

​
Failure branches

SymptomFix
Users bounce before payingAdd a no-wallet demo mode.
Agents cannot parse pricePut exact chain, asset, amount, and payTo in the response.
The service returns only textReturn machine-readable JSON for 402.
Users do not have fundsLink to wallet funding and show the exact network, usually Base USDC for first runs.
Demo and paid inputs differMake the same query shape work in both modes before asking for payment.

​
Next