DataQuoll homeDataQuoll
DocsPricing
Log in

Core concepts

Pay per request

Call a data endpoint without a key and you get a 402 with the price. An MPP client pays and sends the request again, and the response carries a receipt. A paid request gets the same features as the Pro plan.

How a paid request works

  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 free key.
  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/problem+json
Cache-Control: no-store
WWW-Authenticate: Payment id="...", realm="dataquoll.io", method="tempo", intent="charge", request="...", expires="...", opaque="..."

{
  "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.",
  "instance": "/api/v1/states"
}

Prices

PriceEndpoints
US$0.02/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.10/incidents/history, /incidents/snapshot
US$0.25/hazard-history/point

Prices are in US dollars, paid in USDC.e on the Tempo network. 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. Your wallet also pays the Tempo network fee for the transfer, a fraction of a cent, to the network, not to us.

Declarations are not sold per request. 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.
  • 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.

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

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.