Paying per call with x402

Status: live since 2026-10-02 07:13 UTC on Base mainnet (eip155:8453), USDC, facilitator Coinbase Developer Platform. A payable /v2 request with no key is answered 402 with what it costs; any x402 client pays and gets the answer. Payments go to debyko.base.eth (0x17b2c55872338727660aa77776a4056a1a3158ec).

The short guide, with the plans and the state of your Agent rules, is Pay with USDC; this page is the detail.

x402 is an open standard for paying for one HTTP request: the server answers 402 Payment Required with what it wants, the client signs a USDC transfer for exactly that, sends it, and gets the answer. No account, no key, no card. DEBYKO takes USDC on Base (eip155:8453; native USDC, 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), speaks x402 version 2, and uses Coinbase’s CDP facilitator to check and settle payments.

What a call costs

The price is by the class of the endpoint and is the same for everyone. A paid call is answered as Pro answers it, for that one request: all venues, all instruments, all the history the platform keeps. There is no tier and no balance to top up.

class	price (USDC)	endpoint
snapshots	0.005	POST /v2/snapshots
history	0.02	POST /v2/snapshots/history
screen	0.01	POST /v2/screen
candles	0.005	POST /v2/candles
agent_state	0.01	GET /v2/agent/state (per rule named)
archive	0.10	GET /v2/archive/{listing}/{layer}/{day} (per file: core)
archive_top100	0.05	GET /v2/archive/{listing}/{layer}/{day} (per file: top-100)

A file of the archive is priced per file: 0.10 for a file of a core listing, 0.05 for one of the top-100 (the list of files, GET /v2/archive, is free with a key and is not payable). One payment is one file and one 302 to a link that works for fifteen minutes; the payment is settled after the redirect, and in the ledger the class is archive for both prices.

agent_state is priced per rule named (0.01 each, one to 100 rules in a call): see Pay with USDC.

Beside the price of the request, the 402 also offers the plans — Mini $9, Standard $29, Pro $99, Pro Plus $249, the same prices as at checkout — for 30 days, no renewal: pay the amount of a plan instead and the answer is a key of that plan (no data is served from the path), shown once. See Pay with USDC.

Not payable, because nobody has priced them: GET /v2/stream (an open connection has no single request to pay for, and will not become payable), POST /v2/books, POST /v2/liquidations and the DQL helpers. Those need a key. /v2/venues, /v2/instruments, /v2/dql/catalogue and /v2/dql/parse stay free and need nothing. The attestation endpoint is priced at 0.05 and does not exist yet.

The order in which a request is read

The first line that matches wins:

1. An Authorization header is present: the key decides. A good key gets its plan, a bad one a 401. If a payment header is also sent, it is not read and not verified. Send one or the other.
2. A PAYMENT-SIGNATURE header is present on a payable endpoint: the payment is checked, the request is answered, and the payment is settled after the response.
3. A payable endpoint and neither header: 402 with what to pay.
4. Anything else: 401.

Paying

Ask without credentials. The answer is 402, with the requirements in the PAYMENT-REQUIRED header (base64) and in the body, next to the usual errors list that says “or send an API key”:

curl -si https://api.debyko.com/v2/snapshots \
  -H "Content-Type: application/json" \
  -d '{"where":"base in (BTC)","layers":["mark"]}'

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": { "url": "https://api.debyko.com/v2/snapshots", "description": "DEBYKO /v2/snapshots (price class snapshots)", "mimeType": "application/json" },
  "accepts": [
    { "scheme": "exact", "network": "eip155:8453", "amount": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x…", "maxTimeoutSeconds": 60,
      "extra": { "name": "USD Coin", "version": "2" } }
  ],
  "errors": [ { "code": "PAYMENT_REQUIRED", "message": "PAYMENT-SIGNATURE header is required", "hint": "or send an API key instead: …" } ]
}

amount is in atomic units of the asset: USDC has six decimals, so 5000 is 0.005 USDC. Sign an EIP-3009 transfer of exactly that amount to payTo, valid for at most maxTimeoutSeconds, and send the same request again with PAYMENT-SIGNATURE: <base64 of the x402 payment>. Any x402 client library does this for you (it makes the first request, reads the 402, signs, retries). X-PAYMENT is read as the same header when it carries a version 2 payment; a version 1 payment is a 400 that says to use version 2.

Discovery

The 402 declares each payable endpoint for x402 discovery (the bazaar extension): under extensions.bazaar, info is how to call the endpoint (an example request and an example answer) and schema is a JSON Schema that describes the request and the answer, taken from the published schemas; and resource names the service (DEBYKO), its tags and its icon. An x402 client that pays echoes the extension in its payment, and the facilitator lists the service in its catalogue after that first settlement. Nothing else needs doing, and a client that ignores the extension is not affected by it.

What can go wrong, and what you are charged

you see	meaning	charged
400 PAYMENT_MALFORMED	The header is not a version 2 exact payment of the form the specification gives. Nothing was asked of the facilitator.	no
402, error says what	A payment that is not what was asked (amount, receiver, network, expired), one already presented, or one the facilitator refused (insufficient_funds, …).	no
429 RATE_LIMITED, X-Debyko-Limit: x402_challenges_per_minute	Your address has been sent its share of 402s this minute. A paid, served call does not use any of it.	no
429 RATE_LIMITED, X-Debyko-Limit: x402_unpaid_in_flight_per_payer	Three payments of yours are verified and not yet settled; the fourth waits (Retry-After: 5) and is not used.	no
503 UNAVAILABLE, Retry-After: 5	The facilitator did not answer; the payment was not checked. Retry with the same payment while it is valid.	no
the endpoint’s own 400, 403, 5xx	The payment was good and the request was not: the request is not served and the payment is not settled. The same signed payment may be presented again.	no
200	The payment is settled after the response is complete.	yes, once

A settlement that fails after you have been served is DEBYKO’s loss, not yours: it is logged and counted, nobody re-asks you. Because the response is complete before the payment settles, there is no PAYMENT-RESPONSE header on the 200 of a request: the transaction does not exist yet while the headers are written. The transaction is on Base, in your own wallet’s history, and every paid answer carries a receipt_id that the ledger keeps beside the transaction hash. A plan is the exception: it is settled before anything is given, so its answer carries the settlement in PAYMENT-RESPONSE (base64: success, transaction, network, payer) and in the body.

An authorization can be used once: the signer and the nonce are remembered while the authorization could still be valid — in Redis, so a second API process or a restart does not forget them — in addition to the chain’s own rule.

What is kept

A payment is public on chain. DEBYKO keeps one row per settled payment: the transaction hash, the network, the payer’s address, the amount, the price class (or, for a plan, the plan) and the receipt_id of the answer it paid for, and counters of requests and amounts per payer address and day. It keeps nothing about what you asked, and no key is involved. This is the revenue record, kept for ten years as Lithuanian accounting law requires; it is not a request log. The Privacy page says the same.

Switching it on (for the operator)

Off by default. X402__Enabled=true with X402__PayTo (the receiving address; there is no default and the service does not start without it) and a CDP API key (X402__Cdp__KeyId, X402__Cdp__KeySecret, an ECDSA key). Prices are X402__Prices__<class>.