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.

  1. Seal
  2. Quote
  3. Prove
  4. Pay
  5. Store
  6. Open
Every file, from your device to Irys. Dashed: what the chain sees. Solid: what stays with you.

Request

HTTP
GET /quote?bytes=2516582&term=permanent
Query
bytesrequired
integer
The complete ciphertext length in bytes, encryption framing included. A positive integer, at most 67108864 (the 64 MiB bucket). Sent as a decimal in the query string.
term
'30d' | '1y' | 'permanent'
How long the ciphertext is kept. Defaults to permanent. It must be one of the relayer's /config.terms; see Terms the relayer accepts and Terms and quotes.
locator
Hash32
The holder's locator, 0x 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

QuoteResponse
quoteIdrequired
string
The quote's id, 1 to 512 characters. Pass it to POST /pay as quoteId, unchanged.
bucketrequired
Bucket
The smallest bucket that holds bytes. The ciphertext is padded to exactly this length before upload.
termrequired
Term
The term priced.
priceLamportsrequired
U64
The Irys price, for this term, of the data item that will carry the ciphertext: the bucket plus the item's signed header and tags.
feeLamportsrequired
U64
Geode's fee: floor(priceLamports * feeBps / 10000).
networkLamportsrequired
U64
The network refund pay moves from the pool vault to the relayer, read from the cluster's rent when the quote is issued.
totalLamportsrequired
U64
priceLamports plus feeLamports plus networkLamports: the amount the proof spends.
feeBpsrequired
integer
The fee rate the fee was computed at, in basis points, 0 to 10000.
expiresAtrequired
Timestamp
Five minutes after the quote was issued: when POST /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:

StepRuleWhen it differs
GET /quotelocator sent for a manifest, absent for a file
POST /paylocator equal to the quote's, both absent includedVALIDATION_ERROR ("The receipt does not match the signed quote.")
POST /uploadlocator equal to the one the receipt was paid with, both absent includedIDEMPOTENCY_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:

  1. The relayer is ready (PROGRAM_UNAVAILABLE).
  2. The query schema (VALIDATION_ERROR with fieldErrors).
  3. The term is one of /config.terms (VALIDATION_ERROR).
  4. The program config exists (PROGRAM_UNAVAILABLE), its fee equals the relayer's fee rate and it lists this relayer (CONFIGURATION_REQUIRED).
  5. Irys prices the data item for the term (QUOTE_FAILED).
  6. The network refund is computed from the rent-exempt minimum the Solana RPC reports for an 8-byte account (QUOTE_FAILED when 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.

CodeRaised whenNext
PROGRAM_UNAVAILABLEThe relayer is not ready, or the program config account does not exist yet. Retryable.Retry later.
VALIDATION_ERRORbytes 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_REQUIREDThe relayer's fee rate differs from the program config's, or the program config does not list this relayer.Try again later.
QUOTE_FAILEDIrys could not price the data item, or the Solana RPC did not report the rent for the network refund. Retryable.Quote again.

Example

HTTP
GET /quote?bytes=2516582&term=permanent&locator=0xc956aee6dbf6a2442867a786c697bc0ca45e59b45653d9dfc722ee0da73c0bca
Accept: application/json