Core concepts
Pay per request
Call a data endpoint without a key and you get a 402 with the price. An MPP or x402 client pays and sends the request again, and the response carries a receipt. A paid request gets the same features as the Pro plan.
Pay with MPP
- Send the request with no
Authorizationheader. - You get
402 Payment Required. ItsWWW-Authenticate: Paymentheader carries the price, the token, where to pay and when the price expires, 5 minutes after it was issued. The body says a key or a payment is needed and points to a key that opens the endpoint: a free key, or for declarations the Organisation licence. - Your client pays in USDC.e on Tempo and sends the same request again with
Authorization: Paymentand the credential it made. - We confirm the payment on chain before we answer. You get the normal response, plus a
Payment-Receiptheader andCache-Control: private.
MPP is the Machine Payments Protocol. A client that pays a Tempo charge follows this flow; we have proven it with the mppx client, versions 0.13.4 and 0.15.0.
HTTP/1.1 402 Payment Required
Content-Type: application/json
Cache-Control: no-store
WWW-Authenticate: Payment id="...", realm="dataquoll.io", method="tempo", intent="charge", request="...", expires="...", opaque="..."
PAYMENT-REQUIRED: <base64 JSON: x402Version 2, accepts [{ scheme "exact", network "eip155:8453", asset USDC, amount "80000", payTo our address, maxTimeoutSeconds 300 }], resource>
{
"type": "https://emergencyapi.com/errors/payment-required",
"title": "Payment Required",
"status": 402,
"detail": "This endpoint needs a key or a payment. Get a free key at https://dataquoll.io/signup and send it as `Authorization: Bearer <key>`, or pay for this one request with an MPP client (the WWW-Authenticate header carries the price) or an x402 client (the PAYMENT-REQUIRED header carries it).",
"instance": "/api/v1/states",
"x402Version": 2,
"error": "Payment is required.",
"resource": {
"url": "https://dataquoll.io/api/v1/states"
},
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "...",
"amount": "80000",
"payTo": "...",
"maxTimeoutSeconds": 300,
"extra": "..."
}
]
}Pay with x402
- Send the request with no
Authorizationheader. The same 402 also carries aPAYMENT-REQUIREDheader: an x402 version 2 offer of the same price in USDC on Base, paid to our address with the exact scheme. The body carries the same offer, decoded:x402Version,error,resourceandaccepts, for a client that reads the offer from the body. - Your client signs an EIP-3009 authorization for exactly that amount, valid for at most 300 seconds, and sends the same request again with the
PAYMENT-SIGNATUREheader. - Coinbase, our x402 facilitator, settles it on Base and pays the network fee. The payment is confirmed on chain before we answer. You get the normal response, plus a
PAYMENT-RESPONSEheader andCache-Control: private.
We accept x402 version 2 only: the PAYMENT-SIGNATURE header, never X-PAYMENT. The authorization can be signed by a standard wallet (an externally owned account) or by a smart contract wallet that is already deployed on Base and signs with ERC-1271 in more than 65 bytes, such as a Base Account. We check a smart wallet's signature with the wallet itself on Base before anything moves. A wallet that is not deployed yet (an ERC-6492 signature) is refused with a 402 that offers no price (reason signature_unsupported). When a request carries both Authorization: Payment and PAYMENT-SIGNATURE, the MPP payment is used. We have run this flow end to end with @x402/fetch 2.28.0 and the mppx 0.15.0 x402 client on the Base Sepolia testnet.
Prices
| Price | Endpoints |
|---|---|
| US$0.08 | /incidents, /incidents/{id}, /incidents/nearby, /events, /events/{id}, /states, /gauges, /gauges/{id}, /gauges/{id}/readings, /gauges/summary, /facilities, /mobile-sites, /address, /publications, /publications/{id}, /publishers, /calendars, /calendars/{jurisdiction}, /calendars/{jurisdiction}/{date} |
| US$0.20 | /incidents/history, /incidents/snapshot |
| US$0.25 | /hazard-history/point |
| US$0.50 | /declarations, /declarations/agrn/{agrn}, /declarations/point, /declarations/postcode/{postcode} |
Prices are in US dollars, paid in USDC.e on the Tempo network (MPP) or USDC on the Base network (x402). One payment buys one request, so each page of a paginated result is paid for separately. The price in the 402 is the price we charge, and it holds for 5 minutes. With MPP your wallet also pays the Tempo network fee for the transfer, a fraction of a cent, to the network, not to us. With x402 the facilitator pays the Base network fee, so your wallet pays nothing but the price.
A declarations request returns declared-area status: whether a place sits in an area under a disaster declaration or funding activation, with the official source for each record. With a key, the declarations API comes with the Organisation licence (see pricing).
Pay from the command line
The mppx command line pays and prints the answer. It reads the paying wallet's key from the environment, and the wallet needs USDC.e on Tempo.
export MPPX_PRIVATE_KEY=<your wallet key>
npx mppx https://dataquoll.io/api/v1/states -i
npx mppx https://dataquoll.io/api/v1/hazard-history/point -J '{"lat":-28.8078,"lng":153.2766}' -iPay from code
We publish the command line above because it is the client path we have run end to end against this API. For code, the MPP documentation covers the client libraries.
What a paid request gets
- The same answer as a request on the Pro plan, with its features: the full archive and gauge history with no lookback limit, CSV and CAP-AU, and incidents grouped into events.
- Hazard history lookups at the hazard price, with no lookup quota.
- Disaster declaration status at the declarations price: the same answer the declarations API gives on the Organisation licence.
- Commercial use, as on the paid plans (terms section 18).
- No monthly quota, so a paid response carries no RateLimit headers. One IP address can send up to 120 payments a minute.
Receipts and refunds
The Payment-Receipt header on a paid response names the payment's transaction. Keep it: the receipt and the public transaction are the record of the payment. We do not issue invoices.
If we do not answer a paid request with a 2xx, we refund the amount we received to the wallet that paid it, within 35 days of the request. That covers a request refused for a bad parameter (400) and a second payment for a price that was already paid (409). The network fee is not refunded. Check your parameters before you pay: a 400 is refunded, but not straight away.
With x402, the PAYMENT-RESPONSE header names the transaction instead. An x402 payment is refunded in USDC on Base to the wallet that signed the authorization.
When a payment is refused
| Status | What happened | What to do |
|---|---|---|
| 402 | No payment, or a payment that failed its checks: the wrong amount, another endpoint's price, or a price that expired. A fresh price comes with it. An x402 payment we cannot accept as sent gets a 402 with no price instead (see below). | Pay the new price, or send a key. |
| 403 | This payment was already used for a request. | Send the request again without it to get a new price. |
| 409 | A second payment for a price that was already paid. It was not used, and it is refunded. | Send the request again without a payment to get a new price. |
| 429 | More than 120 payments in a minute from one IP address. | Wait for Retry-After. |
| 500 | Something failed on our side. A payment taken for a request we did not answer is refunded. | Retry with backoff. |
| 503 | Pay per request is paused, so no price is issued. | Wait for Retry-After, or send a key. If you already sent a payment, send the same request with it again within 5 minutes of the price being issued. |
When an x402 payment is refused with no new price
Once we have tried to settle an authorization, no answer for it offers a price again, so a client that pays automatically is never asked to pay twice for one request. These answers carry no PAYMENT-REQUIRED header. Their detail says what to do:
| Status | Detail |
|---|---|
| 409 | This payment authorization was already used, so it was not charged again. Do not pay again for this request. If it paid for a request that was not served, it is refunded within 35 days. |
| 409 | This payment's transaction reverted on chain and moved no money, so this authorization cannot be used again. Send the request without it for a new price and pay with a new authorization. If this authorization is ever landed later, that payment is refunded within 35 days. |
| 503 | Your payment may have gone through, so no new price is offered. Do not pay again for this request: if the payment lands, it is refunded within 35 days. |
| 503 | This payment could not be recorded, so it was not charged. Send the same request with the same PAYMENT-SIGNATURE again within a few minutes, or get a free key at https://dataquoll.io/signup. |
When an x402 payment is not accepted
Some x402 payments can never be accepted as sent: a signature in a format we do not accept, a signature that does not verify, or a PAYMENT-SIGNATURE we cannot read. We refuse them before anything reaches Coinbase, our facilitator, so nothing moves and nothing is charged. The answer is a 402 whose type ends in /errors/payment-not-accepted, with no PAYMENT-REQUIRED header, so a client that pays automatically is not asked to sign the same payment again. Its reason member says which one it is:
| Status | Reason | Detail |
|---|---|---|
| 402 | signature_unsupported | This payment's signature is in a format we do not accept. A standard wallet (an externally owned account) signs with 65 bytes. A smart contract wallet, such as a Base Account, must already be deployed on Base and sign with ERC-1271 in more than 65 and at most 2,048 bytes; an ERC-6492 signature from a wallet that is not deployed yet is not accepted. Nothing was charged. Do not send this payment again. Send the request without PAYMENT-SIGNATURE for a new price and pay it from a standard wallet or a deployed smart wallet, or with MPP, or get a free key at https://dataquoll.io/signup. |
| 402 | signature_invalid | This payment's signature does not verify: it was not made by the authorization's from address for USDC on the Base network. Nothing was charged. Do not send this payment again. Send the request without PAYMENT-SIGNATURE for a new price and sign that offer with the paying wallet, or get a free key at https://dataquoll.io/signup. |
| 402 | payment_malformed | This PAYMENT-SIGNATURE is not an x402 version 2 payment we can read (base64 JSON carrying an EIP-3009 authorization and its signature). Nothing was charged. Do not send it again. Send the request without it for a new price, or get a free key at https://dataquoll.io/signup. |
Keys, HEAD and MCP
A request that carries your API key is never charged: it runs on your plan as usual. HEAD requests are never priced. Pay per request covers the REST API only. The MCP server takes no payments and always needs a key or a sign-in.