Paying per call
Every service here is free within the anonymous rate limit, and that does not change. What follows applies only after an anonymous caller has spent that limit — the point at which this API used to say 429 and stop. A caller with an API key is never asked to pay; keys have their own higher limit.
Payments are live on eip155:8453, which is Base mainnet: these are real funds.
What it costs
Prices are per request, in USDC, and are published in machine-readable form in the offers document alongside every other service:
GET https://wellknown.network/api/v1/offersGET /api/v1/search— $0.005 · Search the index beyond the free rate limit.POST /api/v1/resolve— $0.005 · Resolve a need to a live server beyond the free rate limit.GET /api/v1/agents/[id]/evidence— $0.01 · Evidence document for one record beyond the free rate limit.
No other route charges. A route that is not in that list answers 429 past the free limit whether payments are switched on or not.
The exchange
This is x402: the standard use of HTTP 402, which was reserved for exactly this and never defined. A request past the free limit is answered with the price and where to pay; the same request, retried carrying a signed payment, is served.
GET /api/v1/search?q=postgres → 402
PAYMENT-REQUIRED: <the price, scheme, network and address>
Link: <https://wellknown.network/api/v1/offers>; rel="payment"
body: { "x402Version": 2, "accepts": [ … ], "offers": "…" }
GET /api/v1/search?q=postgres → 200
PAYMENT-SIGNATURE: <the signed payment>
← PAYMENT-RESPONSE: <the settlement, including the transaction>
← x-paid: x402The price is in the PAYMENT-REQUIRED header for a client that speaks x402, and in the body for a person holding curl. Both say the same thing. Any x402 client library will do this for you; there is nothing bespoke to implement.
Four properties worth relying on
You are not charged for an error. A payment is verified before the request runs, but only settled after it has succeeded. If the handler fails, nothing is settled.
A 402 only ever appears where a 429 would have. Within the free limit, no payment is requested, examined, or required, and a request that carries one anyway is served for free like any other.
An outage at the payments provider is not an outage here. If the facilitator cannot be reached, paid routes fall back to the ordinary 429 rather than failing. You will never get an error page because someone else's service is down.
Settlement is public. The transaction is returned to you in PAYMENT-RESPONSE and is verifiable on-chain without our cooperation. We record it too, for reconciliation on our side, along with the route, the amount and the time.
What we keep
One row per settled payment: the route, the path, the scheme, the network, the asset, the amount, the receiving address, the payer address and the transaction. A payer address is public chain data and is stored because reconciliation and any dispute both need it. No request body, no query, and nothing that identifies a person is stored with a payment.