Reference
The HTTP payment scheme
The 402 body a gate answers with, the payment header an agent retries with, and the status codes.
Remit's payment scheme rides on HTTP 402 in the shape of x402, with the scheme name remit. A paid call is one round trip more than an unpaid one: the server names its price, the agent pays on chain, and the agent repeats the request with the payment's signature. The server verifies the payment itself by decrypting the hold made out to it. No facilitator takes part.
remit.fetch and gate in @remit/sdk speak this scheme. Implement it directly to pay or charge from another language.
1. The request without payment
The server answers 402 Payment Required:
{
"x402Version": 1,
"error": "payment required",
"accepts": [
{
"scheme": "remit",
"network": "solana-mainnet",
"mint": "<mint address>",
"payTo": "<payee address>",
"price": "40000",
"deadlineSeconds": 300,
"requestHash": "<64 hex characters>",
"resource": "https://api.example.com/quote?pair=SOL-USDC"
}
]
}| Field | Type | Meaning |
|---|---|---|
x402Version | number | 1. |
error | string | Why payment is asked: see Status codes. |
accepts[].scheme | string | remit. |
accepts[].network | string | solana-mainnet, solana-devnet or solana-localnet. |
accepts[].mint | Address | The mint the price is in. |
accepts[].payTo | Address | The payee's wallet address. |
accepts[].price | string | The price of this call in base units of mint. |
accepts[].deadlineSeconds | number | How long the hold stays open for the payee to settle. At most 86,400. |
accepts[].requestHash | hex, 32 bytes | The hash of this request, which the payment must carry. |
accepts[].resource | string | The URL being paid for. |
The request hash
requestHash = sha256( METHOD + " " + URL + "\n" + hex(sha256(body)) )Lowercase hex. METHOD is the HTTP method, URL the full URL as in resource, and body the request body's bytes (empty for a request without one). The client takes the hash from the 402 body as it stands. The server recomputes it from the retried request, so a payment for one request cannot be used for another.
2. The payment
The client sends one pay transaction from its remit: price goes into a hold for payTo, carrying requestHash and a deadline deadlineSeconds from now. A payment the remit's terms do not allow is never built, and the client gets the error that names the term.
3. The retry
The client repeats the same request with one header more:
X-Remit-Payment: <signature of the pay transaction, base58>The header holds the signature and nothing else. No key travels with it.
4. Verification and the response
The server:
- decrypts the hold that transaction created, with the payee's own viewing key
- checks that the hold is for this payee, in this mint, for at least
price, with therequestHashit recomputes from the request, and with enough of its deadline left to serve and settle - refuses a signature it has already served
- serves the response, with the header
X-Remit-Receipt: <signature of the pay transaction> - settles the hold, with
sha256(response body)in lowercase hex as the response hash
Settlement happens after the response is sent. The settled payment is the receipt.
Status codes
| Status | When | Body |
|---|---|---|
402 | No X-Remit-Payment header. | The body above, error: "payment required". |
402 | The signature names no payment to this payee. | error: "payment not found". |
402 | The hold's amount, mint or request hash is not what this request needs. | error: "payment does not match". |
402 | The hold's deadline is too close to serve and settle. | error: "hold expires too soon". |
409 | The signature was already used for a served request. | |
| the resource's own | The payment is good. | The response, with X-Remit-Receipt. |
Every 402 carries a fresh accepts, so the client can pay again.
Checking a receipt against the request and the response
A receipt holds the request hash and, once settled, the response hash. Anyone who also has the request and the response computes the two hashes as above and compares them with the receipt on Verify.