back to search

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

1

send a request

call the endpoint exactly as you would with an API key, but omit the Authorization header.

initial request
POST /v1/generate HTTP/1.1
Content-Type: application/json

{
  "vertical": "plumber",
  "location": "Denver, CO",
  "limit": 200
}
2

receive payment terms

the server responds with HTTP 402 and a JSON body describing what it costs and where to pay.

402 response
HTTP/1.1 402 Payment Required

{
  "x402": {
    "version": "1",
    "price": "0.25",
    "currency": "USDC",
    "network": "base",
    "recipient": "0xBD7dd8b1...",
    "description": "200 plumber leads, Denver CO",
    "expiry": "2026-09-10T15:00:00Z"
  }
}
3

settle on-chain

transfer the specified amount to the recipient address on the specified network. the transaction hash is your payment proof.

4

re-send with proof

repeat the same request with the payment proof in the header.

authenticated request
POST /v1/generate HTTP/1.1
Content-Type: application/json
X-Payment-Proof: 0x<transaction_hash>

{
  "vertical": "plumber",
  "location": "Denver, CO",
  "limit": 200
}
5

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.

endpoint catalog

23 x402-gated endpoints. machine-readable catalog at /v1/bazaar

lead discovery

/v1/leads/search

scored leads by vertical + location

$0.25
/v1/leads/search/raw

unscored scrape data — cheapest tier

$0.08
/v1/leads/search/enriched

full pipeline — rankings, backlinks, speed, social

$0.75
/v1/leads/freshness

re-verify previously purchased leads

$0.02

single-business intelligence

/v1/business/score

multi-lens opportunity scoring

$0.05
/v1/business/contact

phone, address, maps URL

$0.03
/v1/business/competitors

same-vertical nearby businesses

$0.15
/v1/business/verify

SoS + Google Maps verification

$0.10
/v1/business/audit

digital presence audit with A-F grade

$0.08

market intelligence

/v1/market/saturation

density + competition index

$0.25
/v1/market/gaps

find underserved verticals in a location

$0.50
/v1/market/compare

compare saturation across locations

$0.40
/v1/market/growth

growth trajectory signals

$0.30

enrichment-as-a-service

/v1/enrich/whois

domain registration, age, nameservers

$0.01
/v1/enrich/social

social media presence check

$0.04
/v1/enrich/techstack

CMS, analytics, framework detection

$0.03
/v1/enrich/formation

SoS business formation data

$0.05
/v1/enrich/hiring

job posting signals — growth indicator

$0.03
/v1/enrich/reviews

review sentiment + competitive position

$0.05

utility

/v1/website/status

reachability + response time + SSL

$0.005
/v1/email/verify

MX records + format + disposable check

$0.005
/v1/phone/verify

format + carrier type + fake detection

$0.01
/v1/compare/pricing

gravee vs competitor pricing

$0.01

compound products coming soon — 15 cross-portfolio endpoints composing gravee + PLEXUS adapters + Tranche investigative graph. due diligence, compliance reports, entity dossiers, trigger events.
ceiling: $7.50/call for a full entity dossier.

settlement details

networksBase (Ethereum L2) + Solana
currencyUSDC on both networks
confirmation1 block (~2s on Base, ~0.4s on Solana)
expirypayment terms expire 5 minutes after the 402 response
bazaarGET /v1/bazaar — full machine-readable catalog

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

x402

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.

key

when you want predictable billing through Stripe, volume discounts, or integration with systems that expect header-based auth. buy credits at getgravee.com/credits, use the key 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.