Section 4
HTTP 402
A server that wants to be paid answers 402 and names its price. The client pays and asks again. This page is the exact format of both messages.
4.1The exchange
- The client requests a resource, with no credentials.
- The server answers
402 Payment Requiredwith a JSON challenge. - The client pays the stated amount to the stated address as a private transfer.
- The client repeats the request with a
Doei-Paymentheader that names the transaction and is signed by the paying key. - The server finds the transfer in its own incoming payments, checks it, and answers with the resource and a
Doei-Receiptheader.
The server never asks the chain how much was paid, because the chain does not know. It reads the amount from its own private balance, which only it can decrypt.
4.2Challenge body
{
"doei": 1,
"accepts": [
{
"scheme": "rings-transfer",
"network": "solana-mainnet",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amount": "4200",
"payTo": "BAmBVKM2H2V6H3MxiGBpQmdVqz3vACgqUGUhJXnLti6z",
"resource": "https://search.example/v1/search?q=gpu+spot+price",
"nonce": "1794562322.AQFaF8MHLpE.9YpKxSnaxZY7KjRqEUgBxQ",
"expires": 1794562322
}
]
}| Field | Type | Meaning |
|---|---|---|
doei | 1 | Marks the format. A client rejects any other value. |
accepts | array | One entry per way to pay. Entries with an unknown scheme are skipped. |
scheme | "rings-transfer" | A confidential transfer on Helius Privacy Rings. |
network | string | solana-mainnet or solana-devnet. |
asset | base58 | Mint address of the token the server wants. |
amount | string | Price in base units, a positive integer. |
payTo | base58 | Address to pay. Must be registered with Privacy Rings. |
resource | string | The URL this payment unlocks. Bound into the proof. |
nonce | string | Opaque to the client, echoed in the proof. 8 to 256 characters. |
expires | number | Unix seconds. The server refuses the nonce after this. |
The price is public to anyone who makes the request. That is by design: a price list is not a secret. What stays confidential is which prices an agent actually paid, and how often.
4.3Doei-Payment header
Doei-Payment: v=1; tx=aRzPKykodnPkvP9Vntx7dwUXXf2nRmJECQDc3LsBPVskVQ54hPeMxA13xquzrJN5eQtE7HYiPVDrAEPpBY6c5w1; nonce=1794562322.AQFaF8MHLpE.9YpKxSnaxZY7KjRqEUgBxQ; payer=5G7o7GubkDFKvVyCJ6LwS9SqCngVAQDxae4KxVq8S6To; sig=F6JrJ50ZJ9bbFEbxtfGJMBg5XM5toQHmOu0Fwz-YmrlktBlN-eXOcrsJFBjrBzK-Bzqr1LN1ZfUwY14Xu6hjCg| Field | Type | Meaning |
|---|---|---|
v | 1 | Marks the format. |
tx | base58 | Signature of the Solana transaction that carried the transfer. |
nonce | string | The nonce from the challenge, unchanged. |
payer | base58 | The address that sent the transfer and signed this proof. |
sig | base64url | Ed25519 signature by the payer over the message below, 64 bytes. |
Fields are separated by a semicolon and a space. A field that appears twice makes the header invalid.
4.4What the proof signs
The payer signs five lines of UTF-8 text joined by a line feed, with no trailing line feed:
doei-payment-v1
<resource>
<nonce>
<tx>
<payTo>A transaction signature is public. Anyone watching the chain can copy it. The proof signature is what stops them from redeeming someone else's payment: only the key that sent the transfer can sign for it, and the signature is bound to one resource, one nonce and one payee.
4.5Server checks
paywall.verify runs these checks in order and stops at the first that fails. A failed proof gets a fresh 402 whose body carries error.code and error.reason next to the new challenge.
| Order | Code | The server refuses when |
|---|---|---|
| 01 | MALFORMED_PROOF | The header cannot be parsed. |
| 02 | UNKNOWN_NONCE | It did not issue that nonce for this resource and price. |
| 03 | NONCE_EXPIRED | The challenge is older than its expiry. |
| 04 | BAD_SIGNATURE | The proof is not signed by the payer it names. |
| 05 | PAYMENT_NOT_FOUND | No incoming transfer with that signature is visible yet. |
| 06 | WRONG_PAYER | The transfer came from a different address. |
| 07 | WRONG_ASSET | The transfer is in a different token. |
| 08 | UNDERPAID | The transfer is smaller than the price. |
| 09 | STALE_PAYMENT | The transfer was made before this challenge was issued. |
| 10 | FEE_MISSING | The payment did not carry the protocol fee. |
| 11 | ALREADY_REDEEMED | That transfer already paid for a request. |
Nonces are stateless. Each one carries its expiry and an HMAC over the resource, price, asset and payee, so a server does not store issued challenges. It does store redeemed transaction signatures, and that store must claim a signature atomically. The default keeps them in memory, which is correct for one process only.
4.6Doei-Receipt header
Doei-Receipt: v=1; tx=aRzPKykodnPkvP9Vntx7dwUXXf2nRmJECQDc3LsBPVskVQ54hPeMxA13xquzrJN5eQtE7HYiPVDrAEPpBY6c5w1; status=settledSent with the paid response. It repeats the transaction the server accepted. wallet.fetch passes it to the trace callback and leaves it on the response.
4.7Charging for an endpoint
On the provider side, createPaywall wraps a handler that takes a Request and returns a Response, which is the handler shape of Next.js route handlers, Hono, Bun and Deno. incoming is the provider wallet's view of what it received. The Rings rail implements it.
import { USDC, createPaywall, type IncomingPayments } from "@doei/sdk";
declare const incoming: IncomingPayments; // your wallet's view of what it received
const paywall = createPaywall({
network: "solana-mainnet",
asset: USDC,
payTo: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
secret: Buffer.from(process.env.PAYWALL_SECRET!, "hex"), // 32 bytes or more
incoming,
});
// 0.0042 USDC per request. Unpaid requests get 402 and a challenge.
export const GET = paywall.protect(4_200n, async (request, paid) => {
const query = new URL(request.url).searchParams.get("q");
return Response.json({ query, results: await search(query), paidBy: paid.payer });
});| Option | Type | Meaning |
|---|---|---|
network | Network | The cluster payments must arrive on. |
asset | Asset | The token the price is in. |
payTo | Address | The provider's registered address. |
secret | Uint8Array | 32 bytes or more. Keys the nonce HMAC. Rotate it to void open challenges. |
incoming | IncomingPayments | Looks up a received transfer by transaction signature. |
ttlSeconds | number | Lifetime of a challenge. Default 120. |
redeemed | RedeemedStore | Where spent signatures are recorded. Default: in memory. |
fee | object | false | The protocol fee a payment must have carried. Default on mainnet: the protocol's own. false turns the check off. |
A server that only gets paid needs no key that can spend. createRingsViewer opens the provider's history with a viewing key, which reads amounts and can move nothing, and that is all incoming asks for. The accept page makes the address and the viewing key in your browser and gives you the code to paste.
4.8The fee check
The payer's wallet adds the protocol fee on top of the price, as a second output of the same transfer. A fee is sealed like any other amount, so only its collector can read it. On mainnet the paywall asks the collector's read-only service what the payment's fee output held, and refuses a payment that left the fee out with FEE_MISSING.
POST https://doei.io/api/fee
content-type: application/json
{ "proof": "<the Doei-Payment header>", "resource": "<the URL paid for>", "payTo": "<the payee>" }
200 { "fee": "42" }The service answers only for a proof the payer signed, and only if that payer sent the transaction. So the two who can ask about a payment are its payer and the payee the proof was handed to, and both know the amount already. If the service cannot be reached, a paid request is served: set ifUnknown to "refuse" to turn that around.
4.9Client failures
What wallet.fetch raises, and whether money has moved when it does. The full list is in the SDK reference.
| Code | Paid | Meaning |
|---|---|---|
BODY_NOT_REPLAYABLE | No | The body is not a string. Nothing was sent. |
INVALID_CHALLENGE | No | The 402 body is not a Doei challenge. |
UNSUPPORTED_CHALLENGE | No | No entry matches the wallet's network and asset. |
CHALLENGE_EXPIRED | No | The challenge was stale on arrival. |
PRICE_ABOVE_LIMIT | No | The price is above maxAmount. |
POLICY_DENIED | No | The owner's policy refused the total. |
INSUFFICIENT_BALANCE | No | The private balance is too small. |
PAYMENT_NOT_ACCEPTED | Yes | The server answered 402 again. The receipt is in error.detail. |
4.10Relation to x402
x402 is an open protocol that uses the same status code for payments settled with public token transfers. Doei follows the same request, 402, pay, retry shape. It defines its own scheme, rings-transfer, because the settlement is different: the amount is not on the chain, so the server cannot verify a payment by reading a transaction. It has to find the transfer in its own private balance.
The two are not wire-compatible today. A Doei challenge has a doei field and Doei header names, and an x402 client will not understand it.