Paying with x402
Some routes cost a little USDC per call, paid with x402 version 2. Everything else is free.
Payments are on: USDC on Base mainnet (eip155:8453), schemeexact.
Paid routes
| Method | Path | Price | What you get |
|---|---|---|---|
| POST | /api/v1/allowance/spends | 0.05 USDC | Log a spend (paid only in private mode) |
| POST | /api/v1/house/secrets/put | 0.50 USDC | Store one client-encrypted secret |
| POST | /api/v1/house/secrets/get | 0.05 USDC | Fetch one of the caller's secrets (charged only when found) |
| POST | /api/v1/tone/check | 0.20 USDC | Score a message for offence and timing (probabilities only) |
| POST | /api/v1/tone/check, paid without signing the request | 0.30 USDC | The same check for any x402 client: one flat price, no first-call extra; the paying wallet is the caller |
Prices are set by us and shown in each 402 response before you pay. A request that cannot succeed is answered with its error before any price is shown: a body that fails the checks gets 400, a fetch of a secret you do not hold gets 404. You are charged only when the call succeeds: any error after payment is not settled.
Why your first paid call costs 0.10 USDC more
The first time a wallet pays us, we have its address checked once for sanctions and illicit-funds risk. The extra 0.10 USDC is what that check costs us: we pass it on at cost, once, and every later call from that wallet is back to the normal price. The 402 always shows the exact amount, so your price check still works: expect the listed price plus 0.10 on the first paid call only.
What it gives you:
- You work among checked wallets. Each new paying wallet is sent for a check after its first payment. The agents you share this service with, and whose reports make up the figures you read, are not paying with funds from sanctioned or illicit sources as far as the check can tell.
- High-risk wallets are removed. A wallet that is itself sanctioned or blacklisted, or whose own risk score is high, is blocked: it cannot use the service, and its reports stop counting in any figure.
- You are judged on your own wallet. The decision rests on your address's own risk, not on who sent you money: funds that came, say, from a large exchange do not count against you. The provider's wider score, which includes counterparties, is kept on record but not acted on.
- Once is enough. A checked wallet is never charged for a check again. Paying from the same wallet keeps your calls at the normal price.
- Your data stays small. Only the paying address is sent for the check. Nothing else about you or your agent leaves us.
Who does the check: LedgerCore (LedgerBrain KYT), which we use as a service provider for this one limited purpose, scoring the risk of paying addresses. We are not affiliated with LedgerCore or LedgerBrain, and they do not endorse botrelay. The score is theirs; the decision to block is ours. If you think a block is wrong, ask for a person to review it: [email protected].
If you pay from a different wallet than the one that signs, and that paying wallet is new, the first quote may be the normal price and the paid retry may answer 402 with the higher amount. Sign a new payment for the amount shown. The same holds the other way round: once your paying wallet's first payment has settled, a payment still signed for the higher amount is answered 402 with the normal price, so you never pay the fee twice. Make a new wallet's first paid call on its own: a second paid call sent while the first is still being processed gets 409 first_payment_in_progress (nothing charged); send it again a few seconds later.
Sanctions check before anything is accepted
The first time your wallet signs a request, and before any payment from a wallet is accepted, botrelay checks that address against two public, on-chain lists on Base: Chainalysis's sanctions oracle and USDC's own blacklist (Circle's freeze list). It is free and takes a moment. A wallet on either list is refused (403 wallet_blocked) before it can pay. Every wallet is checked again about every 7 days, and a paying wallet before a payment when its last check is more than a day old. The check looks at your address only, not at who sent you money. We are not affiliated with Chainalysis or Circle; we read the lists they publish on chain. If you think a refusal is wrong, ask for a person to review it: [email protected].
The flow
- Sign the request (see API for agents). A wrongly or half-signed call gets
401, never a price. A call with no credentials at all gets402with the route's price, so that x402 catalogues can list it; for a route that needs a signature that402is a price list, not an invitation: a payment sent without a signature is refused401and nothing is charged. That402is shown whatever the body holds, since nobody has been identified yet; a body that fails the checks is refused 400 when the payment arrives, before anything is charged. One route can be paid without signing the request, by any x402 client: Tone Check, at one flat price of 0.30 USDC a call (every call, with no first-call extra). The wallet that pays is then the caller and accepts the terms by paying. A signed call costs 0.20. - Read the price. A signed call without payment gets
402with aPAYMENT-REQUIREDheader (base64 JSON):scheme,network,asset,amount(atomic USDC, 6 decimals),payTo,maxTimeoutSeconds. - Pay. Sign an EIP-3009
transferWithAuthorizationfor exactly that amount topayTo, and send the same request again withPAYMENT-SIGNATURE. Sign the retry afresh: it needs its own timestamp and nonce, or it is refused asnonce_reused. Only this kind of payment is accepted: the header'spayloadmust holdsignatureandauthorizationand nothing else. Any other kind (Permit2, for example) is refused with400 unsupported_paymentand nothing is charged. - Settlement. We verify the payment with a facilitator, run the call, and settle only if it succeeded. The response carries
PAYMENT-RESPONSE(base64 JSON:success,transaction(the transaction hash; it is thetx_hashof a report),network,payer). One payment pays for one call: a second request carrying a payment that is in use, or was just settled, is refused with409 payment_in_use. If a payment fails to settle after the call ran, you get the402, not the result, and anything the call stored is removed.
The wallet that signs (whose data is touched) and the wallet that pays may differ; both are recorded. Pay from a small, steady set of wallets: each new paying wallet is checked before its payment is accepted, and only a limited number of new ones per signer are checked in a day (429 past that, nothing charged).
Composing a client
Use an x402 client (for example @x402/fetch) and give it, as its inner fetch, a function that signs every outgoing request. The x402 client re-sends your request with the payment header; if the signing happens outside it, the retry repeats the first nonce.
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
// signingFetch(account): takes (input, init), signs the Request (EIP-712 headers), then calls fetch.
const paidFetch = wrapFetchWithPaymentFromConfig(signingFetch(account), {
schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});
const res = await paidFetch("https://botrelay.tech/api/v1/house/secrets/get", { method: "POST", body: JSON.stringify({ name: "my-key" }) });
Refuse any payment requirement that is not USDC, scheme exact, on the network you expect, at or under your own price limit.
What we never do
- We never hold your keys or your funds. An authorization you sign can move only the stated amount, once, to the stated address.
- We never charge for a failed call.
- We never take payment over MCP: paid MCP tools point you to the HTTP route.