Reference
API
Every route of Pook's HTTP API: what to send, what comes back, and what each can answer when it fails. The SDK calls these routes for you, so this page is for calling them directly.
Conventions
The base URL is https://api.pook.codes. Every route below is a path under it.
Requests and responses are JSON. A POST carries Content-Type: application/json, and its body is at most 1 MiB. Request objects are strict: a key the route does not define fails validation. Responses can gain fields and enum values over time, so read the keys you know and pass over the rest.
Every response carries X-Request-Id and X-Contract-Version, and Cache-Control: no-store unless the route sets its own.
A browser calls the API from an origin the API accepts. Requests with no Origin header, such as a server's, are not checked.
Value formats
| Format | Type | Meaning |
|---|---|---|
Address | string | A base58 public key of 32 bytes, 32 to 44 characters. |
Signature | string | A base58 transaction signature of 64 bytes, 64 to 88 characters. |
BaseUnits | string | An unsigned integer as a decimal string, in the smallest unit of its asset. No sign, no leading zero, no decimal point. |
U64 | string | BaseUnits that fit an unsigned 64-bit integer. Slots, block heights and Unix times use it too. |
PositiveU64 | string | A U64 greater than zero. |
Base64 | string | Standard base64 with padding. |
Hex | string | Hex bytes, an even number of characters, either case. |
Timestamp | string | ISO 8601 date and time in UTC, ending in Z. |
HookId | string | A hook id such as jupiter.swap: 2 to 48 characters of a-z, 0-9, dot, underscore and hyphen, starting and ending with a letter or digit. |
Amounts are strings because they pass the range a JSON number holds exactly. Do arithmetic on them as big integers.
Pagination
List routes take the same two query parameters and answer the same page object.
| Parameter | Type | Meaning |
|---|---|---|
cursoroptional | string | The nextCursor of the page before. Digits only, up to 12. Leave it out for the first page. |
limitoptional | integer | Items per page, 1 to 100. Default 24. |
| Field | Type | Meaning |
|---|---|---|
items | array | The items of this page. |
page.nextCursor | string | null | The cursor of the next page, or null on the last one. |
page.hasMore | boolean | Whether a next page exists. |
asOf | Timestamp | When the API read the data. |
Treat the cursor as opaque: send back what you were given.
Readiness
Several responses carry status. It is ready when the API reads the Pook program on its cluster and waiting until then. While it is waiting, GET /health, GET /v1/config and GET /v1/stats still answer, the list routes answer empty pages, and routes that need the program answer 409 PROGRAM_UNAVAILABLE.
Errors
A failed request answers with its HTTP status and one envelope:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Check the highlighted fields.",
"retryable": false,
"stage": "validation",
"fieldErrors": { "amountIn": ["Must be greater than zero."] }
}
}| Field | Type | Meaning |
|---|---|---|
code | string | The stable code to branch on. The table below lists every one. |
message | string | One sentence a person can read. |
retryable | boolean | Whether sending the same request again can succeed. |
stage | string | The step that failed. |
fieldErrorsoptional | Record<string, string[]> | Messages per field, keyed by the dotted path of the field. Sent with VALIDATION_ERROR. |
programErroroptional | { programId: Address, name: string, number?: integer } | The program that refused a transaction, its error name and its error number. |
retryAfterSecondsoptional | integer | Seconds to wait before retrying. The Retry-After header carries the same value. |
requestIdoptional | string | The id of the request, the same as the X-Request-Id header. |
The stages are: validation, auth, read, upload, build, wallet, wallet_rejected, co_sign, simulation, proving, relay, send, confirmation, expired.
The error codes and the HTTP status each one arrives with:
| Code | Type | Meaning |
|---|---|---|
VALIDATION_ERROR | HTTP 400 | The body, the query or a path value failed its schema. fieldErrors names each field. Also answered when a signed transaction differs from the one that was built. |
UNAUTHORIZED | HTTP 401 | A wallet signer is required and none is connected. The SDK raises it before any request. |
ORIGIN_NOT_ALLOWED | HTTP 403 | The Origin header of a browser request is not one the API accepts. |
NOT_FOUND | HTTP 404 | The route, the hook, the build, the transaction, the relayed submission, the circuit file or the on-chain IDL account does not exist. The SDK raises it for a Rings recipient wallet that has no record in the Rings user registry. |
PROGRAM_UNAVAILABLE | HTTP 409 | The API is waiting for the Pook program on its cluster. |
CONFIGURATION_REQUIRED | HTTP 409 | The service is missing a value it needs to act, such as a relayer started without its signing key. |
IDEMPOTENCY_CONFLICT | HTTP 409 | The request was already submitted with different parameters. |
TRANSACTION_EXPIRED | HTTP 409 | The expiry of a relayed submission has passed: prove and submit again. In a status body, the transaction's blockhash passed before it landed: build it again. |
PAYLOAD_TOO_LARGE | HTTP 413 | The request body is over 1 MiB. |
UNSUPPORTED_MEDIA_TYPE | HTTP 415 | A POST body was sent without Content-Type: application/json. |
SIMULATION_FAILED | HTTP 422 | The transaction failed in simulation. Nothing was sent. programError names the program and its error when a program refused it. |
CHAIN_REFUSED | HTTP 422 | A program refused the transaction on chain. programError names the program and its error. |
RATE_LIMITED | HTTP 429 | Too many requests. retryAfterSeconds and the Retry-After header say when to try again. |
INTERNAL_ERROR | HTTP 500 | The request could not be completed. requestId identifies it. |
UPSTREAM_UNAVAILABLE | HTTP 502 | The cluster RPC, the relayer, the prover, the Rings indexer or Jupiter could not be reached. |
NO_ROUTE | HTTP 422 | No route exists for this asset pair and amount. |
QUOTE_EXPIRED | HTTP 409 | The quote is past its expiresAt. Quote again. |
INSUFFICIENT_BALANCE | HTTP 422 | The private balance does not cover the amount. The SDK raises it when at most two notes cannot cover the amount in. |
PROOF_FAILED | HTTP 422 | A proof could not be generated or did not verify. |
PROOF_EXPIRED | HTTP 409 | The proof passed its expiry before the run landed. No note was spent. Prove again. |
RELAY_REFUSED | HTTP 422 | The relayer declined the submission: its fee is below the relayer's minimum, an instruction is outside what it relays, or an account other than the relayer is marked as signer. |
WALLET_REJECTED | HTTP 400 | The wallet declined to sign. The SDK raises it. |
IDL_INVALID | HTTP 400 | The IDL could not be parsed, or it holds no instructions. |
HOOK_ALREADY_EXISTS | HTTP 409 | A hook with this id is already published. |
SEAT_NOT_EMPTY | HTTP 409 | The seat still holds collateral or debt. Repay and withdraw before closing it. |
SCAN_FAILED | HTTP 502 | The note scan could not read the indexer. Retry. |
Any route can answer VALIDATION_ERROR, ORIGIN_NOT_ALLOWED, NOT_FOUND, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, INTERNAL_ERROR and UPSTREAM_UNAVAILABLE. Each route below lists what it adds.
When a program refuses a transaction, programError.name is the program's own error name, such as SlippageExceeded. The program reference lists Pook's errors with their numbers.
A transaction that fails after it was accepted does not answer with the envelope. Its status body carries an error object of the same shape. There, code is SIMULATION_FAILED, CHAIN_REFUSED or TRANSACTION_EXPIRED, stage is simulation or confirmation, and programError carries programId, name and number when a program refused it.
Shared objects
PublicRun
One run as the chain shows it.
| Field | Type | Meaning |
|---|---|---|
signature | Signature | The transaction of the run. |
slot | U64 | The slot it landed in. |
hookId | string | The hook that ran. |
hookAddress | Address | The hook's account. |
protocol | string | The protocol the hook calls, such as jupiter. |
kind | 'flow' | 'seat' | The kind of hook. |
mintIn | Address | null | The asset in, or null when the run takes none. |
assetInSymbol | string | null | Its symbol. |
amountIn | BaseUnits | What entered the stage. |
mintOut | Address | null | The asset out, or null when the run returns none. |
assetOutSymbol | string | null | Its symbol. |
amountOut | BaseUnits | What the protocol returned to the stage. |
runFeeAmount | BaseUnits | The run fee taken from the result. |
relayerFeeAmount | BaseUnits | The relayer's fee taken from the result. |
stageAuthority | Address | The stage that signed the call. |
relayer | Address | The fee payer of the transaction. |
status | 'confirmed' | 'finalized' | The commitment the run has reached. |
timestamp | Timestamp | The block time. |
TxBuildResponse
An unsigned transaction for a wallet to sign. Enter, publishing and claiming all answer with it.
| Field | Type | Meaning |
|---|---|---|
buildId | string | The id to submit and follow the transaction with. |
action | 'enter' | 'publish_hook' | 'claim_author_fees' | What the transaction does. |
transactionBase64 | Base64 | The unsigned version 0 transaction. The wallet named in the request is its fee payer. |
blockhash | string | The recent blockhash it was built on. |
lastValidBlockHeight | U64 | The last block height at which that blockhash is valid. |
networkFeeLamports | BaseUnits | The network fee in lamports. |
expiresAt | Timestamp | When the build stops being accepted, 60 seconds after it was made. |
The API simulates the transaction before it answers. A build that fails simulation answers 422 SIMULATION_FAILED, with programError when a program names the reason.
TxStatusResponse
| Field | Type | Meaning |
|---|---|---|
id | string | The build id. |
actionoptional | string | The action of the build. |
status | string | Where the transaction stands. |
signature | Signature | null | The transaction signature once known. |
slot | U64 | null | The slot it landed in. |
erroroptional | object | Why it failed or expired, in the shape of the error envelope. |
updatedAt | Timestamp | When this status was read. |
The statuses are: built, submitted, unconfirmed, confirmed, finalized, failed, expired. A transaction the wallet broadcast itself reads unconfirmed once its blockhash has passed with no record of it on chain.
RelaySubmissionResponse
| Field | Type | Meaning |
|---|---|---|
relayId | string | The id to follow the submission with. |
kind | 'run' | 'leave' | 'open_seat' | 'close_seat' | What was relayed. |
status | string | Where the transaction stands. |
signature | Signature | null | The transaction signature. |
slot | U64 | null | The slot it landed in, once confirmed. |
hookIdoptional | string | null | The hook, for a run. |
seatAddressoptional | Address | null | The seat, where the submission names one. |
relayerFee | BaseUnits | The relayer's fee the proof fixes. Zero for opening and closing a seat. |
runoptional | PublicRun | null | The run as indexed, where the relayer has it. |
erroroptional | object | Why it failed or expired, in the shape of the error envelope. |
expiresAt | Timestamp | The expiry the proof fixes. |
updatedAt | Timestamp | When this status was read. |
The statuses are: accepted, submitted, confirmed, finalized, failed, expired.
Instruction and account shapes
An AccountMeta is { pubkey: Address, isWritable: boolean, isSigner: boolean }. An Instruction is an object with programId (Address), accounts (an array of those accounts) and dataBase64 (Base64).
Health, config and stats
GET /health
Answers 200 in every state.
| Field | Type | Meaning |
|---|---|---|
status | 'ready' | 'waiting' | See Readiness. |
programId | Address | null | The Pook program. |
cluster | 'localnet' | 'devnet' | 'mainnet' | The cluster the API reads. |
contractVersion | string | The version of the API contract, the same as X-Contract-Version. |
asOf | Timestamp | When the answer was made. |
GET /v1/config
The addresses and rates a client needs before it builds anything. Addresses lists the same accounts, and Fees and POOK explains the rates.
| Field | Type | Meaning |
|---|---|---|
status | 'ready' | 'waiting' | See Readiness. |
cluster | string | The cluster the API reads. |
programId | Address | null | The Pook program. |
authorityPda | Address | null | The program's authority account. |
stagePdaoptional | Address | null | The stage. |
configPdaoptional | Address | null | The program's config account. |
ringsProgramId | Address | The Solana Privacy Program. |
stateTree | Address | The state tree notes are written to. |
runFeeBps | integer | null | The run fee in basis points, read from the config account. |
authorShareBps | integer | null | The author's share of the run fee in basis points. |
feeRecipient | Address | null | The account that receives the protocol share. |
pookMint | Address | null | The mint of POOK. |
relayerUrl | string | The relayer behind /v1/relayer. |
proverUrl | string | The prover behind /v1/prover. |
photonRelayUrloptional | string | The path of the Rings indexer pass-through, /v1/photon. |
supportedAssets | AssetInfo[] | Each asset the API names: mint (Address), symbol, name, decimals (integer) and, for SOL, isNative (boolean). |
asOf | Timestamp | When the answer was made. |
GET /v1/stats
| Field | Type | Meaning |
|---|---|---|
status | 'ready' | 'waiting' | See Readiness. |
hooksCount | integer | Published hooks. |
runsCount | integer | Runs indexed. |
activeSeatsCount | integer | Seats that are open. |
volumeByAsset | AssetVolume[] | For each asset in: mint (Address), symbol, decimals (integer) and volume (BaseUnits), the sum of amountIn across runs. |
asOf | Timestamp | When the answer was made. |
GET /openapi.json
The OpenAPI 3.1 document generated from the same schemas the API validates with.
Hooks and quotes
GET /v1/hooks
One page of published hooks, most run first, then newest.
| Query | Type | Meaning |
|---|---|---|
protocoloptional | string | Only hooks of this protocol, 1 to 32 characters. Case is ignored. |
kindoptional | 'flow' | 'seat' | Only hooks of this kind. |
qoptional | string | Text to find in the id, the protocol name, the label or the description. Up to 64 characters. |
cursoroptional | string | See Pagination. |
limitoptional | integer | See Pagination. |
The response is status, items, page and asOf. Each item is a HookSummary:
| Field | Type | Meaning |
|---|---|---|
id | string | The hook id. |
address | Address | The hook's account. |
protocol | string | The protocol, as a short lowercase name. |
protocolName | string | The protocol, as shown to people. |
label | string | The name of the action. |
description | string | One or two sentences on what it does. |
kind | 'flow' | 'seat' | Whether the hook acts on a seat. |
targetProgram | Address | The protocol's program. |
instructionName | string | The instruction it calls. |
mintIn | Address | null | The asset in when the hook fixes one. |
mintOut | Address | null | The asset out when the hook fixes one. |
mintInConstraintoptional | MintConstraint | What the hook allows as the asset in: kind is 'None', 'Any', 'Sol' or 'Spl', and 'Spl' carries mint. |
mintOutConstraintoptional | MintConstraint | The same for the asset out. |
wrapSolInoptional | boolean | Whether SOL in is wrapped before the call. |
unwrapSolOutoptional | boolean | Whether wrapped SOL out is unwrapped after the call. |
assetInSymbol | string | null | The symbol of the asset in. |
assetOutSymbol | string | null | The symbol of the asset out. |
author | Address | The wallet that published the hook. |
authorShareBps | integer | null | The author's share of the run fee in basis points. |
immutable | boolean | Whether the hook is immutable. |
sdkCall | string | The SDK call that runs this hook, as text. |
stats | HookStats | runsCount (integer), volumeIn and volumeOut (BaseUnits), lastRunAt (Timestamp or null). |
publishedAt | Timestamp | When it was published. |
GET /v1/hooks/:id
One hook in full, with its ten most recent runs. :id is a HookId.
| Field | Type | Meaning |
|---|---|---|
hook | HookDetail | The hook. |
recentRuns | PublicRun[] | Up to ten runs, newest first. |
asOf | Timestamp | When the answer was made. |
A HookDetail is a HookSummary with these fields added. Hook schema specifies each of them and every slot kind.
| Field | Type | Meaning |
|---|---|---|
discriminator | Hex | The leading bytes that select the instruction. |
dataTemplate | { baseHex: Hex, slots: DataSlot[] } | The instruction data with its named slots. A slot has name, kind, offset, length, type and optional label and description. |
accountsTemplate | AccountSlot[] | The account list with names. A slot has index, name, role, writable, signer and optional address and description. |
companionInstructions | CompanionInstruction[] | Instructions that must travel with the run: programId, instructionName, discriminator, position ('before' or 'after') and optional description. |
dataTemplateHexoptional | Hex | The data template as the hook account stores it. |
dataSlotsoptional | OnChainDataSlot[] | The data slots as stored: offset, len and kind. |
accountSlotsoptional | OnChainAccountSlot[] | The account slots as stored: kind, isWritable, isSigner and pubkey. |
companionsoptional | OnChainCompanion[] | The companions as stored: programId, discriminatorHex, discLen and mustPrecede. |
formFields | HookFormField[] | The inputs a form shows for this hook: name, kind, label, required and optional defaultValue and placeholder. |
publishSignature | Signature | The transaction that published it. |
Answers 404 NOT_FOUND for an id that is not published, and 409 PROGRAM_UNAVAILABLE.
POST /v1/hooks/:id/quote
Prices one run of a hook and resolves everything the proof will fix: the accounts, the instruction data and the call hash. Call it before proving.
| Body | Type | Meaning |
|---|---|---|
amountIn | PositiveU64 | The amount in. For a hook that takes no asset in, the amount the action asks the protocol for. |
mintInoptional | Address | The asset in, where the hook leaves it open. |
mintOutoptional | Address | The asset out, where the hook leaves it open. |
minimumOutoptional | BaseUnits | The least the run may bring back. Required when the hook returns an asset and the API does not price the hook. The API prices jupiter.swap, jito.stake, jito.unstake and the Kamino hooks, and sets their minimum from slippageBps. |
slippageBpsoptional | integer | Allowed slippage in basis points, 0 to 5000. Default 50. |
seatAddressoptional | Address | The seat, for a seat hook. |
argsoptional | Record<string, string> | Values for the hook's caller slots. A key that matches an account slot's name sets that account's address. |
{
"mintIn": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"mintOut": "So11111111111111111111111111111111111111112",
"amountIn": "1000000",
"slippageBps": 50
}That body, sent to /v1/hooks/jupiter.swap/quote, quotes a swap from USDC to SOL.
| Field | Type | Meaning |
|---|---|---|
quoteId | string | The id of this quote. |
hookId | string | The hook quoted. |
hookAddressoptional | Address | The hook's account. |
hookAuthoroptional | Address | The hook's author. |
feeRecipientoptional | Address | null | The account that receives the protocol share. |
relayeroptional | Address | The relayer the accounts were resolved for. |
mintIn | Address | null | The asset in. |
assetInSymbol | string | null | Its symbol. |
amountIn | BaseUnits | What leaves your notes for the stage. Zero for a hook that takes no asset in. |
mintOut | Address | null | The asset out. |
assetOutSymbol | string | null | Its symbol. |
tokenProgramInoptional | Address | The token program of the asset in. |
tokenProgramOutoptional | Address | The token program of the asset out. |
expectedOut | BaseUnits | What the protocol is expected to return. |
minimumOut | BaseUnits | The least the run may bring back: expectedOut after slippage, or the minimumOut of the request. |
minimumOutFromCalleroptional | boolean | true when minimumOut is the one the request sent. expectedOut then equals it. |
slippageBps | integer | The slippage applied. |
fees | QuoteFees | See below. |
netOut | BaseUnits | expectedOut less the run fee and the relayer's fee. |
minimumNetOutoptional | BaseUnits | minimumOut less the run fee and the relayer's fee: the least that reaches the holder. The program checks minimumOut, before fees. |
resolvedAccounts | ResolvedAccount[] | Every account passed to the protocol, in order: index, name, address, writable, signer. |
resolvedDataBase64 | Base64 | The instruction data after the slots are filled. |
callHashHexoptional | Hex | The 32-byte call hash the proof binds. |
callerDataBase64optional | Base64 | The bytes that fill the hook's caller slots. |
callerAccountsoptional | AccountMeta[] | The accounts the caller supplies to the run instruction. |
callerRemainingWritableoptional | integer[] | A 0 or 1 writable flag for each trailing caller account. |
setupInstructionsoptional | Instruction[] | Instructions the relayer places before the run, such as creating a token account for the stage. |
companionInstructions | Instruction[] | The companion instructions the hook requires, built. |
chainPreview | { visible, hidden } | visible holds what the chain will show: hookId, targetProgram, assetIn, amountIn, assetOut, minimumOut, relayer. hidden is a list of what stays off chain, as labels. |
routeSummary | string | null | The route in words. |
expiresAt | Timestamp | When the quote stops holding, five minutes after it was made. |
QuoteFees. Every amount is in the asset feeAssetMint names.
| Field | Type | Meaning |
|---|---|---|
runFeeAmount | BaseUnits | The run fee. |
runFeeBps | integer | null | Its rate in basis points. |
authorShareAmount | BaseUnits | The author's share of the run fee. |
authorShareBps | integer | null | Its rate in basis points of the run fee. |
protocolShareAmount | BaseUnits | The protocol share of the run fee. |
relayerFeeAmount | BaseUnits | The relayer's fee. |
feeAssetMint | Address | null | The asset the fees are taken in. |
feeAssetSymbol | string | null | Its symbol. |
Answers 400 VALIDATION_ERROR with a message naming minimumOut when the hook needs it and the body leaves it out, 404 NOT_FOUND when the hook is not on chain, 422 NO_ROUTE when no route exists for the pair and amount, 502 UPSTREAM_UNAVAILABLE with stage build when Jupiter could not be reached, and 409 PROGRAM_UNAVAILABLE.
Runs feed
GET /v1/runs
One page of the public feed, newest first. The feed holds the 500 most recent runs that match.
| Query | Type | Meaning |
|---|---|---|
hookIdoptional | HookId | Only runs of this hook. |
protocoloptional | string | Only runs of this protocol, 1 to 32 characters. Case is ignored. |
cursoroptional | string | See Pagination. |
limitoptional | integer | See Pagination. |
The response is status, items, page and asOf. Each item is a PublicRun.
GET /v1/runs/stream
The same feed as Server-Sent Events. Add ?hookId= to receive the runs of one hook.
Each event has an event line with its type, an id line, and a data line holding one JSON object:
| Field | Type | Meaning |
|---|---|---|
type | string | The event type, the same as the event line. |
id | string | The event id, the same as the id line. |
timestamp | Timestamp | When the API sent it. |
data | object | The payload, by type. |
| Event | When | data |
|---|---|---|
ready | First, on every connection | status: ready or waiting |
run | A run was indexed | A PublicRun |
resync | The stream cannot give you what you missed | reason: reconnected or behind |
The stream replays nothing. A client that reconnects with Last-Event-ID gets resync with reconnected, and a client that falls 500 events behind gets resync with behind. On resync, fetch GET /v1/runs again and continue from the stream.
A comment line, : keepalive, arrives after every 15 seconds without an event.
event: ready
id: <event id>
data: {"type":"ready","id":"<event id>","timestamp":"<Timestamp>","data":{"status":"ready"}}Wallet balance
GET /v1/wallets/:wallet/balance
The public balance of a wallet in one asset, read from the cluster. :wallet is an Address.
| Query | Type | Meaning |
|---|---|---|
mintoptional | Address | The asset. Default wrapped SOL, which reads the SOL balance of the wallet. |
| Field | Type | Meaning |
|---|---|---|
wallet | Address | The wallet read. |
mint | Address | The asset. SOL is reported under the wrapped SOL mint. |
symbol | string | null | The symbol, for an asset the API names. |
decimals | integer | The decimals of the mint. |
amount | BaseUnits | The balance. For a token, the balance of the associated token account of the wallet. |
asOf | Timestamp | When it was read. |
Notes and seats
The API never receives a key that can read a note. A client finds its notes by scanning encrypted records and decrypting them itself, as Notes and the private balance describes. The SDK scans through POST /v1/photon/:method.
GET /v1/notes
One page of encrypted note records.
| Query | Type | Meaning |
|---|---|---|
ownerTagoptional | Address | Only records under this owner tag. |
afterSlotoptional | U64 | Only records after this slot. |
cursoroptional | string | See Pagination. |
limitoptional | integer | See Pagination. |
The response is items, page and asOf. Each item:
| Field | Type | Meaning |
|---|---|---|
commitment | string | The note commitment. |
treeId | integer | The state tree it is in. |
leafIndex | integer | Its leaf in that tree. |
slot | U64 | The slot it was written in. |
signature | Signature | The transaction that wrote it. |
ownerTag | Address | The tag a holder matches against its own one-time keys. |
ciphertextBase64 | Base64 | The encrypted note. |
txViewingPkBase64 | Base64 | The viewing public key of the transaction. |
saltBase64 | Base64 | The salt of the encryption. |
timestamp | Timestamp | The block time. |
POST /v1/notes/nullifiers
| Body | Type | Meaning |
|---|---|---|
nullifiers | string[] | 1 to 200 nullifiers, each 1 to 128 characters. |
| Field | Type | Meaning |
|---|---|---|
spent | Record<string, boolean> | One entry per nullifier sent. |
asOf | Timestamp | When the answer was made. |
POST /v1/seats/state
The public position of each seat you name. A seat's address is public on chain; which holder commands it is not, so the client sends the addresses it has decrypted. Seats explains the object.
| Body | Type | Meaning |
|---|---|---|
seatAddresses | Address[] | Up to 50 seat addresses. |
The response is seats and asOf. Each seat is a SeatPosition, in the order sent:
| Field | Type | Meaning |
|---|---|---|
seatAddress | Address | The seat. |
commitmentHexoptional | Hex | The commitment the seat was opened with. |
openerRelayeroptional | Address | null | The relayer that opened it. |
protocol | string | The protocol the position is in. |
protocolName | string | The protocol, as shown to people. |
obligationAddress | Address | null | The protocol's own account for the position. |
status | 'open' | 'empty' | 'closed' | open holds collateral or debt. empty holds neither. |
collateral | SeatAssetPosition[] | Deposits: mint, symbol, decimals, amount (BaseUnits) and usdValue (string or null). |
debt | SeatAssetPosition[] | Borrows, in the same shape. |
depositedValueUsdoptional | string | null | The value of the collateral in USD, as the protocol reports it. |
borrowFactorAdjustedDebtUsdoptional | string | null | The debt in USD after the borrow factor. |
unhealthyBorrowValueUsdoptional | string | null | The debt value at which the position can be liquidated. |
healthFactor | string | null | The health of the position, computed from the two values above. |
actions | string[] | The ids of the hooks that act on this seat. |
updatedAt | Timestamp | When it was read. |
Answers 409 PROGRAM_UNAVAILABLE.
Enter and wallet-signed transactions
Three actions are signed by a wallet: entering, publishing a hook and claiming author fees. Each has a build route that answers a TxBuildResponse. The wallet signs transactionBase64, and the two routes at the end of this section submit it and follow it.
POST /v1/enter/build
Builds the transaction that moves an asset into your private balance.
| Body | Type | Meaning |
|---|---|---|
source | 'wallet' | 'rings' | wallet enters from the public balance of the wallet. rings enters from a private balance you already hold on Solana Privacy Rings. |
wallet | Address | The wallet that signs and pays the network fee. |
mint | Address | The asset. The wrapped SOL mint enters SOL. |
amount | PositiveU64 | The amount to enter. |
outputOwnerHash | string | The one-time owner of the note that receives the amount: 32 bytes as hex when source is wallet. |
outputViewingPkBase64optional | Base64 | The viewing public key of the output note. |
transactDataBase64optional | Base64 | Required when source is rings: the Privacy Program transact data the client built. |
transactAccountsoptional | AccountMeta[] | Required when source is rings: the accounts of that transact, up to 64. |
{
"source": "wallet",
"wallet": "<your wallet address>",
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amount": "1000000",
"outputOwnerHash": "<32 bytes as hex>"
}Answers 409 PROGRAM_UNAVAILABLE, and 422 SIMULATION_FAILED when the build fails simulation.
POST /v1/tx/submit
Hands a signed transaction to the API, or tells it the wallet already sent one.
| Body | Type | Meaning |
|---|---|---|
buildId | string | The buildId of the build, 1 to 128 characters. |
signedTransactionBase64optional | Base64 | The signed transaction. The API checks it against the build and broadcasts it. |
signatureoptional | Signature | The signature of a transaction the wallet broadcast itself. The API follows it. |
Send one of signedTransactionBase64 and signature.
The response is a TxStatusResponse. Submitting the same build twice answers with the status of the first submission.
Answers 400 VALIDATION_ERROR with stage wallet when the signed transaction differs from the build, 422 SIMULATION_FAILED when it fails simulation, 404 NOT_FOUND with stage build for a buildId the API does not hold, and 409 PROGRAM_UNAVAILABLE.
GET /v1/tx/:id
The status of a submitted transaction. :id is the buildId or the transaction signature. Each read checks the cluster once, and rebroadcasts a transaction the API holds while its blockhash is valid.
The response is a TxStatusResponse. A transaction that failed or expired answers 200 with error in the body.
Answers 404 NOT_FOUND for an id the API does not hold, and 409 PROGRAM_UNAVAILABLE.
Prover
Proofs are generated in the client. These routes serve the circuit files it proves with. The API forwards every path under /v1/prover to the prover and returns its answer with its status. The circuits are run, leave, seat_open, seat_fund, seat_action and seat_close.
GET /v1/prover/circuits
| Field | Type | Meaning |
|---|---|---|
status | 'ready' | 'waiting' | ready when at least one circuit is available. |
circuits | ProverCircuitArtifact[] | One entry per circuit. |
circuits[].circuit | string | The circuit name. |
circuits[].xbcSha256 | Hex | null | SHA-256 of circuit.xbc. |
circuits[].pkSha256 | Hex | null | SHA-256 of pk.bin. |
circuits[].vkSha256 | Hex | null | SHA-256 of vk.bin. |
circuits[].available | boolean | Whether all three files are served. |
asOf | Timestamp | When the answer was made. |
GET /v1/prover/circuits/:circuit/:file
One file of one circuit. :file is circuit.xbc, pk.bin, vk.bin or metadata.json.
The body is the file: application/json for metadata.json, application/octet-stream for the rest. The x-artifact-sha256 header holds its SHA-256, to check against the list above, and cache-control allows caching for an hour.
Answers 404 NOT_FOUND with stage proving for a circuit or file it does not serve.
Relayer
The API forwards every path under /v1/relayer to Pook's relayer and returns its answer with its status. An app can also call a relayer directly: every relayer, Pook's or one run by someone else, serves the same routes at its own URL and accepts browser requests from the origins it is configured with. The SDK does this when it is given relayerUrl. See Run a relayer. Relayers explains the role.
The four submission routes answer 201 with a RelaySubmissionResponse. Before it signs, the relayer checks the submission and simulates the transaction. After it sends, it follows the transaction for up to 15 seconds, so the 201 carries confirmed, failed or expired when the cluster settled it in that time and submitted otherwise. A transaction that fails simulation is not sent: the 201 carries failed with error.
Every submission route can answer:
| Status | Code | When |
|---|---|---|
| 409 | TRANSACTION_EXPIRED | expiryUnixTs is not in the future |
| 409 | PROGRAM_UNAVAILABLE | The relayer has no Pook program to send to |
| 409 | CONFIGURATION_REQUIRED | The relayer has no signing key |
| 409 | CONFIGURATION_REQUIRED | The relayer has no fee set for the instruction's asset |
| 422 | RELAY_REFUSED | The instruction is not the one the route relays, the relayer's fee in it is below the quote, an instruction outside the allowed set is present, an account other than the relayer is marked as signer, the relayer's key appears in a place other than fee payer, token account funder, SOL fee recipient or seat opener, the hook has a payer slot and is not a launch hook, or the setup calls of an opening are not Kamino's seat setup |
The relayer reads the hook, the hook's companions as stored on chain, the relayer's fee, whether the run has an asset out and the mints from the Pook instruction in instructionDataBase64 and accounts. The other fields of a request body are informational. It signs only for the Pook program, the Compute Budget program, an idempotent create of an associated token account and the companion instructions the hook names on chain.
GET /v1/relayer/quote
The relayer's fee for one submission.
| Query | Type | Meaning |
|---|---|---|
kind | 'run' | 'leave' | 'open_seat' | 'close_seat' | What will be relayed. |
mint | Address | The asset the fee is paid in: the asset out of a run, or the asset leaving. |
hookIdoptional | HookId | The hook, for a run. |
| Field | Type | Meaning |
|---|---|---|
relayer | Address | The relayer's address, the fee payer of what it sends. |
mint | Address | The asset of the fee. |
feeAmount | BaseUnits | The fee. A submission that names less is refused. |
expiresAt | Timestamp | When the quote stops holding, five minutes after it was made. |
Answers 409 CONFIGURATION_REQUIRED from a relayer with no signing key, or with no fee set for mint.
POST /v1/relayer/run
Submits a proven run. Runs lists what the proof fixes; the body carries those values with the proofs and the built instruction.
| Body | Type | Meaning |
|---|---|---|
hookId | HookId | The hook. |
quoteIdoptional | string | The quote the run was built from, up to 128 characters. |
appProofBase64 | Base64 | The proof for Pook's run. |
sppProofBase64 | Base64 | The proof for the Solana Privacy Program spend. |
transactDataBase64 | Base64 | The Privacy Program transact data. |
resolvedAccounts | Address[] | The accounts passed to the protocol, in order, up to 64. |
resolvedDataBase64 | Base64 | The instruction data sent to the protocol. |
instructionDataBase64 | Base64 | The data of the run instruction. Its first byte is the run tag, 4. |
accounts | AccountMeta[] | The accounts of the run instruction, in order, 1 to 64. |
companionInstructionsoptional | Instruction[] | The companion instructions from the quote, up to 8. |
setupInstructionsoptional | Instruction[] | The setup instructions from the quote, up to 8. |
computeUnitLimitoptional | integer | The compute limit, 100,000 to 1,400,000. Default 1,400,000. |
mintInoptional | Address | The asset in. |
mintOutoptional | Address | The asset out. When present, relayerFee is checked against the relayer's fee for it. |
amountIn | BaseUnits | The amount in. |
minimumOut | BaseUnits | The minimum out. |
relayerFee | BaseUnits | The relayer's fee the proof fixes. |
expiryUnixTs | U64 | The expiry the proof fixes, as Unix seconds. |
seatAddressoptional | Address | The seat, for a seat hook. |
The transaction is the setup instructions, then the companion instructions, then the run.
Beyond the shared answers: 404 NOT_FOUND when the hook is not on chain, and 422 RELAY_REFUSED when relayerFee is below the relayer's fee for mintOut.
POST /v1/relayer/leave
Submits a proven leave: an amount moves out of your private balance to a public address or to a balance on Solana Privacy Rings.
| Body | Type | Meaning |
|---|---|---|
destinationType | 'wallet' | 'rings' | Where the amount goes. |
destination | string | The destination, 16 to 160 characters: the receiving address for wallet, the owner hash of the recipient as 64 hex characters for rings. |
mint | Address | The asset leaving. |
amount | PositiveU64 | The amount leaving. |
appProofBase64 | Base64 | The proof for Pook's leave. |
sppProofBase64 | Base64 | The proof for the Privacy Program spend. |
transactDataBase64 | Base64 | The Privacy Program transact data. |
instructionDataBase64 | Base64 | The data of the leave instruction. Its first byte is the leave tag, 5. |
accounts | AccountMeta[] | The accounts of the leave instruction, in order, 1 to 64. |
setupInstructionsoptional | Instruction[] | Instructions placed before the leave, up to 8. |
computeUnitLimitoptional | integer | The compute limit, 100,000 to 1,400,000. Default 1,400,000. |
relayerFee | BaseUnits | The relayer's fee, taken from the amount leaving. |
expiryUnixTs | U64 | The expiry the proof fixes, as Unix seconds. |
The leave instruction carries the Rings recipient as an owner hash and a view tag. A client that starts from the recipient's Solana wallet reads that wallet's record in the Rings user registry with POST /v1/photon/getUserRecords and derives both from it.
Beyond the shared answers: 422 RELAY_REFUSED when relayerFee is below the relayer's fee for mint.
POST /v1/relayer/seat/open
Submits a proven open of a seat. The relayer pays the rent of the seat's state account.
| Body | Type | Meaning |
|---|---|---|
seatCommitmentHex | Hex | The commitment the seat is opened with. |
seatAddressoptional | Address | The seat address, echoed in the response. |
instructionDataBase64 | Base64 | The data of the instruction. Its first byte is the open tag, 6. |
accounts | AccountMeta[] | The accounts of the instruction, in order, up to 64. |
computeUnitLimitoptional | integer | The compute limit, 100,000 to 1,400,000. Default 1,400,000. |
expiryUnixTs | U64 | The expiry the proof fixes, as Unix seconds. |
POST /v1/relayer/seat/close
Submits a proven close of a seat. The body is the same as for opening one, and the first byte of instructionDataBase64 is the close tag, 7. Answers 409 SEAT_NOT_EMPTY while the seat still holds collateral or owes debt at its protocol.
GET /v1/relayer/runs/:relayId
The status of any relayed submission: a run, a leave, or a seat opened or closed. The response is a RelaySubmissionResponse. Reading a submission that is still submitted checks the cluster once.
Answers 404 NOT_FOUND for a relayId the relayer does not hold.
Publishing
The three routes a hook's author uses, in order: read the protocol's instructions, test the hook, build the transaction that publishes it. Hook schema specifies the hook itself.
POST /v1/hooks/parse-idl
Reads an Anchor IDL into the instructions a hook can be written against.
| Body | Type | Meaning |
|---|---|---|
programIdoptional | Address | The program. Without idlJson, the API reads the program's IDL account from the cluster. |
idlJsonoptional | string | The IDL as JSON text, 2 to 524,288 characters. |
Send at least one of the two.
| Field | Type | Meaning |
|---|---|---|
programId | Address | null | The program the IDL belongs to. |
programName | string | The name in the IDL. |
version | string | null | The version in the IDL. |
instructions | ParsedIdlInstruction[] | One entry per instruction. |
instructions[].name | string | The instruction name. |
instructions[].discriminator | Hex | Its discriminator. |
instructions[].args | ParsedIdlArg[] | Its arguments in order: name, type, and the offset and length in bytes within the instruction data. |
instructions[].accounts | ParsedIdlAccount[] | Its accounts in order: index, name, writable, signer. |
Answers 400 IDL_INVALID when the JSON does not parse as an IDL or holds no instructions, and 404 NOT_FOUND when the program has no IDL account.
POST /v1/hooks/simulate
Simulates the call a hook describes against the cluster, with the stage standing in for every stage and seat account.
| Body | Type | Meaning |
|---|---|---|
hook | HookDraft | The hook, as below. |
sampleAmountIn | PositiveU64 | The amount written into the amount slot. |
sampleMintInoptional | Address | An asset in for the sample. |
sampleMintOutoptional | Address | An asset out for the sample. |
sampleArgsoptional | Record<string, string> | Sample values. A key that matches a caller account slot sets its address, and callerDataHex sets the caller bytes. |
| Field | Type | Meaning |
|---|---|---|
passed | boolean | Whether the simulation succeeded. |
computeUnits | integer | null | Compute units the call used. |
logs | string[] | The program logs. |
estimatedTxBytes | integer | null | The size of the simulated transaction in bytes. |
accountCount | integer | How many accounts the call passes. |
erroroptional | object | Present when passed is false, with code SIMULATION_FAILED. |
A simulation that fails still answers 200, with passed false. Answers 409 PROGRAM_UNAVAILABLE.
A HookDraft:
| Field | Type | Meaning |
|---|---|---|
id | HookId | The id to publish under. |
protocol | string | The protocol, 1 to 32 characters. |
protocolName | string | The protocol as shown to people, 1 to 64 characters. |
label | string | The name of the action, 1 to 64 characters. |
description | string | What it does, 1 to 280 characters. |
kind | 'flow' | 'seat' | Whether the hook acts on a seat. |
targetProgram | Address | The protocol's program. |
instructionName | string | The instruction, 1 to 64 characters. |
discriminator | Hex | Its discriminator. |
dataTemplate | { baseHex: Hex, slots } | The instruction data, at most 256 bytes, and up to 16 slots. A slot has name (1 to 64), kind, offset (0 to 256), length (0 to 256), type, and optional label (up to 64) and description (up to 240). |
accountsTemplate | AccountSlot[] | 1 to 48 account slots. A slot has index (0 to 47), name (1 to 64), role, writable, signer, and optional address and description (up to 240). |
companionInstructionsoptional | CompanionInstruction[] | Up to 8: programId, instructionName (1 to 64), discriminator (at most 8 bytes), position ('before' or 'after') and optional description (up to 240). |
mintIn | Address | null | The asset in, or null to leave it open. |
mintOut | Address | null | The asset out, or null to leave it open. |
assetInSymboloptional | string | null | Its symbol, up to 24 characters. |
assetOutSymboloptional | string | null | Its symbol, up to 24 characters. |
mintInConstraintoptional | MintConstraint | The constraint on the asset in, used as given: kind 'None', 'Any', 'Sol' or 'Spl' with mint. |
mintOutConstraintoptional | MintConstraint | The same for the asset out. |
wrapSolInoptional | boolean | Wrap SOL in before the call. Default false. |
unwrapSolOutoptional | boolean | Unwrap SOL out after the call. Default false. |
dataTemplateHexoptional | Hex | The data template as stored, at most 256 bytes, used as given. |
dataSlotsoptional | OnChainDataSlot[] | Up to 16 data slots as stored: offset and len (0 to 256) and kind. |
accountSlotsoptional | OnChainAccountSlot[] | Up to 48 account slots as stored: kind, isWritable, isSigner and pubkey. |
companionsoptional | OnChainCompanion[] | Up to 8 companions as stored: programId, discriminatorHex (at most 8 bytes), discLen (0 to 8) and mustPrecede. |
formFieldsoptional | HookFormField[] | Up to 16 form inputs: name, kind, label, required, and optional defaultValue and placeholder (up to 128 each). |
Where dataSlots, accountSlots, companions or a mint constraint is left out, the API derives it from dataTemplate, accountsTemplate, companionInstructions, mintIn and mintOut. The values each kind, type and role can take are on Hook schema.
POST /v1/hooks/publish/build
Builds the transaction that publishes a hook. The author signs it and pays for the hook's account.
| Body | Type | Meaning |
|---|---|---|
author | Address | The wallet that signs. It becomes the author of the hook. |
hook | HookDraft | The hook. |
The response is a TxBuildResponse with action publish_hook. Submit it with POST /v1/tx/submit.
Answers 409 HOOK_ALREADY_EXISTS when the id is taken, 409 PROGRAM_UNAVAILABLE, and 422 SIMULATION_FAILED when the build fails simulation.
Author fees
The author's share of each run fee accrues to the hook's author, per asset. Fees and POOK explains the split.
GET /v1/authors/:wallet/fees
What an author has earned and can claim. :wallet is the author's Address.
| Field | Type | Meaning |
|---|---|---|
author | Address | The author. |
hooks | AuthorHookFee[] | One entry per hook and asset. |
hooks[].hookId | string | The hook. |
hooks[].hookAddress | Address | The hook's account. |
hooks[].mint | Address | The asset of the fees. |
hooks[].assetSymbol | string | null | Its symbol. |
hooks[].decimals | integer | Its decimals. |
hooks[].claimableAmount | BaseUnits | What can be claimed now, read from the author's fee account for that asset. |
hooks[].totalEarnedAmount | BaseUnits | Everything the hook has earned in that asset. |
hooks[].lastClaimedAt | Timestamp | null | The last claim. |
asOf | Timestamp | When it was read. |
Answers 409 PROGRAM_UNAVAILABLE.
POST /v1/authors/:wallet/claim/build
Builds the transaction that pays accrued fees to the author. For a token, it creates the author's associated token account when the wallet has none.
| Body | Type | Meaning |
|---|---|---|
hookIds | HookId[] | 1 to 16 hooks to claim for. |
mintoptional | Address | Claim this asset only. Without it, the transaction claims every asset that has fees accrued for those hooks. |
The response is a TxBuildResponse with action claim_author_fees. The author's wallet signs it. Submit it with POST /v1/tx/submit.
Answers 409 PROGRAM_UNAVAILABLE, and 422 SIMULATION_FAILED when the build fails simulation.
Pass-through routes
These routes forward to a service behind the API, so a browser reaches the cluster, the Rings indexer and the Rings prover from one origin.
POST /v1/rpc
Solana JSON-RPC 2.0. Send one request per call, with a string or integer id and params as an array.
The methods relayed are getAccountInfo, getMultipleAccounts, getBalance, getTokenAccountBalance, getSlot, getBlockHeight, getLatestBlockhash, isBlockhashValid, getFeeForMessage, getMinimumBalanceForRentExemption, getSignatureStatuses, getTransaction, getSignaturesForAddress, getGenesisHash, getVersion, simulateTransaction and sendTransaction. getProgramAccounts is relayed for one query: the Privacy Program's list of registered assets.
Each client gets 600 reads and 30 sendTransaction calls a minute. The body is at most 64 KiB.
A success is the cluster's own response. A failure is a JSON-RPC error object, not the envelope above:
| HTTP | JSON-RPC code | When |
|---|---|---|
| 400 | -32700 | The body is not JSON |
| 400 | -32600 | Not a single JSON-RPC 2.0 request with an id, a method and array params |
| 413 | -32600 | The body is too large |
| 400 | -32601 | The method is not relayed |
| 200 | -32601 | A getProgramAccounts query other than the one relayed |
| 429 | -32005 | Over the rate. Retry-After says when to try again |
| 200 | -32004 | The API is waiting |
| 502 | -32603 | The cluster RPC could not be reached |
POST /v1/photon/:method
One read from the Rings indexer. :method is getEncryptedUtxosByTags, getShieldedTransactionsByTags, getShieldedTransactionsBySignature, getShieldedTransactionsByNullifiers, getMerkleProofs, getNonInclusionProofs or getUserRecords.
The body is the method's parameters as JSON, either bare or as an object with params and an optional id. The API forwards them as a JSON-RPC 2.0 request and returns the indexer's response with its status.
Answers 400 VALIDATION_ERROR with stage read for any other method or a body that is not JSON, and 502 UPSTREAM_UNAVAILABLE when the indexer could not be reached.
ANY /v1/prover/spp/*
Forwards the request to the Rings prover, which produces the proof for the Solana Privacy Program spend. The method, the body, the query and the rest of the path go through as sent, and the prover's response comes back with its status.
Answers 502 UPSTREAM_UNAVAILABLE with stage proving when the Rings prover could not be reached.