Relayer API
API overview
How to call the Geode relayer over HTTP, how its values are encoded, and every error code it can answer with.
The relayer is the service that turns a holder's proof into a Solana transaction and a sealed file into an Irys upload. It prices storage, submits pay and unshield with itself as fee payer, writes ciphertext to Irys against a paid receipt, serves the commitment tree the browser proves against, and finds the latest manifest for a locator. The holder's wallet signs only shield. Everything else reaches the chain through these routes. See The relayer for its place in the design.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
| Route | Page |
|---|---|
GET /quote | Price a ciphertext's data item |
POST /pay | Submit a storage payment |
POST /upload | Store ciphertext against a receipt |
GET /unshield/quote | Quote a withdrawal |
POST /unshield | Withdraw from the pool |
GET /tree | Read the commitment tree |
GET /receipt/:id | Read a receipt |
GET /see/:ref | Inspect an upload |
GET /manifest | Find the latest manifest |
GET /health | Health |
GET /config | Config |
POST /shield/build | Shield build |
POST /shield/confirm | Shield confirm |
Ciphertext itself is read from the Irys gateway, not from these routes; see Gateway.
Base URL
Every path on these pages is relative to the base URL of the Geode relayer.
Requests and responses
Requests and responses are JSON over HTTP. Every POST sends Content-Type: application/json; a body with any other content type is refused with UNSUPPORTED_MEDIA_TYPE before it is read, and a body that is not valid JSON is refused with VALIDATION_ERROR. Successful responses are 200 with an application/json body.
Request objects are strict: an unknown key in a body or a query string is a VALIDATION_ERROR.
The OpenAPI 3.1 document for every route ships in @geode/contract as openapi.json, version 0.1.7, generated from the same zod schemas the relayer validates with.
How values travel
Amounts travel as decimal strings, so no lamport value loses precision in JSON. Slots, leaf indexes and block heights are JSON integers.
| Value | Encoding | Rule |
|---|---|---|
Lamports (U64) | Decimal string | ^(0|[1-9][0-9]*)$, at most 18446744073709551615 (2^64 - 1). No sign, no leading zeros. PositiveU64 also excludes "0". |
Field (Field) | 0x + 64 lowercase hex | A canonical BN254 scalar: 32 bytes big-endian, value below 21888242871839275222246405745257275088548364400416034343698204186575808495617. Commitments, nullifiers, roots, receipts, binding hashes and public amounts are fields. |
Hash (Hash32) | 0x + 64 lowercase hex | 32 bytes big-endian, not reduced. Ciphertext roots and locators are hashes. |
Address (Address) | base58 | Decodes to exactly 32 bytes (32 to 44 characters). |
Signature (Signature) | base58 | Decodes to exactly 64 bytes (64 to 88 characters). |
Irys id (IrysId) | base64url | 43 characters of [A-Za-z0-9_-], 32 bytes. |
Bytes (Base64) | Standard base64 | Alphabet [A-Za-z0-9+/], padded so the length is a multiple of 4. Proof points, transactions, ciphertext and memos. |
Memo (Memo) | Standard base64 | At most 108 characters, decoding to at most 80 bytes. An encrypted note memo. |
Time (Timestamp) | ISO 8601 | UTC with Z, for example 2026-11-16T00:00:00.000Z. |
A proof is three base64 points in groth16-solana byte order:
arequiredBase64brequiredBase64crequiredBase64The public inputs of the 2-in-2-out circuit, in circuit order: root, nullifiers[0], nullifiers[1], outputCommitments[0], outputCommitments[1], publicAmount, bindingHash.
rootrequiredFieldnullifiersrequired[Field, Field]outputCommitmentsrequired[Field, Field]publicAmountrequiredFieldlamports on shield, lamports plus networkLamports on unshield, price plus fee plus networkLamports on pay. The relayer recomputes it from the request and refuses a mismatch. See Spending: two in, two out.bindingHashrequiredFieldpay the receipt, price, fee, networkLamports, relayer and memos; on unshield the recipient, amount, networkLamports, relayer and memos; on shield the wallet, amount and memos. The relayer recomputes it from the request and refuses a mismatch. See Binding hashes.The proof that pays explains how these are produced.
The network refund
networkLamports is the network refund: the lamports pay and unshield move from the pool vault to the relayer, which repay it the rent of the two nullifier accounts it creates and the transaction's signature fee. It equals twice the rent-exempt minimum of an 8-byte account plus 5,000 lamports. The program computes it from the Rent sysvar as relayer_refund, and the relayer from its RPC, so the figure follows the cluster's rent. The proof spends it and binds it: GET /quote and GET /unshield/quote return it, and POST /pay and POST /unshield send it back unchanged.
Buckets and terms
Ciphertext is padded to a bucket before it is priced, paid for and stored. A bucket is the smallest of these sizes, in bytes, that holds the complete ciphertext including its encryption framing:
| Bucket | Bytes |
|---|---|
| 64 KiB | 65536 |
| 128 KiB | 131072 |
| 256 KiB | 262144 |
| 512 KiB | 524288 |
| 1 MiB | 1048576 |
| 2 MiB | 2097152 |
| 4 MiB | 4194304 |
| 8 MiB | 8388608 |
| 16 MiB | 16777216 |
| 32 MiB | 33554432 |
| 64 MiB | 67108864 |
A term is one of 30d, 1y or permanent. A relayer accepts the terms its storage network takes, listed in /config.terms. See Terms and quotes. bucketFor(bytes) in @geode/contract returns the bucket for a ciphertext length.
Response headers
Every response carries:
| Header | Value |
|---|---|
X-Request-Id | A UUID for this request. |
X-Contract-Version | The contract version the relayer speaks, 0.1.7. |
Cache-Control | no-store. |
X-Content-Type-Options | nosniff. |
Retry-After | Seconds, on an error whose envelope carries retryAfterSeconds. |
CORS
Browser calls are allowed from the relayer's exact list of origins (scheme://host[:port]).
| Setting | Value |
|---|---|
| Allowed methods | GET, POST, PUT, PATCH, DELETE, OPTIONS |
| Allowed request headers | Content-Type |
| Exposed response headers | X-Request-Id, Retry-After, X-Contract-Version |
| Credentials | Not sent |
| Preflight cache | 600 seconds |
A request whose Origin header names an origin outside the list is refused with ORIGIN_NOT_ALLOWED (403) before any route runs. A request with no Origin header, such as one from a script or server, is not affected.
Write rate limit
Every POST counts against a limit of 120 write requests per client per minute, in fixed one-minute windows. Past the limit, the relayer answers RATE_LIMITED with retryAfterSeconds, the seconds until the window resets, and a Retry-After header. The limit is checked before the route runs. Reads are not limited.
Body limit
A request body may be at most 90 MiB (94371840 bytes); a larger one is refused with PAYLOAD_TOO_LARGE. The limit leaves room for the largest upload: ciphertext of up to the 64 MiB bucket, which is 89478488 characters of base64, inside its JSON body.
The error envelope
Every failure, on every route, answers with one JSON shape and the HTTP status of its code. A request from an origin outside the allowlist, for example:
{
"error": {
"code": "ORIGIN_NOT_ALLOWED",
"message": "This origin is not allowed.",
"retryable": false,
"stage": "validation",
"requestId": "e481922d-d742-4ce7-9d77-abe3cd41940f"
}
}messagerequiredstringretryablerequiredbooleantrue when sending the same request again can succeed.stagerequiredErrorStagevalidation, auth, read, upload, build, wallet, co_sign, simulation, send and confirmation; the stages each code arrives with are under Errors.fieldErrorsRecord<string, string[]>. (for example publicInputs.root or memos.1), or form for the value as a whole.programErrorProgramErrorprogramId (Address), name (string) and number (integer, optional).retryAfterSecondsintegerRATE_LIMITED from the write limit. Also sent as the Retry-After header.requestIdstringX-Request-Id header.Errors
This is the one list of codes the relayer speaks. Endpoint pages name the codes their route raises and link here.
| Code | HTTP | Retryable | Stage | Meaning |
|---|---|---|---|---|
VALIDATION_ERROR | 400 | no | validation, upload, wallet | A body, query or path value failed the contract schema, the JSON is malformed, signed transaction bytes do not deserialize, a value disagrees with the quote or receipt it refers to (validation, upload), or signed shield bytes were refused or changed after the wallet signed them (wallet). On GET /quote, also a term outside /config.terms ("Unsupported storage term. Supported terms:" and the list). fieldErrors names the fields when the schema caught it. |
ORIGIN_NOT_ALLOWED | 403 | no | validation | The Origin header is not in the relayer's allowlist. |
NOT_FOUND | 404 | no | read | No route, receipt, upload, signature, shield build or ciphertext matches. |
PROGRAM_UNAVAILABLE | 409 | yes | build | The relayer is not ready: it cannot yet read the Geode program, its lookup table, or its config or pool account, including when a quote or transaction is prepared. |
CONFIGURATION_REQUIRED | 409 | no | build | The relayer is not set up for this request: its fee rate differs from the program config's, or the program config does not list it as a relayer. |
IDEMPOTENCY_CONFLICT | 409 | no | upload, wallet | The locator sent to POST /upload differs from the one the receipt was paid with, or Irys already holds different bytes or tags for the receipt (upload); or a shield build already has a different signed transaction (wallet). |
TRANSACTION_EXPIRED | 409 | yes | confirmation | The transaction's blockhash expired before it landed. |
PAYLOAD_TOO_LARGE | 413 | no | validation | The request body exceeds the body limit. |
UNSUPPORTED_MEDIA_TYPE | 415 | no | validation | A body was sent without Content-Type: application/json. |
SIMULATION_FAILED | 422 | from the step | simulation | The transaction failed simulation. |
CHAIN_REFUSED | 422 | from the step | the failed step | The chain refused the transaction; programError names the program and its error when the logs name one. |
RATE_LIMITED | 429 | yes | validation | Too many write requests from one client in a minute; wait retryAfterSeconds. |
INTERNAL_ERROR | 500 | yes | read | The request could not be completed; requestId identifies it. |
UPSTREAM_UNAVAILABLE | 502 | yes | read | The Solana RPC is unavailable. |
INSUFFICIENT_BALANCE | 409 | from the step, or no | the failed step, or upload | The program refused with InsufficientPoolFunds: the pool vault cannot cover the transfer. On POST /upload (stage upload, not retryable): the relayer could not fund the Irys storage the upload needs. |
QUOTE_EXPIRED | 409 | yes | build | The quoteId is malformed, not signed by this relayer, or past its expiresAt; or the networkLamports sent is no longer the current network refund ("The network refund changed. Request a fresh quote."). Request a fresh quote. |
QUOTE_FAILED | 502 | yes | read | The storage price could not be retrieved from Irys, or the Solana RPC did not report the rent for the network refund. |
RECEIPT_NOT_PAID | 409 | no | upload | No paid receipt matches the receipt given; pay it before uploading ciphertext. |
NULLIFIER_SPENT | 409 | no | build, or the failed step | A nullifier account already exists (build), or the program refused with DuplicateNullifier. |
UNKNOWN_ROOT | 409 | no | the failed step | The program refused with UnknownRoot: the proof uses a tree root the pool does not accept. Read the tree again and prove against its root. |
PROOF_INVALID | 422 | no | simulation, or the failed step | publicAmount or bindingHash does not match the request (simulation), or the program refused with InvalidProof. |
NOT_GEODE | 422 | no | read, confirmation | The reference is not a Geode upload (read), or a confirmed shield transaction does not contain the requested shield (confirmation). |
IRYS_UNAVAILABLE | 502 | yes | upload | An Irys read or upload failed; retry with the same paid receipt. |
RELAYER_FAILED | 502 | yes | confirmation | The transaction's outcome is not known yet; retry the same request. |
STORAGE_PAYEE_KEY_REQUIRED | 409 | no | build | On POST /upload: the relayer is not set up to fund the Irys storage the upload needs. |
A code that comes from a transaction the relayer built, simulated or sent (SIMULATION_FAILED, CHAIN_REFUSED and the program refusals INSUFFICIENT_BALANCE, NULLIFIER_SPENT, UNKNOWN_ROOT, PROOF_INVALID) takes stage from the step that failed: build, wallet, simulation, send or confirmation. SIMULATION_FAILED, CHAIN_REFUSED and INSUFFICIENT_BALANCE take retryable from that step too; NULLIFIER_SPENT, UNKNOWN_ROOT and PROOF_INVALID are always retryable: false, since the same proof is refused again. A transaction that changed after the wallet signed it answers VALIDATION_ERROR with stage wallet. When a submitted transaction is recorded as failed on chain, the code arrives with stage confirmation and retryable: false.
The typed client turns a response that is not an envelope into one. An error status whose body is not the envelope becomes UPSTREAM_UNAVAILABLE (retryable) at 500 or above and INTERNAL_ERROR (not retryable) below 500. A success whose body is not JSON or does not match the route's schema becomes RELAYER_FAILED (retryable, "The relayer returned an invalid response."). All three carry stage read.
Health
GET /health reports whether the relayer is ready. It answers 200 with this body in every state.
statusrequired'waiting' | 'ready'waiting while the relayer cannot yet take payments, ready when it can.moderequired'chain'contractVersionrequiredstring0.1.7.reasonstringwaiting.The relayer is ready once it can read the Geode program, its lookup table and its config and pool accounts on chain; while waiting it checks again every 30 seconds. The routes that build or submit (/quote, /unshield/quote, /manifest, /see/:ref, /pay, /unshield, /upload, /shield/build, /shield/confirm) answer PROGRAM_UNAVAILABLE until then.
A ready relayer answers:
{ "status": "ready", "mode": "chain", "contractVersion": "0.1.7" }Config
GET /config returns the public facts a client needs before it seals, proves or pays: the program, the relayer address pay and unshield proofs bind to, the fee rate and the encoding constants.
moderequired'chain'programIdrequiredAddress | nullrelayerrequiredAddress | nullclusterrequired'devnet' | 'mainnet-beta'feeBpsrequiredinteger | nulltermsrequiredTerm[]["permanent"] on the Irys network. GET /quote answers any other term with VALIDATION_ERROR naming these.gatewayUrlrequiredstring | null/ and an Irys id. See Gateway.artifactsUrlrequiredstring | nullgeode.wasm and geode_final.zkey.signingMessagerequiredstringtreeDepthrequired26tokenMintrequiredAddress | nullsigningMessage is always these two lines, joined by a single \n:
Geode key derivation v1
Sign to unlock your encrypted vault. This does not send a transaction.GET /configShield build
POST /shield/build builds the one transaction the holder's wallet signs: shield, which moves SOL from the wallet into the pool. The browser proves the deposit for two output notes with their memos; the relayer returns an unsigned v0 transaction carrying that proof, with the wallet as fee payer. See Shield SOL.
walletrequiredAddresslamportsrequiredPositiveU64publicInputsrequiredPublicInputspublicAmount is the deposit's public amount for lamports, and bindingHash binds wallet, lamports and memos.memosrequired[Memo, Memo]idrequiredstring/shield/confirm.transactionBase64requiredBase64blockhashrequiredstringlastValidBlockHeightrequiredintegerChecks, in order: readiness (PROGRAM_UNAVAILABLE), the body (UNSUPPORTED_MEDIA_TYPE, then VALIDATION_ERROR with fieldErrors), then publicAmount and bindingHash against lamports, wallet and memos (PROOF_INVALID, stage simulation, "The proof public amount or binding does not match this instruction."). The relayer then builds and simulates the transaction with the relayer's lookup table; a refusal there answers with the code of the step that failed (see Errors). The build is kept under its id.
Shield confirm
POST /shield/confirm takes the signed shield back. The body carries the build id and either the signed transaction bytes for the relayer to send, or the signature of a transaction the wallet sent itself.
idrequiredstring/shield/build, 1 to 128 characters.transactionBase64requiredBase64idrequiredstring/shield/build, 1 to 128 characters.signaturerequiredSignaturesignaturerequiredSignatureslotrequiredintegeroutputCommitmentsrequired[Field, Field]Checks, in order:
- Readiness (
PROGRAM_UNAVAILABLE), then the body (UNSUPPORTED_MEDIA_TYPE,VALIDATION_ERROR). - The build
idexists (NOT_FOUND, "This shield build was not found."). - When the build already has a signed transaction, the signature sent, or the signature of the bytes sent, must be that one (
IDEMPOTENCY_CONFLICT, stagewallet); bytes that do not deserialize answerVALIDATION_ERROR("The signed transaction bytes are malformed."). The relayer then follows that transaction again, rebroadcasting the bytes it holds. - Signed bytes: they must fit one packet and deserialize, their lookup tables must load, the wallet must be the fee payer with a valid signature, and the transaction must call the Geode program and no program other than Compute Budget, Associated Token and Lighthouse (
VALIDATION_ERROR, stagewallet). They are simulated with signature verification, recorded under the build and sent; the relayer rebroadcasts them until they land or their blockhash expires (TRANSACTION_EXPIRED). - A signature: the relayer follows it until it lands and then records it under the build. A wallet-sent transaction is never declared expired; until it is seen the answer is
RELAYER_FAILED(retryable). - The landed transaction must insert exactly the build's two output commitments, in order (
NOT_GEODE, stageconfirmation, "This transaction does not contain the requested shield.").
A transaction that fails on chain answers with the code of the step that failed. Confirming is idempotent per build id: once a build has a signed transaction, the same id with the same signature or bytes returns the same result.
Gateway
The relayer serves no gateway route of its own: config.gatewayUrl and every gatewayUrl it returns point at the Irys gateway. A ciphertext's URL is config.gatewayUrl, / and the Irys id, and it answers the padded ciphertext as raw bytes, exactly one bucket long; the browser decrypts them.
GET <Irys gateway URL>/bSAbr3nZWiTjjriWwg2eLRrxMwxlH4qJZy2TuMRr82c
Accept: application/octet-streamTyped client
@geode/contract ships a client for every JSON route, built on fetch, that runs in the browser, in server components and in scripts. It sends and parses with the same zod schemas the relayer validates with, so a response that drifts from the contract fails at the call.
import { createClient, ApiClientError } from '@geode/contract'
const client = createClient('https://api.geode.directory')
try {
const quote = await client.quote({ bytes: 2516582, term: 'permanent' })
} catch (error) {
if (error instanceof ApiClientError && error.details.retryable) {
// error.code, error.status, error.details.stage
}
}createClient(baseUrl, options) takes these options:
fetchtypeof fetchcredentialsRequestCredentialsheadersRecord<string, string>| Method | Route | Returns |
|---|---|---|
health() | GET /health | HealthResponse |
config() | GET /config | ConfigResponse |
quote({ bytes, term, locator }) | GET /quote | QuoteResponse |
pay(body) | POST /pay | PayResponse |
upload(body) | POST /upload | UploadResponse |
unshieldQuote({ lamports }) | GET /unshield/quote | UnshieldQuoteResponse |
unshield(body) | POST /unshield | UnshieldResponse |
tree() | GET /tree | TreeResponse |
receipt(id) | GET /receipt/:id | ReceiptResponse |
see(ref) | GET /see/:ref | SeeResponse |
manifest({ locator }) | GET /manifest | ManifestResponse |
shieldBuild(body) | POST /shield/build | ShieldBuildResponse |
shieldConfirm(body) | POST /shield/confirm | ShieldConfirmResponse |
gatewayUrl(id) | GET /config | The ciphertext's URL as a string: config.gatewayUrl, / and the Irys id. Throws CONFIGURATION_REQUIRED when gatewayUrl is null |
Every method takes a last, optional call argument: signal (an AbortSignal) and headers. A failed call throws ApiClientError, which carries status (the HTTP status), body (the envelope), details (the envelope's error) and code. A body that is an envelope throws whatever its status.
Most applications call the relayer through the SDK, which wraps these routes in store, open and the rest. See Install and createGeode.