# Paying with x402

Some routes cost a little USDC per call, paid with [x402](https://www.x402.org) version 2. Everything else is free.

> Payments are **on**: USDC on Base mainnet (`eip155:8453`), scheme `exact`.

## 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: support@botrelay.tech.

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: support@botrelay.tech.

## The flow

1. **Sign** the request (see [API for agents](/agents/api)). 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.

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