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.

  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.
RoutePage
GET /quotePrice a ciphertext's data item
POST /paySubmit a storage payment
POST /uploadStore ciphertext against a receipt
GET /unshield/quoteQuote a withdrawal
POST /unshieldWithdraw from the pool
GET /treeRead the commitment tree
GET /receipt/:idRead a receipt
GET /see/:refInspect an upload
GET /manifestFind the latest manifest
GET /healthHealth
GET /configConfig
POST /shield/buildShield build
POST /shield/confirmShield 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.

ValueEncodingRule
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 hexA 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 hex32 bytes big-endian, not reduced. Ciphertext roots and locators are hashes.
Address (Address)base58Decodes to exactly 32 bytes (32 to 44 characters).
Signature (Signature)base58Decodes to exactly 64 bytes (64 to 88 characters).
Irys id (IrysId)base64url43 characters of [A-Za-z0-9_-], 32 bytes.
Bytes (Base64)Standard base64Alphabet [A-Za-z0-9+/], padded so the length is a multiple of 4. Proof points, transactions, ciphertext and memos.
Memo (Memo)Standard base64At most 108 characters, decoding to at most 80 bytes. An encrypted note memo.
Time (Timestamp)ISO 8601UTC with Z, for example 2026-11-16T00:00:00.000Z.

A proof is three base64 points in groth16-solana byte order:

Proof
arequired
Base64
Exactly 64 bytes. The negated G1 point A.
brequired
Base64
Exactly 128 bytes. The G2 point B, with Fq2 coefficients in the syscall's order.
crequired
Base64
Exactly 64 bytes. The G1 point C.

The public inputs of the 2-in-2-out circuit, in circuit order: root, nullifiers[0], nullifiers[1], outputCommitments[0], outputCommitments[1], publicAmount, bindingHash.

PublicInputs
rootrequired
Field
The commitment tree root the proof was built against.
nullifiersrequired
[Field, Field]
The nullifiers of the two input notes, one of which may be a zero-amount dummy. Each creates a nullifier account.
outputCommitmentsrequired
[Field, Field]
The commitments of the two output notes. Both are inserted into the tree, a zero-valued output included.
publicAmountrequired
Field
The proof's public amount for the instruction's amount: lamports 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.
bindingHashrequired
Field
The proof's binding input, which ties it to one request: on pay 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:

BucketBytes
64 KiB65536
128 KiB131072
256 KiB262144
512 KiB524288
1 MiB1048576
2 MiB2097152
4 MiB4194304
8 MiB8388608
16 MiB16777216
32 MiB33554432
64 MiB67108864

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:

HeaderValue
X-Request-IdA UUID for this request.
X-Contract-VersionThe contract version the relayer speaks, 0.1.7.
Cache-Controlno-store.
X-Content-Type-Optionsnosniff.
Retry-AfterSeconds, on an error whose envelope carries retryAfterSeconds.

CORS

Browser calls are allowed from the relayer's exact list of origins (scheme://host[:port]).

SettingValue
Allowed methodsGET, POST, PUT, PATCH, DELETE, OPTIONS
Allowed request headersContent-Type
Exposed response headersX-Request-Id, Retry-After, X-Contract-Version
CredentialsNot sent
Preflight cache600 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:

JSON
{
  "error": {
    "code": "ORIGIN_NOT_ALLOWED",
    "message": "This origin is not allowed.",
    "retryable": false,
    "stage": "validation",
    "requestId": "e481922d-d742-4ce7-9d77-abe3cd41940f"
  }
}
error
coderequired
ErrorCode
The stable code to branch on. Every code is listed under Errors.
messagerequired
string
A sentence that can be shown to the holder as it is.
retryablerequired
boolean
true when sending the same request again can succeed.
stagerequired
ErrorStage
The step of the flow that failed. The schema allows validation, auth, read, upload, build, wallet, co_sign, simulation, send and confirmation; the stages each code arrives with are under Errors.
fieldErrors
Record<string, string[]>
On a schema failure: the messages per field, keyed by the field's path joined with . (for example publicInputs.root or memos.1), or form for the value as a whole.
programError
ProgramError
On a transaction a program refused: the program, as programId (Address), name (string) and number (integer, optional).
retryAfterSeconds
integer
When to try again, on RATE_LIMITED from the write limit. Also sent as the Retry-After header.
requestId
string
The request id to quote when reporting the failure. It matches the X-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.

CodeHTTPRetryableStageMeaning
VALIDATION_ERROR400novalidation, upload, walletA 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_ALLOWED403novalidationThe Origin header is not in the relayer's allowlist.
NOT_FOUND404noreadNo route, receipt, upload, signature, shield build or ciphertext matches.
PROGRAM_UNAVAILABLE409yesbuildThe 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_REQUIRED409nobuildThe 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_CONFLICT409noupload, walletThe 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_EXPIRED409yesconfirmationThe transaction's blockhash expired before it landed.
PAYLOAD_TOO_LARGE413novalidationThe request body exceeds the body limit.
UNSUPPORTED_MEDIA_TYPE415novalidationA body was sent without Content-Type: application/json.
SIMULATION_FAILED422from the stepsimulationThe transaction failed simulation.
CHAIN_REFUSED422from the stepthe failed stepThe chain refused the transaction; programError names the program and its error when the logs name one.
RATE_LIMITED429yesvalidationToo many write requests from one client in a minute; wait retryAfterSeconds.
INTERNAL_ERROR500yesreadThe request could not be completed; requestId identifies it.
UPSTREAM_UNAVAILABLE502yesreadThe Solana RPC is unavailable.
INSUFFICIENT_BALANCE409from the step, or nothe failed step, or uploadThe 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_EXPIRED409yesbuildThe 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_FAILED502yesreadThe storage price could not be retrieved from Irys, or the Solana RPC did not report the rent for the network refund.
RECEIPT_NOT_PAID409nouploadNo paid receipt matches the receipt given; pay it before uploading ciphertext.
NULLIFIER_SPENT409nobuild, or the failed stepA nullifier account already exists (build), or the program refused with DuplicateNullifier.
UNKNOWN_ROOT409nothe failed stepThe 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_INVALID422nosimulation, or the failed steppublicAmount or bindingHash does not match the request (simulation), or the program refused with InvalidProof.
NOT_GEODE422noread, confirmationThe reference is not a Geode upload (read), or a confirmed shield transaction does not contain the requested shield (confirmation).
IRYS_UNAVAILABLE502yesuploadAn Irys read or upload failed; retry with the same paid receipt.
RELAYER_FAILED502yesconfirmationThe transaction's outcome is not known yet; retry the same request.
STORAGE_PAYEE_KEY_REQUIRED409nobuildOn 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.

Response
statusrequired
'waiting' | 'ready'
waiting while the relayer cannot yet take payments, ready when it can.
moderequired
'chain'
The routes settle on chain.
contractVersionrequired
string
The contract version, 0.1.7.
reason
string
Why the relayer is waiting.

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:

JSON
{ "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.

Response
moderequired
'chain'
The routes settle on chain.
programIdrequired
Address | null
The Geode program id.
relayerrequired
Address | null
The relayer's public key. Every pay and unshield binding includes it, see Binding hashes.
clusterrequired
'devnet' | 'mainnet-beta'
The Solana cluster the relayer settles on.
feeBpsrequired
integer | null
Geode's fee in basis points, 0 to 10000, equal to the program config's fee.
bucketsrequired
Bucket[]
Every ciphertext bucket, ascending. See Buckets and terms.
termsrequired
Term[]
The terms the relayer's storage network accepts: ["permanent"] on the Irys network. GET /quote answers any other term with VALIDATION_ERROR naming these.
gatewayUrlrequired
string | null
The Irys gateway ciphertext is read from; append / and an Irys id. See Gateway.
artifactsUrlrequired
string | null
The browser directory that holds the circuit's geode.wasm and geode_final.zkey.
signingMessagerequired
string
The exact message the wallet signs once to derive the holder's keys. See Keys.
treeDepthrequired
26
The depth of the commitment tree.
tokenMintrequired
Address | null
The token mint.

signingMessage is always these two lines, joined by a single \n:

Text
Geode key derivation v1
Sign to unlock your encrypted vault. This does not send a transaction.
HTTP
GET /config

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

Request body
walletrequired
Address
The wallet that signs, pays the fee and deposits.
lamportsrequired
PositiveU64
The amount to shield.
proofrequired
Proof
The Groth16 proof. See How values travel.
publicInputsrequired
PublicInputs
The proof's public inputs. publicAmount is the deposit's public amount for lamports, and bindingHash binds wallet, lamports and memos.
memosrequired
[Memo, Memo]
One encrypted note memo per output commitment, in the same order.
Response
idrequired
string
The build id, 1 to 128 characters, passed to /shield/confirm.
transactionBase64required
Base64
The unsigned v0 transaction, for the wallet to sign.
blockhashrequired
string
The transaction's recent blockhash, base58.
lastValidBlockHeightrequired
integer
The last block height at which the transaction can land.

Checks, 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.

Request body: signed bytes
idrequired
string
The build id from /shield/build, 1 to 128 characters.
transactionBase64required
Base64
The wallet-signed transaction.
Request body: sent by the wallet
idrequired
string
The build id from /shield/build, 1 to 128 characters.
signaturerequired
Signature
The signature of the transaction the wallet submitted.
Response
signaturerequired
Signature
The shield transaction's signature.
slotrequired
integer
The slot it landed in.
outputCommitmentsrequired
[Field, Field]
The two commitments now in the tree, as built.

Checks, in order:

  1. Readiness (PROGRAM_UNAVAILABLE), then the body (UNSUPPORTED_MEDIA_TYPE, VALIDATION_ERROR).
  2. The build id exists (NOT_FOUND, "This shield build was not found.").
  3. When the build already has a signed transaction, the signature sent, or the signature of the bytes sent, must be that one (IDEMPOTENCY_CONFLICT, stage wallet); bytes that do not deserialize answer VALIDATION_ERROR ("The signed transaction bytes are malformed."). The relayer then follows that transaction again, rebroadcasting the bytes it holds.
  4. 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, stage wallet). 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).
  5. 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).
  6. The landed transaction must insert exactly the build's two output commitments, in order (NOT_GEODE, stage confirmation, "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.

HTTP
GET <Irys gateway URL>/bSAbr3nZWiTjjriWwg2eLRrxMwxlH4qJZy2TuMRr82c
Accept: application/octet-stream

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

TypeScript
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:

options
fetch
typeof fetch
The fetch to use. Defaults to the global one.
credentials
RequestCredentials
Passed to every fetch.
headers
Record<string, string>
Sent with every request.
MethodRouteReturns
health()GET /healthHealthResponse
config()GET /configConfigResponse
quote({ bytes, term, locator })GET /quoteQuoteResponse
pay(body)POST /payPayResponse
upload(body)POST /uploadUploadResponse
unshieldQuote({ lamports })GET /unshield/quoteUnshieldQuoteResponse
unshield(body)POST /unshieldUnshieldResponse
tree()GET /treeTreeResponse
receipt(id)GET /receipt/:idReceiptResponse
see(ref)GET /see/:refSeeResponse
manifest({ locator })GET /manifestManifestResponse
shieldBuild(body)POST /shield/buildShieldBuildResponse
shieldConfirm(body)POST /shield/confirmShieldConfirmResponse
gatewayUrl(id)GET /configThe 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.