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

  1. Send the request with no Authorization header.
  2. You get 402 Payment Required. Its WWW-Authenticate: Payment header 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.
  3. Your client pays in USDC.e on Tempo and sends the same request again with Authorization: Payment and the credential it made.
  4. We confirm the payment on chain before we answer. You get the normal response, plus a Payment-Receipt header and Cache-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.

402 response
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

  1. Send the request with no Authorization header. The same 402 also carries a PAYMENT-REQUIRED header: 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, resource and accepts, for a client that reads the offer from the body.
  2. 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-SIGNATURE header.
  3. 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-RESPONSE header and Cache-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

PriceEndpoints
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.

Shell
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}' -i

Pay 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

StatusWhat happenedWhat to do
402No 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.
403This payment was already used for a request.Send the request again without it to get a new price.
409A 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.
429More than 120 payments in a minute from one IP address.Wait for Retry-After.
500Something failed on our side. A payment taken for a request we did not answer is refunded.Retry with backoff.
503Pay 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:

StatusDetail
409This 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.
409This 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.
503Your 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.
503This 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:

StatusReasonDetail
402signature_unsupportedThis 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.
402signature_invalidThis 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.
402payment_malformedThis 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.