Relayer API
GET /quote
How to price the Irys data item that will carry a ciphertext, for its bucket, term and locator, before paying for it.
GET /quote prices storage for one ciphertext: it picks the bucket the ciphertext pads to and returns the Irys price of the data item that will carry it, Geode's fee, the network refund (networkLamports) and a quoteId that POST /pay must name. It is called after the file is sealed and before the proof is built, since the proof spends exactly the quoted total.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
Request
GET /quote?bytes=2516582&term=permanentbytesrequiredinteger67108864 (the 64 MiB bucket). Sent as a decimal in the query string.term'30d' | '1y' | 'permanent'permanent. It must be one of the relayer's /config.terms; see Terms the relayer accepts and Terms and quotes.locatorHash320x and 64 lowercase hex characters. Sent only for a manifest, so the price covers its Geode-Locator tag; see The locator. The SDK sends it for every manifest it stores.No other query keys are accepted.
Response
quoteIdrequiredstringPOST /pay as quoteId, unchanged.bucketrequiredBucketbytes. The ciphertext is padded to exactly this length before upload.termrequiredTermpriceLamportsrequiredU64feeLamportsrequiredU64floor(priceLamports * feeBps / 10000).networkLamportsrequiredU64pay moves from the pool vault to the relayer, read from the cluster's rent when the quote is issued.totalLamportsrequiredU64priceLamports plus feeLamports plus networkLamports: the amount the proof spends.feeBpsrequiredintegerexpiresAtrequiredTimestampPOST /pay stops accepting it.What is priced
Irys charges for the whole data item it stores, not for the ciphertext alone. The relayer prices exactly the item POST /upload will write: the bucket's bytes plus the item's ANS-104 header, signed by the relayer, with its signature, owner, 32-byte anchor and serialized tags. The tags are Geode-Receipt, Geode-Locator when a locator is sent, and Geode-Term, in that order. The relayer measures the header with the same serializer it uploads with, and refuses to upload an item whose size differs from the one quoted.
The locator
A manifest upload carries one more tag than a file upload, Geode-Locator, so its data item is larger and its price higher. Send the holder's locator to GET /quote for a manifest and leave it out for a file. The quoteId carries the locator, and the same value must travel through every step of that payment:
| Step | Rule | When it differs |
|---|---|---|
GET /quote | locator sent for a manifest, absent for a file | |
POST /pay | locator equal to the quote's, both absent included | VALIDATION_ERROR ("The receipt does not match the signed quote.") |
POST /upload | locator equal to the one the receipt was paid with, both absent included | IDEMPOTENCY_CONFLICT, stage upload ("The manifest metadata does not match the paid quote.") |
The locator is a public lookup tag; the file key and the view key never enter these requests. See The manifest.
Terms the relayer accepts
A relayer quotes only the terms its storage network takes, and lists them in /config.terms. On the Irys network that is permanent.
A quote for any other term answers VALIDATION_ERROR (stage validation) with the supported terms in its message, for example "Unsupported storage term. Supported terms: permanent."
Behaviour
The checks run in this order:
- The relayer is ready (
PROGRAM_UNAVAILABLE). - The query schema (
VALIDATION_ERRORwithfieldErrors). - The term is one of
/config.terms(VALIDATION_ERROR). - The program config exists (
PROGRAM_UNAVAILABLE), its fee equals the relayer's fee rate and it lists this relayer (CONFIGURATION_REQUIRED). - Irys prices the data item for the term (
QUOTE_FAILED). - The network refund is computed from the rent-exempt minimum the Solana RPC reports for an 8-byte account (
QUOTE_FAILEDwhen the RPC does not answer it).
Every call issues a new quote. The quoteId is signed by the relayer and carries the bucket, term, price, fee, network refund, locator and expiry itself, so it stays valid until expiresAt. A POST /pay that names the quote must carry the same bucket, term, priceLamports, feeLamports, networkLamports and locator, and a proof that spends totalLamports. A quote that has expired, or whose networkLamports is no longer the current network refund, is answered with QUOTE_EXPIRED at pay time: quote again, rebuild the proof for the new total, and pay.
bucketFor(bytes) from @geode/contract returns the same bucket the relayer picks, so the browser can pad the ciphertext before the quote returns.
Errors
Codes are explained in full under Errors.
| Code | Raised when | Next |
|---|---|---|
PROGRAM_UNAVAILABLE | The relayer is not ready, or the program config account does not exist yet. Retryable. | Retry later. |
VALIDATION_ERROR | bytes is missing, not a positive integer or above 67108864; term is not a term; locator is not 0x and 64 lowercase hex characters; or the query has another key. fieldErrors names the key. Also a term outside /config.terms, with the supported terms in message. | Fix the query. A ciphertext above 64 MiB cannot be stored as one file; a term must be one the relayer lists. |
CONFIGURATION_REQUIRED | The relayer's fee rate differs from the program config's, or the program config does not list this relayer. | Try again later. |
QUOTE_FAILED | Irys could not price the data item, or the Solana RPC did not report the rent for the network refund. Retryable. | Quote again. |
Example
GET /quote?bytes=2516582&term=permanent&locator=0xc956aee6dbf6a2442867a786c697bc0ca45e59b45653d9dfc722ee0da73c0bca
Accept: application/jsonconst quote = await client.quote({ bytes: ciphertext.length, term: 'permanent', locator })