Prepaid credits: one payment, many calls

Paying each call with x402 settles one payment per call. With prepaid credits, one x402 payment funds an API key (it starts with tnd_), and later calls with the key are paid from its balance: at the same price as their x402 price, only when they return an answer (HTTP 200), with no payment step per call. The key works with the HTTP API and with the MCP server.

Buy credits with one x402 payment

Call POST /v1/credits/topup with the amount (USD 1 or USD 5). The answer is an x402 402 for that amount; pay it the way you pay any Tanod route, and the paid answer carries the credit and, for a new key, the key itself. The amount paid is the amount credited. To add to a key you already have, send it in the body as "key" (or in the Authorization header).

POST https://tanod.dev/v1/credits/topup
Content-Type: application/json

{"amount_usd": "5"}

Add to your key: {"amount_usd": "5", "key": "tnd_your_key"}

One payment is credited once: sending the same signed payment again answers 409 and moves no money. If the answer says the payment needs a manual check (503 settlement_unknown, or 500 credit_not_applied), do not pay again: keep the payment and write to [email protected] with the transaction. Support is best effort.

If GET /v1/credits/packs answers 503 not_configured, prepaid credits are paused for a moment: pay per call with x402 or use the free daily allowance meanwhile.

Your key

Save the key when you get it. It is shown once, in the paid answer, and we store only a hash of it, so nobody can show it to you again. If you lose it, write to [email protected]: support can replace it after you prove you made every purchase that funded it (a message signed with the paying wallet; a smart-contract wallet is checked on chain, case by case); the old key then stops working. Support never asks for your key.

How a key is charged

• A call with a key always draws on its balance: the free daily allowance does not apply, and no x402 payment is needed.
• A call is charged its listed price only when it returns an answer (HTTP 200). Errors, timeouts, bad input and a search that finds nothing are not charged, exactly as with x402.
• A balance too low for a call answers 402 with the balance and the usual x402 offer; nothing is charged.
• Paid answers show what was charged and what is left: headers X-Tanod-Credits-Charged-Usd and X-Tanod-Credits-Balance-Usd (over MCP, _meta["tanod/credits"]).
• Each charge is taken from your oldest purchase that has not expired.
• Unused credit expires 12 months after the purchase that added it. The balance shows the amount and date of the next expiry. Purchases are final: unused credit is not refunded.

Use the key

• HTTP: Authorization: Bearer tnd_... or X-Tanod-Credits: tnd_...
• MCP: https://tanod.dev/mcp?key=tnd_... (also on /mcp/<family> URLs)
• Balance: GET https://tanod.dev/v1/credits/balance with the key, or the free MCP tool get_credit_balance: the balance, the amount and date of the next expiry, recent purchases and the last 20 charges.

What we keep

A hash of the key, its balance, each purchase (amount and payment transaction) and each charge (route, amount, time). No email, name or IP address in the credit records (see privacy). Machine-readable terms: terms.json, key prepaid_credits.

Back to tanod.dev · pricing · when a paid call is charged.