Docs4HTTP 402

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

  1. The client requests a resource, with no credentials.
  2. The server answers 402 Payment Required with a JSON challenge.
  3. The client pays the stated amount to the stated address as a private transfer.
  4. The client repeats the request with a Doei-Payment header that names the transaction and is signed by the paying key.
  5. The server finds the transfer in its own incoming payments, checks it, and answers with the resource and a Doei-Receipt header.

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

402 response 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
    }
  ]
}
FieldTypeMeaning
doei1Marks the format. A client rejects any other value.
acceptsarrayOne entry per way to pay. Entries with an unknown scheme are skipped.
scheme"rings-transfer"A confidential transfer on Helius Privacy Rings.
networkstringsolana-mainnet or solana-devnet.
assetbase58Mint address of the token the server wants.
amountstringPrice in base units, a positive integer.
payTobase58Address to pay. Must be registered with Privacy Rings.
resourcestringThe URL this payment unlocks. Bound into the proof.
noncestringOpaque to the client, echoed in the proof. 8 to 256 characters.
expiresnumberUnix 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

request header
Doei-Payment: v=1; tx=aRzPKykodnPkvP9Vntx7dwUXXf2nRmJECQDc3LsBPVskVQ54hPeMxA13xquzrJN5eQtE7HYiPVDrAEPpBY6c5w1; nonce=1794562322.AQFaF8MHLpE.9YpKxSnaxZY7KjRqEUgBxQ; payer=5G7o7GubkDFKvVyCJ6LwS9SqCngVAQDxae4KxVq8S6To; sig=F6JrJ50ZJ9bbFEbxtfGJMBg5XM5toQHmOu0Fwz-YmrlktBlN-eXOcrsJFBjrBzK-Bzqr1LN1ZfUwY14Xu6hjCg
FieldTypeMeaning
v1Marks the format.
txbase58Signature of the Solana transaction that carried the transfer.
noncestringThe nonce from the challenge, unchanged.
payerbase58The address that sent the transfer and signed this proof.
sigbase64urlEd25519 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:

proof message
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.

OrderCodeThe server refuses when
01MALFORMED_PROOFThe header cannot be parsed.
02UNKNOWN_NONCEIt did not issue that nonce for this resource and price.
03NONCE_EXPIREDThe challenge is older than its expiry.
04BAD_SIGNATUREThe proof is not signed by the payer it names.
05PAYMENT_NOT_FOUNDNo incoming transfer with that signature is visible yet.
06WRONG_PAYERThe transfer came from a different address.
07WRONG_ASSETThe transfer is in a different token.
08UNDERPAIDThe transfer is smaller than the price.
09STALE_PAYMENTThe transfer was made before this challenge was issued.
10FEE_MISSINGThe payment did not carry the protocol fee.
11ALREADY_REDEEMEDThat 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

response header
Doei-Receipt: v=1; tx=aRzPKykodnPkvP9Vntx7dwUXXf2nRmJECQDc3LsBPVskVQ54hPeMxA13xquzrJN5eQtE7HYiPVDrAEPpBY6c5w1; status=settled

Sent 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.

examples/provider.ts
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 });
});
OptionTypeMeaning
networkNetworkThe cluster payments must arrive on.
assetAssetThe token the price is in.
payToAddressThe provider's registered address.
secretUint8Array32 bytes or more. Keys the nonce HMAC. Rotate it to void open challenges.
incomingIncomingPaymentsLooks up a received transfer by transaction signature.
ttlSecondsnumberLifetime of a challenge. Default 120.
redeemedRedeemedStoreWhere spent signatures are recorded. Default: in memory.
feeobject | falseThe 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.

the fee check
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.

CodePaidMeaning
BODY_NOT_REPLAYABLENoThe body is not a string. Nothing was sent.
INVALID_CHALLENGENoThe 402 body is not a Doei challenge.
UNSUPPORTED_CHALLENGENoNo entry matches the wallet's network and asset.
CHALLENGE_EXPIREDNoThe challenge was stale on arrival.
PRICE_ABOVE_LIMITNoThe price is above maxAmount.
POLICY_DENIEDNoThe owner's policy refused the total.
INSUFFICIENT_BALANCENoThe private balance is too small.
PAYMENT_NOT_ACCEPTEDYesThe 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.