HTTP API

Overview

The HTTP API reads the voynich program's accounts as JSON, builds the transactions a wallet signs, follows them, and carries encrypted inputs to enclaves. The SDK and the CLI are clients of it.

Base URL#

The API is served at https://<api host>, the address of the Voynich API. Every path on these pages is relative to it.

  • Every read is public. No route takes a key, a session or a cookie.
  • A route that builds a transaction takes a wallet address in its body. The program checks the signer when the transaction lands.
  • Requests with a body send Content-Type: application/json. Responses are JSON, except the two event streams.
  • A request body is at most 1,048,576 bytes.
  • A request that carries an Origin header is answered only when that origin is on the API's allow list.

Every response carries these headers:

HeaderValue
X-Request-IdAn id for this request.
X-Contract-VersionThe version of the API's contract, the same value as contractVersion in GET /health.
Cache-Controlno-store

Conventions#

KindWritten as
AmountA decimal string of base units, such as "100000". It fits an unsigned 64-bit integer.
SlotA decimal string, such as "1000".
AddressBase58 of 32 bytes.
Transaction signatureBase58 of 64 bytes.
HashSHA-256 as 64 lowercase hex characters.
Measurement96 lowercase hex characters (48 bytes).
Encryption keyPadded base64 of 32 bytes.
Receipt signaturePadded base64 of 64 bytes.
EnvelopePadded base64 of at least 73 bytes whose first byte is 1.
Wrapped keyAn envelope of exactly 105 bytes.
Ciphertext bytes, transactionsPadded base64.
Byte count, share in basis points, layout versionA JSON number.
TimestampISO 8601 in UTC, such as 2026-11-18T11:48:06.849Z.
Byte rangeoffset and length: the bytes from offset up to, and not including, offset + length.

A model is named in a path or a body by its account address or by its name: 1 to 32 characters of lowercase letters and digits in groups joined by single hyphens, such as sketch-32.

A field the API does not define is refused: a body or a query with an unknown key answers VALIDATION_ERROR.

Money#

A price, an escrow or an earning is a Money object.

FieldMeaning
amountamountrequired

Base units of the mint.

mintaddress or nullrequired

The SPL Token mint. null is SOL.

decimalsinteger, 0 to 255required

The mint's decimals. 9 for SOL.

symbolstringrequired

The mint's symbol. SOL for SOL.

Pagination#

List routes take two query parameters.

FieldMeaning
cursorstring of digits, at most 12

Where the page starts. Pass the nextCursor of the page before. Omitted, the list starts at its first item.

limitinteger, 1 to 100

Items per page. 24 when omitted.

A page has this shape:

FieldMeaning
itemsarrayrequired

The items of this page.

page.nextCursorstring or nullrequired

The cursor of the next page. null on the last page.

page.hasMorebooleanrequired

Whether a next page exists.

asOftimestamprequired

When the API assembled the response.

The error envelope#

Every failed response has one shape, with the HTTP status of its code:

JSON
{
  "error": {
    "code": "MODEL_NOT_FOUND",
    "message": "This model was not found.",
    "retryable": false,
    "stage": "read"
  }
}
FieldMeaning
codestringrequired

One of the codes in Errors. Branch on this.

messagestringrequired

A sentence that can be shown to a person.

retryablebooleanrequired

Whether the same request can succeed when sent again.

stagestringrequired

Where the request failed. One of the stages below.

fieldErrorsobject of string arrays

With VALIDATION_ERROR: the messages for each field, keyed by the field's path joined with dots, such as price.amount. A message about the whole value is under form.

programErrorobject

With an error raised by a program: programId (address of the program that raised it), name (the error's name, ProgramError when the program gave none) and number (its number, when it has one). The names and numbers of the voynich program are in Program errors.

fundingobject

With INSUFFICIENT_FUNDS: mint (the mint's address, null for SOL), required (the amount the transaction needs), available (the amount the wallet holds) and shortfall (required less available), each an amount in base units of the mint, lamports for SOL. What required counts for each build is in Errors from a build.

retryAfterSecondsinteger

With RATE_LIMITED: seconds until the next request is taken. The same number is in the Retry-After header.

requestIdstring

The request's id, on INTERNAL_ERROR. The X-Request-Id header carries it on every response.

StageThe request failed
validationin its path, query, headers or body
authin authorization
readwhile reading state
uploadwhile an encrypted input was handed to an enclave
buildwhile a transaction was built
walletin the copy the wallet signed
co_signin a signature the API adds
simulationin simulation of the transaction
sendwhile the transaction was sent
confirmationwhile the transaction was followed on the cluster

Errors#

CodeStatusMeaning
VALIDATION_ERROR400The request's path, query or body does not match the route's schema. fieldErrors names each field.
UNAUTHORIZED401The request is not allowed for this caller.
ORIGIN_NOT_ALLOWED403The browser origin is not on the API's allow list.
NOT_FOUND404No route at this path, or no transaction build has this id.
PROGRAM_UNAVAILABLE409The API cannot reach the program on its cluster yet.
CONFIGURATION_REQUIRED409A value the route needs is not configured on this deployment.
IDEMPOTENCY_CONFLICT409The build was already submitted with another idempotency key.
TRANSACTION_EXPIRED409The transaction's blockhash expired before it landed. Build again.
PAYLOAD_TOO_LARGE413The request body is larger than the route accepts.
UNSUPPORTED_MEDIA_TYPE415The request body is not application/json.
SIMULATION_FAILED422The transaction failed in simulation.
CHAIN_REFUSED422The cluster refused the transaction.
RATE_LIMITED429Too many requests. retryAfterSeconds says when to try again.
INTERNAL_ERROR500The API failed.
UPSTREAM_UNAVAILABLE502The RPC or the enclave behind the API did not answer.
MODEL_NOT_FOUND404No model has this name or address.
MODEL_NOT_LIVE409The model is not live, so it takes no new call.
MODEL_NOT_UPLOADING409The model is already sealed, so it takes no write and no second seal.
ENCLAVE_NOT_FOUND404No enclave has this address or signing key.
ENCLAVE_EXPIRED409The enclave's attestation record has expired.
MEASUREMENT_NOT_ALLOWED422The enclave's measurement is not in the model's allowed measurements.
GRANT_REQUIRED409The enclave holds no live grant for the model.
CALL_NOT_FOUND404No call has this address.
CALL_NOT_OPEN409The call already settled or was refunded.
CALL_NOT_REFUNDABLE409The call's deadline has not passed.
CALL_DEADLINE_PASSED409The call's deadline has passed, so it takes no input.
RECEIPT_NOT_FOUND404No receipt matches this receipt address, call address or transaction signature.
INPUT_HASH_MISMATCH422The envelope sent does not hash to the call's input hash.
INVALID_ENVELOPE422The envelope is not a version 1 envelope.
UPLOAD_INCOMPLETE409Not every ciphertext byte is written yet.
CIPHERTEXT_HASH_MISMATCH422The hash sent is not the SHA-256 of the bytes written.
PROGRAM_REFUSED422The Voynich program refused the transaction. programError names the program error.
INSUFFICIENT_FUNDS422The wallet holds less than the transaction needs. funding gives the mint and the required, available and shortfall amounts.

On every route#

CodeWhen
VALIDATION_ERRORA path parameter, a query parameter or the body does not match the route.
ORIGIN_NOT_ALLOWEDThe request's Origin header is not on the allow list.
PAYLOAD_TOO_LARGEThe body is larger than 1,048,576 bytes.
NOT_FOUNDThe path is not a route. The two transaction routes also answer it for a Build id they do not hold.
INTERNAL_ERRORThe API failed. The envelope carries requestId.

A route that returns a Money in a mint answers UPSTREAM_UNAVAILABLE, retryable, while the API has no decimals and symbol for that mint.

On every POST route#

CodeWhen
UNSUPPORTED_MEDIA_TYPEThe Content-Type does not start with application/json.
VALIDATION_ERRORThe body is not JSON.
PROGRAM_UNAVAILABLEGET /health reports waiting. Retryable. Every POST route under /v1 answers it except POST /v1/models/quote.

The pages for each group of routes list the codes each route adds to these.

Routes#

RouteOperationDoes
GET /healthhealthService readiness
GET /v1/configconfigBrowser and protocol configuration
GET /v1/statsstatsLive counts and operator earnings by mint
GET /v1/homehomeSketch-32, its ciphertext excerpt, receipts and counts
GET /v1/modelsmodelsBrowse models
GET /v1/models/{id}modelModel facts and resumable upload progress
GET /v1/models/{id}/weightsweightsRaw ciphertext range encoded as base64 and its account locations
GET /v1/models/{id}/enclavesmodelEnclavesEnclaves granted this model, including expired records
GET /v1/models/{id}/receiptsmodelReceiptsRecent model receipts
POST /v1/models/buildcreateModelBuild create_model and upload-key funding in one transaction
POST /v1/models/quotequoteModelEstimate sealing costs and check create_model size before allocation
POST /v1/models/{id}/write/buildwriteWeightsBuild a ciphertext write signed by the upload key
POST /v1/models/{id}/seal/buildsealModelBuild seal_model, fix the hash and close the upload key
POST /v1/models/{id}/price/buildsetPriceBuild set_price and operator share
POST /v1/models/{id}/grant/buildgrantByOwnerBuild grant_by_owner with a browser-wrapped model key
POST /v1/models/{id}/revoke/buildrevokeGrantBuild revoke_grant as the model owner
POST /v1/models/{id}/retire/buildretireModelBuild retire_model
GET /v1/enclavesenclavesBrowse live and expired enclaves
GET /v1/enclaves/{key}enclaveAttestation, grants, receipts and earnings
GET /v1/receipts/{id}receiptResolve a receipt address, call address or settle transaction signature
GET /v1/accounts/{wallet}accountOwned models, operated enclaves, earnings and calls
POST /v1/calls/buildopenCallBuild open_call escrowing the price with an encrypted input hash
GET /v1/calls/{id}callRead a call and its refund state
POST /v1/calls/{id}/inputrelayInputRelay the encrypted input to the selected enclave
GET /v1/calls/{id}/answeranswerPoll an encrypted signed answer and settlement identifiers
POST /v1/calls/{id}/refund/buildrefundCallBuild refund_call returning the whole escrow after its deadline
POST /v1/transactions/submitsubmitTransactionSubmit signed bytes or follow a wallet-sent signature
GET /v1/transactions/{id}transactionFollow the transaction ledger
GET /v1/eventseventsProgram events
GET /v1/calls/{id}/eventscallEventsEvents for a call
RoutesPage
/health, /openapi.json, /v1/config, /rpc, /v1/events, /v1/calls/{id}/eventsThis page
/v1/models...Models
/v1/enclaves...Enclaves
/v1/calls/build, /v1/calls/{id}, /v1/calls/{id}/answer, /v1/calls/{id}/refund/build, /v1/receipts/{id}Calls and receipts
/v1/accounts/{wallet}, /v1/stats, /v1/homeAccounts and stats
/v1/transactions...Transactions
/v1/calls/{id}/inputRelay

GET /health#

Whether the API reaches the program on its cluster.

FieldMeaning
statusstringrequired

ready: the voynich program, the attestation program and both Config accounts exist on the API's cluster. waiting: one of them does not; reads answer and every POST route under /v1 except POST /v1/models/quote answers PROGRAM_UNAVAILABLE. fixture: the API answers from built-in sample data.

contractVersionstringrequired

The version of the API's contract, a semantic version string.

GET /v1/config#

What a client needs before it reads the chain or opens a call: the cluster, the RPC address, the program ids and the protocol's Config values. The Config account is described in Program accounts.

FieldMeaning
modestringrequired

chain: the API reads and writes a Solana cluster. fixture: the API answers from built-in sample data.

clusterstringrequired

localnet, devnet or mainnet-beta.

rpcUrlURLrequired

A Solana JSON-RPC address for this cluster. In chain mode it is the API's own /rpc.

programIdaddress or nullrequired

The voynich program.

attestationProgramIdaddress or nullrequired

The program that owns attestation records.

attestationRecordLayoutVersioninteger or nullrequired

The record layout the Config names. See Enclaves and attestation.

feeRecipientaddress or nullrequired

The wallet that receives the protocol share.

protocolShareBpsinteger, 0 to 10000, or nullrequired

The protocol share of a settled call, in basis points. See Fees and the token.

callDeadlineSlotsslot count or nullrequired

The slots a call stays open before it can be refunded.

tokenMintaddress or nullrequired

The mint of VOYNICH.

fixturebooleanrequired

true when mode is fixture.

The four values read from the Config account (attestationRecordLayoutVersion, feeRecipient, protocolShareBps, callDeadlineSlots) are null when the API holds no Config.

POST /rpc#

A Solana JSON-RPC relay, the address rpcUrl names. A web3.js Connection pointed at it reads and sends through the API.

It takes one JSON-RPC 2.0 request per POST: jsonrpc is "2.0", id is a string or an integer, method is one of the methods below, params is an array. The body is at most 65,536 bytes. A successful call returns the cluster's JSON-RPC response unchanged.

Text
getAccountInfo            getMultipleAccounts     getBalance
getTokenAccountBalance    getSlot                 getBlockHeight
getLatestBlockhash        isBlockhashValid        getFeeForMessage
getMinimumBalanceForRentExemption                 getSignatureStatuses
getTransaction            getSignaturesForAddress getGenesisHash
getVersion                simulateTransaction     sendTransaction

Each client address has 600 calls a minute, and 30 a minute for sendTransaction.

This route answers in JSON-RPC's own error shape, { "jsonrpc": "2.0", "id": ..., "error": { "code", "message" } }, not in the error envelope:

JSON-RPC codeHTTP statusWhen
-32700400The body is not JSON.
-32600400The body is not one JSON-RPC 2.0 request with an id, a method and array params. A batch is refused.
-32600413The body is larger than 65,536 bytes.
-32601400The method is not in the list.
-32005429The client's minute is used up, or the API is at its own RPC budget. Retry-After says when to send again.
-32004200GET /health reports waiting.
-32603502The cluster's RPC did not answer.

GET /openapi.json#

The OpenAPI 3.1 document of the API, generated from the schemas the API validates with. It lists every route under /health and /v1 with its parameters, its request body and its response as JSON Schema.

Event streams#

Two routes answer as Server-Sent Events (text/event-stream).

RouteSends
GET /v1/eventsEvery event.
GET /v1/calls/{id}/eventscall.updated for the call at address {id} and receipt.created for its receipt.

GET /v1/calls/{id}/events reads the call's answer before the stream opens. It answers VALIDATION_ERROR when {id} is not an address, and otherwise the errors of GET /v1/calls/{id}/answer, CALL_NOT_FOUND among them.

Each message has the SSE fields event (the event's name), id and data. data is one JSON object, the event envelope:

FieldMeaning
typestringrequired

The event's name, the same as the SSE event field.

idstringrequired

The event's id.

timestamptimestamprequired

When the API published it.

dataobjectrequired

The object the event is about, whole, as its read route returns it.

EventdataSent when
readyOn /v1/events: { status }, the status of GET /health. On a call's stream: the call's CallAnswer, as GET /v1/calls/{id}/answer returns it when the stream opens.First on every connection.
resync{ reason }: reconnected or behind.See below.
model.updatedModelA model was created, written to, sealed, priced or retired, a grant for it changed, or one of its calls settled.
enclave.updatedEnclaveAn enclave registered or refreshed, a grant to it changed, it settled a call, or its reachable changed.
call.updatedCallA call opened, settled or was refunded.
receipt.createdReceiptA call settled.
transaction.updatedTxStatusPOST /v1/transactions/submit took a submission.

A comment line, : keepalive, is sent every 15 seconds on a quiet stream.

On resync#

The stream holds no history. A resync says events were sent that this connection did not receive:

  • reconnected is sent first on a connection that carries a Last-Event-ID header, which an EventSource sends when it reconnects.
  • behind is sent when 500 events were waiting for this connection. They are dropped and replaced by the resync.

After a resync, fetch again the snapshots the client shows (the model, the call, the answer, the transaction) from their read routes, then continue with the events that follow. Polling GET /v1/calls/{id}/answer reaches the same answer without a stream.