x402 protocol
pay per request with on-chain settlement. no API key. no account. no balance to manage.
your agent sends payment proof, gets leads. that's it.
what is x402
HTTP 402 has been reserved since 1999 — "Payment Required." x402 finally gives it a protocol. it lets any HTTP client pay for any HTTP resource in a single round-trip, settled on-chain, without accounts, API keys, OAuth tokens, or billing agreements.
for AI agents, this is the difference between needing a human to sign up for an account and autonomously purchasing data mid-task. the agent decides it needs leads, pays for them, and keeps working. no human in the loop.
how it works
send a request
call the endpoint exactly as you would with an API key, but omit the Authorization header.
POST /v1/generate HTTP/1.1
Content-Type: application/json
{
"vertical": "home-services",
"location": "Austin, TX",
"limit": 50
}receive payment terms
the server responds with HTTP 402 and a JSON body describing what it costs and where to pay.
HTTP/1.1 402 Payment Required
{
"x402": {
"version": "1",
"price": "0.25",
"currency": "USDC",
"network": "base",
"recipient": "0xBD7dd8b1...",
"description": "50 home-services leads, Austin TX",
"expiry": "2026-09-10T15:00:00Z"
}
}settle on-chain
transfer the specified amount to the recipient address on the specified network. the transaction hash is your payment proof.
re-send with proof
repeat the same request with the payment proof in the header.
POST /v1/generate HTTP/1.1
Content-Type: application/json
X-Payment-Proof: 0x<transaction_hash>
{
"vertical": "home-services",
"location": "Austin, TX",
"limit": 50
}receive your leads
the server verifies the transaction, confirms the amount and recipient, runs your search, and returns the results. same response format as the API key path.
why this matters
for AI agents
your agent can autonomously purchase data without a human setting up credentials. it sees a 402, evaluates whether the price is worth it, pays, and gets the resource. no onboarding flow to navigate.
for developers
no API key management. no balance to check. no billing portal. no webhook for failed payments. every request is self-contained — payment and data in one round-trip.
for the ecosystem
x402 is an open protocol. gravee is one of the first production endpoints. the same payment flow works across any x402-enabled service — your agent learns the pattern once.
settlement details
settlement wallet and pricing are included in every 402 response. never hardcode the wallet address — always read it from the response.
discovery
gravee is listed on the x402 Bazaar, the directory of x402-enabled endpoints. agents that support x402 can discover gravee automatically through Bazaar metadata.
the Bazaar listing includes the endpoint URL, pricing, supported parameters, and response schema — everything an agent needs to decide whether to call and pay.
x402 vs API key — when to use which
when your agent or script should pay per call with no setup. best for autonomous agents, one-off scripts, and anything where managing a balance would add friction.
when you want predictable billing through Stripe, volume discounts, or integration with systems that expect header-based auth. buy a key on the website, use it in the header.
both paths hit the same engine, return the same results, and are subject to the same rate limits. the difference is how you pay, not what you get.