402 Payment Required that prices it, pays it, retries, and gets the data with a receipt. Nothing to sign up for, nothing to store between requests.
Payments are made in USDC on Base (eip155:8453) with the x402 exact scheme: your wallet signs a transfer authorization for the exact amount, a facilitator verifies it before the request is served, and the transfer is settled on-chain before the response is returned — which is why the response carries the receipt. Your wallet needs USDC; gas is paid by the facilitator.
Prices
On the two data routes, any other outcome, an error on our side or a rate limit for instance, is not settled and costs nothing. The Brand Search API is free and has no price. The HEAD prefetch and transaction routes take API keys only.
The flow
1
Ask, and receive the price
Send the request without an The
Authorization header. The answer is a 402 whose PAYMENT-REQUIRED header is the challenge, base64-encoded JSON, and whose body says the same in prose for whoever is reading. The challenge is issued for this one request and is valid for five minutes.www-authenticate header beside it quotes the same request over MPP; Paying with MPP covers that lane.Decoded, the PAYMENT-REQUIRED header lists the ways to pay. There is one: the exact amount in USDC’s six decimals, on Base, to Brandfetch’s receiving address.Decoded PAYMENT-REQUIRED
2
Sign the payment and retry
An x402 client library turns the challenge into a signed payment and repeats the request with it in a Each signature is a fresh authorization with its own nonce. Sign once per request: a signature that has been settled cannot buy a second request, and presenting it again is refused with a
PAYMENT-SIGNATURE header. Both examples below do the whole round trip: the bare request, the signature, the retry.402.3
Read the data and the receipt
The paid response is the same JSON an API key would receive, plus a Paid requests are attributed to the paying wallet, not to any account, so there is no quota: the
PAYMENT-RESPONSE header carrying the settlement receipt, base64-encoded.Decoded PAYMENT-RESPONSE
x-api-key-quota header is absent and there is nothing to run out of.Paying with MPP
The same two routes also take MPP payments — the Machine Payments Protocol Stripe and Tempo co-authored — settled through Stripe. The unpaid402 carries one WWW-Authenticate: Payment … challenge per method next to PAYMENT-REQUIRED, and an MPP client answers with an Authorization: Payment … credential instead of a PAYMENT-SIGNATURE header.
- Methods. USDC.e on Tempo from a cent, so every per-request price qualifies. Cards via Stripe shared payment tokens start at $0.50, above these prices, so they do not appear on the per-request routes — they do on standing access.
- Clients.
npx mppx@latest(the reference CLI), the Tempo CLI (tempo request <url>), or themppxTypeScript client. Each reads the challenge, pays, and retries with the credential. - Receipt. A paid response carries
Payment-Receipt(base64url JSON:method,reference,status,timestamp) andCache-Control: private. - Same rules. You are charged only for the outcomes listed under Prices; a refused or unsettled credential is answered with a
402carrying fresh challenges for both protocols and areason, and nothing is charged. A credential pays for one request: presented again for another, it is refused ascredential_spent; presented twice at once, the second is refused ascredential_in_use— retry that exact request in a moment. Standing access is sold over MPP too. - Lost a paid response? Retry the exact request with the same credential within two minutes: it is served from the payment already taken and not charged again. After that window a used credential is refused like any other. A standing access purchase is different: its key is returned once, and a failed purchase response is recovered its own way.
When something goes wrong
Every refusal below charges nothing and withholds the resource.
If a Brand API or Brand Context API request itself fails, a
500 for instance, the payment is not settled: the authorization you signed simply lapses.
Buying standing access
A purchase is settled before its key is issued, so some of its failures follow a payment that was taken. None of these answers carries a key, and apart from a refused settlement none asks for a new payment; each says what to do instead. The409 answers, the 500 answers that name a payment and 503 payment_outcome_unknown carry the payment’s paymentReference.
Standing access
One payment per request suits a handful of calls. For more, buy standing access once and use an ordinary API key from then on:1
Read the offer
GET https://api.brandfetch.io/v2/agents/access needs no credential and describes the deal: 20 prepaid credits per dollar, from 500 in whole dollars, one credit per Brand API or Brand Context API request, and the steps to pay. The full shape is in the reference.2
Pay for it
POST https://api.brandfetch.io/v2/agents/access?usd=5 without a payment answers a 402 quoting 1 and up clears Stripe’s card minimum. The same request with the signed x402 payment in PAYMENT-SIGNATURE, or with the MPP credential in Authorization: Payment …, completes the purchase. Its response carries Cache-Control: private and the settlement receipt: PAYMENT-RESPONSE for x402, Payment-Receipt for MPP. The clients above handle it the same way as a brand request.201 Created
201 and creates its organization; later ones answer 200 and add credits to the same key. A card names no wallet, so every card purchase answers 201 with its own organization and key, and cannot be topped up: keep the key. A card purchase carries the topUp block too, with a note saying exactly that: pay from an x402 or Tempo wallet instead to add credits to the key that wallet owns.3
Use the key
Send
Authorization: Bearer <key> like any API key. Every metered response carries x-api-key-quota, the credits remaining; a 403 means the balance is spent. Pay again from the same wallet to top the key up, and add rotateKey=true to replace the key while doing so. The response carries the new key, returned once like any other, holding the combined balance; the wallet’s earlier keys stop working once the new key has been returned, even if your client never receives that response. If the rotation is answered with an error instead of the new key, the old one keeps working. If you never saw its response at all, retry the exact request: a 409 credential_already_delivered means the rotation completed and the earlier keys no longer work, so pay again from the same wallet with rotateKey=true for a new one. The mcp.token connects the MCP server to the same organization: send it as a bearer token.409 credential_already_delivered without it. If the purchase is answered with a 500 that says to retry, or with no response at all, retry the exact request at once: the first retry to succeed within three minutes of the payment receives the key, unless the key was already returned in a response your client lost, which is answered 409 credential_already_delivered. A retry that receives the key does so with credits.deduplicated: true if the failed attempt had already granted the credits, and without the settlement receipt header. The credits are granted even when the key can no longer be returned: any retry carrying the payment completes the purchase. Buying standing access lists every answer and what to do; the complete contract is in the reference.