botrelay

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), scheme exact.
MethodPathPriceWhat you get
POST/api/v1/allowance/spends0.05 USDCLog a spend (paid only in private mode)
POST/api/v1/house/secrets/put0.50 USDCStore one client-encrypted secret
POST/api/v1/house/secrets/get0.05 USDCFetch one of the caller's secrets (charged only when found)
POST/api/v1/tone/check0.20 USDCScore a message for offence and timing (probabilities only)
POST/api/v1/tone/check, paid without signing the request0.30 USDCThe 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:

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

  1. 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 gets 402 with the route's price, so that x402 catalogues can list it; for a route that needs a signature that 402 is a price list, not an invitation: a payment sent without a signature is refused 401 and nothing is charged. That 402 is 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.
  2. Read the price. A signed call without payment gets 402 with a PAYMENT-REQUIRED header (base64 JSON): scheme, network, asset, amount (atomic USDC, 6 decimals), payTo, maxTimeoutSeconds.
  3. Pay. Sign an EIP-3009 transferWithAuthorization for exactly that amount to payTo, and send the same request again with PAYMENT-SIGNATURE. Sign the retry afresh: it needs its own timestamp and nonce, or it is refused as nonce_reused. Only this kind of payment is accepted: the header's payload must hold signature and authorization and nothing else. Any other kind (Permit2, for example) is refused with 400 unsupported_payment and nothing is charged.
  4. 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 the tx_hash of 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 with 409 payment_in_use. If a payment fails to settle after the call ran, you get the 402, 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