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
walletaddress 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
Originheader is answered only when that origin is on the API's allow list.
Every response carries these headers:
| Header | Value |
|---|---|
X-Request-Id | An id for this request. |
X-Contract-Version | The version of the API's contract, the same value as contractVersion in GET /health. |
Cache-Control | no-store |
Conventions#
| Kind | Written as |
|---|---|
| Amount | A decimal string of base units, such as "100000". It fits an unsigned 64-bit integer. |
| Slot | A decimal string, such as "1000". |
| Address | Base58 of 32 bytes. |
| Transaction signature | Base58 of 64 bytes. |
| Hash | SHA-256 as 64 lowercase hex characters. |
| Measurement | 96 lowercase hex characters (48 bytes). |
| Encryption key | Padded base64 of 32 bytes. |
| Receipt signature | Padded base64 of 64 bytes. |
| Envelope | Padded base64 of at least 73 bytes whose first byte is 1. |
| Wrapped key | An envelope of exactly 105 bytes. |
| Ciphertext bytes, transactions | Padded base64. |
| Byte count, share in basis points, layout version | A JSON number. |
| Timestamp | ISO 8601 in UTC, such as 2026-11-18T11:48:06.849Z. |
| Byte range | offset 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.
amountamountrequiredBase units of the mint.
mintaddress or nullrequiredThe SPL Token mint. null is SOL.
decimalsinteger, 0 to 255requiredThe mint's decimals. 9 for SOL.
symbolstringrequiredThe mint's symbol. SOL for SOL.
Pagination#
List routes take two query parameters.
cursorstring of digits, at most 12Where the page starts. Pass the nextCursor of the page before. Omitted, the list starts at its first item.
limitinteger, 1 to 100Items per page. 24 when omitted.
A page has this shape:
itemsarrayrequiredThe items of this page.
page.nextCursorstring or nullrequiredThe cursor of the next page. null on the last page.
page.hasMorebooleanrequiredWhether a next page exists.
asOftimestamprequiredWhen the API assembled the response.
The error envelope#
Every failed response has one shape, with the HTTP status of its code:
{
"error": {
"code": "MODEL_NOT_FOUND",
"message": "This model was not found.",
"retryable": false,
"stage": "read"
}
}codestringrequiredOne of the codes in Errors. Branch on this.
messagestringrequiredA sentence that can be shown to a person.
retryablebooleanrequiredWhether the same request can succeed when sent again.
stagestringrequiredWhere the request failed. One of the stages below.
fieldErrorsobject of string arraysWith 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.
programErrorobjectWith 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.
fundingobjectWith 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.
retryAfterSecondsintegerWith RATE_LIMITED: seconds until the next request is taken. The same number is in the Retry-After header.
requestIdstringThe request's id, on INTERNAL_ERROR. The X-Request-Id header carries it on every response.
| Stage | The request failed |
|---|---|
validation | in its path, query, headers or body |
auth | in authorization |
read | while reading state |
upload | while an encrypted input was handed to an enclave |
build | while a transaction was built |
wallet | in the copy the wallet signed |
co_sign | in a signature the API adds |
simulation | in simulation of the transaction |
send | while the transaction was sent |
confirmation | while the transaction was followed on the cluster |
Errors#
| Code | Status | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | The request's path, query or body does not match the route's schema. fieldErrors names each field. |
UNAUTHORIZED | 401 | The request is not allowed for this caller. |
ORIGIN_NOT_ALLOWED | 403 | The browser origin is not on the API's allow list. |
NOT_FOUND | 404 | No route at this path, or no transaction build has this id. |
PROGRAM_UNAVAILABLE | 409 | The API cannot reach the program on its cluster yet. |
CONFIGURATION_REQUIRED | 409 | A value the route needs is not configured on this deployment. |
IDEMPOTENCY_CONFLICT | 409 | The build was already submitted with another idempotency key. |
TRANSACTION_EXPIRED | 409 | The transaction's blockhash expired before it landed. Build again. |
PAYLOAD_TOO_LARGE | 413 | The request body is larger than the route accepts. |
UNSUPPORTED_MEDIA_TYPE | 415 | The request body is not application/json. |
SIMULATION_FAILED | 422 | The transaction failed in simulation. |
CHAIN_REFUSED | 422 | The cluster refused the transaction. |
RATE_LIMITED | 429 | Too many requests. retryAfterSeconds says when to try again. |
INTERNAL_ERROR | 500 | The API failed. |
UPSTREAM_UNAVAILABLE | 502 | The RPC or the enclave behind the API did not answer. |
MODEL_NOT_FOUND | 404 | No model has this name or address. |
MODEL_NOT_LIVE | 409 | The model is not live, so it takes no new call. |
MODEL_NOT_UPLOADING | 409 | The model is already sealed, so it takes no write and no second seal. |
ENCLAVE_NOT_FOUND | 404 | No enclave has this address or signing key. |
ENCLAVE_EXPIRED | 409 | The enclave's attestation record has expired. |
MEASUREMENT_NOT_ALLOWED | 422 | The enclave's measurement is not in the model's allowed measurements. |
GRANT_REQUIRED | 409 | The enclave holds no live grant for the model. |
CALL_NOT_FOUND | 404 | No call has this address. |
CALL_NOT_OPEN | 409 | The call already settled or was refunded. |
CALL_NOT_REFUNDABLE | 409 | The call's deadline has not passed. |
CALL_DEADLINE_PASSED | 409 | The call's deadline has passed, so it takes no input. |
RECEIPT_NOT_FOUND | 404 | No receipt matches this receipt address, call address or transaction signature. |
INPUT_HASH_MISMATCH | 422 | The envelope sent does not hash to the call's input hash. |
INVALID_ENVELOPE | 422 | The envelope is not a version 1 envelope. |
UPLOAD_INCOMPLETE | 409 | Not every ciphertext byte is written yet. |
CIPHERTEXT_HASH_MISMATCH | 422 | The hash sent is not the SHA-256 of the bytes written. |
PROGRAM_REFUSED | 422 | The Voynich program refused the transaction. programError names the program error. |
INSUFFICIENT_FUNDS | 422 | The wallet holds less than the transaction needs. funding gives the mint and the required, available and shortfall amounts. |
On every route#
| Code | When |
|---|---|
VALIDATION_ERROR | A path parameter, a query parameter or the body does not match the route. |
ORIGIN_NOT_ALLOWED | The request's Origin header is not on the allow list. |
PAYLOAD_TOO_LARGE | The body is larger than 1,048,576 bytes. |
NOT_FOUND | The path is not a route. The two transaction routes also answer it for a Build id they do not hold. |
INTERNAL_ERROR | The 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#
| Code | When |
|---|---|
UNSUPPORTED_MEDIA_TYPE | The Content-Type does not start with application/json. |
VALIDATION_ERROR | The body is not JSON. |
PROGRAM_UNAVAILABLE | GET /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#
| Route | Operation | Does |
|---|---|---|
GET /health | health | Service readiness |
GET /v1/config | config | Browser and protocol configuration |
GET /v1/stats | stats | Live counts and operator earnings by mint |
GET /v1/home | home | Sketch-32, its ciphertext excerpt, receipts and counts |
GET /v1/models | models | Browse models |
GET /v1/models/{id} | model | Model facts and resumable upload progress |
GET /v1/models/{id}/weights | weights | Raw ciphertext range encoded as base64 and its account locations |
GET /v1/models/{id}/enclaves | modelEnclaves | Enclaves granted this model, including expired records |
GET /v1/models/{id}/receipts | modelReceipts | Recent model receipts |
POST /v1/models/build | createModel | Build create_model and upload-key funding in one transaction |
POST /v1/models/quote | quoteModel | Estimate sealing costs and check create_model size before allocation |
POST /v1/models/{id}/write/build | writeWeights | Build a ciphertext write signed by the upload key |
POST /v1/models/{id}/seal/build | sealModel | Build seal_model, fix the hash and close the upload key |
POST /v1/models/{id}/price/build | setPrice | Build set_price and operator share |
POST /v1/models/{id}/grant/build | grantByOwner | Build grant_by_owner with a browser-wrapped model key |
POST /v1/models/{id}/revoke/build | revokeGrant | Build revoke_grant as the model owner |
POST /v1/models/{id}/retire/build | retireModel | Build retire_model |
GET /v1/enclaves | enclaves | Browse live and expired enclaves |
GET /v1/enclaves/{key} | enclave | Attestation, grants, receipts and earnings |
GET /v1/receipts/{id} | receipt | Resolve a receipt address, call address or settle transaction signature |
GET /v1/accounts/{wallet} | account | Owned models, operated enclaves, earnings and calls |
POST /v1/calls/build | openCall | Build open_call escrowing the price with an encrypted input hash |
GET /v1/calls/{id} | call | Read a call and its refund state |
POST /v1/calls/{id}/input | relayInput | Relay the encrypted input to the selected enclave |
GET /v1/calls/{id}/answer | answer | Poll an encrypted signed answer and settlement identifiers |
POST /v1/calls/{id}/refund/build | refundCall | Build refund_call returning the whole escrow after its deadline |
POST /v1/transactions/submit | submitTransaction | Submit signed bytes or follow a wallet-sent signature |
GET /v1/transactions/{id} | transaction | Follow the transaction ledger |
GET /v1/events | events | Program events |
GET /v1/calls/{id}/events | callEvents | Events for a call |
| Routes | Page |
|---|---|
/health, /openapi.json, /v1/config, /rpc, /v1/events, /v1/calls/{id}/events | This 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/home | Accounts and stats |
/v1/transactions... | Transactions |
/v1/calls/{id}/input | Relay |
GET /health#
Whether the API reaches the program on its cluster.
statusstringrequiredready: 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.
contractVersionstringrequiredThe 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.
modestringrequiredchain: the API reads and writes a Solana cluster. fixture: the API answers from built-in sample data.
clusterstringrequiredlocalnet, devnet or mainnet-beta.
rpcUrlURLrequiredA Solana JSON-RPC address for this cluster. In chain mode it is the API's own /rpc.
programIdaddress or nullrequiredThe voynich program.
attestationProgramIdaddress or nullrequiredThe program that owns attestation records.
attestationRecordLayoutVersioninteger or nullrequiredThe record layout the Config names. See Enclaves and attestation.
feeRecipientaddress or nullrequiredThe wallet that receives the protocol share.
protocolShareBpsinteger, 0 to 10000, or nullrequiredThe protocol share of a settled call, in basis points. See Fees and the token.
callDeadlineSlotsslot count or nullrequiredThe slots a call stays open before it can be refunded.
tokenMintaddress or nullrequiredThe mint of VOYNICH.
fixturebooleanrequiredtrue 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.
getAccountInfo getMultipleAccounts getBalance
getTokenAccountBalance getSlot getBlockHeight
getLatestBlockhash isBlockhashValid getFeeForMessage
getMinimumBalanceForRentExemption getSignatureStatuses
getTransaction getSignaturesForAddress getGenesisHash
getVersion simulateTransaction sendTransactionEach 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 code | HTTP status | When |
|---|---|---|
-32700 | 400 | The body is not JSON. |
-32600 | 400 | The body is not one JSON-RPC 2.0 request with an id, a method and array params. A batch is refused. |
-32600 | 413 | The body is larger than 65,536 bytes. |
-32601 | 400 | The method is not in the list. |
-32005 | 429 | The client's minute is used up, or the API is at its own RPC budget. Retry-After says when to send again. |
-32004 | 200 | GET /health reports waiting. |
-32603 | 502 | The 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).
| Route | Sends |
|---|---|
GET /v1/events | Every event. |
GET /v1/calls/{id}/events | call.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:
typestringrequiredThe event's name, the same as the SSE event field.
idstringrequiredThe event's id.
timestamptimestamprequiredWhen the API published it.
dataobjectrequiredThe object the event is about, whole, as its read route returns it.
| Event | data | Sent when |
|---|---|---|
ready | On /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.updated | Model | A model was created, written to, sealed, priced or retired, a grant for it changed, or one of its calls settled. |
enclave.updated | Enclave | An enclave registered or refreshed, a grant to it changed, it settled a call, or its reachable changed. |
call.updated | Call | A call opened, settled or was refunded. |
receipt.created | Receipt | A call settled. |
transaction.updated | TxStatus | POST /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:
reconnectedis sent first on a connection that carries aLast-Event-IDheader, which anEventSourcesends when it reconnects.behindis sent when 500 events were waiting for this connection. They are dropped and replaced by theresync.
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.