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

FormatTypeMeaning
AddressstringA base58 public key of 32 bytes, 32 to 44 characters.
SignaturestringA base58 transaction signature of 64 bytes, 64 to 88 characters.
BaseUnitsstringAn unsigned integer as a decimal string, in the smallest unit of its asset. No sign, no leading zero, no decimal point.
U64stringBaseUnits that fit an unsigned 64-bit integer. Slots, block heights and Unix times use it too.
PositiveU64stringA U64 greater than zero.
Base64stringStandard base64 with padding.
HexstringHex bytes, an even number of characters, either case.
TimestampstringISO 8601 date and time in UTC, ending in Z.
HookIdstringA 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.

ParameterTypeMeaning
cursoroptionalstringThe nextCursor of the page before. Digits only, up to 12. Leave it out for the first page.
limitoptionalintegerItems per page, 1 to 100. Default 24.
FieldTypeMeaning
itemsarrayThe items of this page.
page.nextCursorstring | nullThe cursor of the next page, or null on the last one.
page.hasMorebooleanWhether a next page exists.
asOfTimestampWhen 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:

JSON
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Check the highlighted fields.",
    "retryable": false,
    "stage": "validation",
    "fieldErrors": { "amountIn": ["Must be greater than zero."] }
  }
}
FieldTypeMeaning
codestringThe stable code to branch on. The table below lists every one.
messagestringOne sentence a person can read.
retryablebooleanWhether sending the same request again can succeed.
stagestringThe step that failed.
fieldErrorsoptionalRecord<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.
retryAfterSecondsoptionalintegerSeconds to wait before retrying. The Retry-After header carries the same value.
requestIdoptionalstringThe 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:

CodeTypeMeaning
VALIDATION_ERRORHTTP 400The 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.
UNAUTHORIZEDHTTP 401A wallet signer is required and none is connected. The SDK raises it before any request.
ORIGIN_NOT_ALLOWEDHTTP 403The Origin header of a browser request is not one the API accepts.
NOT_FOUNDHTTP 404The 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_UNAVAILABLEHTTP 409The API is waiting for the Pook program on its cluster.
CONFIGURATION_REQUIREDHTTP 409The service is missing a value it needs to act, such as a relayer started without its signing key.
IDEMPOTENCY_CONFLICTHTTP 409The request was already submitted with different parameters.
TRANSACTION_EXPIREDHTTP 409The 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_LARGEHTTP 413The request body is over 1 MiB.
UNSUPPORTED_MEDIA_TYPEHTTP 415A POST body was sent without Content-Type: application/json.
SIMULATION_FAILEDHTTP 422The transaction failed in simulation. Nothing was sent. programError names the program and its error when a program refused it.
CHAIN_REFUSEDHTTP 422A program refused the transaction on chain. programError names the program and its error.
RATE_LIMITEDHTTP 429Too many requests. retryAfterSeconds and the Retry-After header say when to try again.
INTERNAL_ERRORHTTP 500The request could not be completed. requestId identifies it.
UPSTREAM_UNAVAILABLEHTTP 502The cluster RPC, the relayer, the prover, the Rings indexer or Jupiter could not be reached.
NO_ROUTEHTTP 422No route exists for this asset pair and amount.
QUOTE_EXPIREDHTTP 409The quote is past its expiresAt. Quote again.
INSUFFICIENT_BALANCEHTTP 422The private balance does not cover the amount. The SDK raises it when at most two notes cannot cover the amount in.
PROOF_FAILEDHTTP 422A proof could not be generated or did not verify.
PROOF_EXPIREDHTTP 409The proof passed its expiry before the run landed. No note was spent. Prove again.
RELAY_REFUSEDHTTP 422The 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_REJECTEDHTTP 400The wallet declined to sign. The SDK raises it.
IDL_INVALIDHTTP 400The IDL could not be parsed, or it holds no instructions.
HOOK_ALREADY_EXISTSHTTP 409A hook with this id is already published.
SEAT_NOT_EMPTYHTTP 409The seat still holds collateral or debt. Repay and withdraw before closing it.
SCAN_FAILEDHTTP 502The 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.

FieldTypeMeaning
signatureSignatureThe transaction of the run.
slotU64The slot it landed in.
hookIdstringThe hook that ran.
hookAddressAddressThe hook's account.
protocolstringThe protocol the hook calls, such as jupiter.
kind'flow' | 'seat'The kind of hook.
mintInAddress | nullThe asset in, or null when the run takes none.
assetInSymbolstring | nullIts symbol.
amountInBaseUnitsWhat entered the stage.
mintOutAddress | nullThe asset out, or null when the run returns none.
assetOutSymbolstring | nullIts symbol.
amountOutBaseUnitsWhat the protocol returned to the stage.
runFeeAmountBaseUnitsThe run fee taken from the result.
relayerFeeAmountBaseUnitsThe relayer's fee taken from the result.
stageAuthorityAddressThe stage that signed the call.
relayerAddressThe fee payer of the transaction.
status'confirmed' | 'finalized'The commitment the run has reached.
timestampTimestampThe block time.

TxBuildResponse

An unsigned transaction for a wallet to sign. Enter, publishing and claiming all answer with it.

FieldTypeMeaning
buildIdstringThe id to submit and follow the transaction with.
action'enter' | 'publish_hook' | 'claim_author_fees'What the transaction does.
transactionBase64Base64The unsigned version 0 transaction. The wallet named in the request is its fee payer.
blockhashstringThe recent blockhash it was built on.
lastValidBlockHeightU64The last block height at which that blockhash is valid.
networkFeeLamportsBaseUnitsThe network fee in lamports.
expiresAtTimestampWhen 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

FieldTypeMeaning
idstringThe build id.
actionoptionalstringThe action of the build.
statusstringWhere the transaction stands.
signatureSignature | nullThe transaction signature once known.
slotU64 | nullThe slot it landed in.
erroroptionalobjectWhy it failed or expired, in the shape of the error envelope.
updatedAtTimestampWhen 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

FieldTypeMeaning
relayIdstringThe id to follow the submission with.
kind'run' | 'leave' | 'open_seat' | 'close_seat'What was relayed.
statusstringWhere the transaction stands.
signatureSignature | nullThe transaction signature.
slotU64 | nullThe slot it landed in, once confirmed.
hookIdoptionalstring | nullThe hook, for a run.
seatAddressoptionalAddress | nullThe seat, where the submission names one.
relayerFeeBaseUnitsThe relayer's fee the proof fixes. Zero for opening and closing a seat.
runoptionalPublicRun | nullThe run as indexed, where the relayer has it.
erroroptionalobjectWhy it failed or expired, in the shape of the error envelope.
expiresAtTimestampThe expiry the proof fixes.
updatedAtTimestampWhen 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.

FieldTypeMeaning
status'ready' | 'waiting'See Readiness.
programIdAddress | nullThe Pook program.
cluster'localnet' | 'devnet' | 'mainnet'The cluster the API reads.
contractVersionstringThe version of the API contract, the same as X-Contract-Version.
asOfTimestampWhen 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.

FieldTypeMeaning
status'ready' | 'waiting'See Readiness.
clusterstringThe cluster the API reads.
programIdAddress | nullThe Pook program.
authorityPdaAddress | nullThe program's authority account.
stagePdaoptionalAddress | nullThe stage.
configPdaoptionalAddress | nullThe program's config account.
ringsProgramIdAddressThe Solana Privacy Program.
stateTreeAddressThe state tree notes are written to.
runFeeBpsinteger | nullThe run fee in basis points, read from the config account.
authorShareBpsinteger | nullThe author's share of the run fee in basis points.
feeRecipientAddress | nullThe account that receives the protocol share.
pookMintAddress | nullThe mint of POOK.
relayerUrlstringThe relayer behind /v1/relayer.
proverUrlstringThe prover behind /v1/prover.
photonRelayUrloptionalstringThe path of the Rings indexer pass-through, /v1/photon.
supportedAssetsAssetInfo[]Each asset the API names: mint (Address), symbol, name, decimals (integer) and, for SOL, isNative (boolean).
asOfTimestampWhen the answer was made.

GET /v1/stats

FieldTypeMeaning
status'ready' | 'waiting'See Readiness.
hooksCountintegerPublished hooks.
runsCountintegerRuns indexed.
activeSeatsCountintegerSeats that are open.
volumeByAssetAssetVolume[]For each asset in: mint (Address), symbol, decimals (integer) and volume (BaseUnits), the sum of amountIn across runs.
asOfTimestampWhen 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.

QueryTypeMeaning
protocoloptionalstringOnly hooks of this protocol, 1 to 32 characters. Case is ignored.
kindoptional'flow' | 'seat'Only hooks of this kind.
qoptionalstringText to find in the id, the protocol name, the label or the description. Up to 64 characters.
cursoroptionalstringSee Pagination.
limitoptionalintegerSee Pagination.

The response is status, items, page and asOf. Each item is a HookSummary:

FieldTypeMeaning
idstringThe hook id.
addressAddressThe hook's account.
protocolstringThe protocol, as a short lowercase name.
protocolNamestringThe protocol, as shown to people.
labelstringThe name of the action.
descriptionstringOne or two sentences on what it does.
kind'flow' | 'seat'Whether the hook acts on a seat.
targetProgramAddressThe protocol's program.
instructionNamestringThe instruction it calls.
mintInAddress | nullThe asset in when the hook fixes one.
mintOutAddress | nullThe asset out when the hook fixes one.
mintInConstraintoptionalMintConstraintWhat the hook allows as the asset in: kind is 'None', 'Any', 'Sol' or 'Spl', and 'Spl' carries mint.
mintOutConstraintoptionalMintConstraintThe same for the asset out.
wrapSolInoptionalbooleanWhether SOL in is wrapped before the call.
unwrapSolOutoptionalbooleanWhether wrapped SOL out is unwrapped after the call.
assetInSymbolstring | nullThe symbol of the asset in.
assetOutSymbolstring | nullThe symbol of the asset out.
authorAddressThe wallet that published the hook.
authorShareBpsinteger | nullThe author's share of the run fee in basis points.
immutablebooleanWhether the hook is immutable.
sdkCallstringThe SDK call that runs this hook, as text.
statsHookStatsrunsCount (integer), volumeIn and volumeOut (BaseUnits), lastRunAt (Timestamp or null).
publishedAtTimestampWhen it was published.

GET /v1/hooks/:id

One hook in full, with its ten most recent runs. :id is a HookId.

FieldTypeMeaning
hookHookDetailThe hook.
recentRunsPublicRun[]Up to ten runs, newest first.
asOfTimestampWhen the answer was made.

A HookDetail is a HookSummary with these fields added. Hook schema specifies each of them and every slot kind.

FieldTypeMeaning
discriminatorHexThe 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.
accountsTemplateAccountSlot[]The account list with names. A slot has index, name, role, writable, signer and optional address and description.
companionInstructionsCompanionInstruction[]Instructions that must travel with the run: programId, instructionName, discriminator, position ('before' or 'after') and optional description.
dataTemplateHexoptionalHexThe data template as the hook account stores it.
dataSlotsoptionalOnChainDataSlot[]The data slots as stored: offset, len and kind.
accountSlotsoptionalOnChainAccountSlot[]The account slots as stored: kind, isWritable, isSigner and pubkey.
companionsoptionalOnChainCompanion[]The companions as stored: programId, discriminatorHex, discLen and mustPrecede.
formFieldsHookFormField[]The inputs a form shows for this hook: name, kind, label, required and optional defaultValue and placeholder.
publishSignatureSignatureThe 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.

BodyTypeMeaning
amountInPositiveU64The amount in. For a hook that takes no asset in, the amount the action asks the protocol for.
mintInoptionalAddressThe asset in, where the hook leaves it open.
mintOutoptionalAddressThe asset out, where the hook leaves it open.
minimumOutoptionalBaseUnitsThe 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.
slippageBpsoptionalintegerAllowed slippage in basis points, 0 to 5000. Default 50.
seatAddressoptionalAddressThe seat, for a seat hook.
argsoptionalRecord<string, string>Values for the hook's caller slots. A key that matches an account slot's name sets that account's address.
JSON
{
  "mintIn": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "mintOut": "So11111111111111111111111111111111111111112",
  "amountIn": "1000000",
  "slippageBps": 50
}

That body, sent to /v1/hooks/jupiter.swap/quote, quotes a swap from USDC to SOL.

FieldTypeMeaning
quoteIdstringThe id of this quote.
hookIdstringThe hook quoted.
hookAddressoptionalAddressThe hook's account.
hookAuthoroptionalAddressThe hook's author.
feeRecipientoptionalAddress | nullThe account that receives the protocol share.
relayeroptionalAddressThe relayer the accounts were resolved for.
mintInAddress | nullThe asset in.
assetInSymbolstring | nullIts symbol.
amountInBaseUnitsWhat leaves your notes for the stage. Zero for a hook that takes no asset in.
mintOutAddress | nullThe asset out.
assetOutSymbolstring | nullIts symbol.
tokenProgramInoptionalAddressThe token program of the asset in.
tokenProgramOutoptionalAddressThe token program of the asset out.
expectedOutBaseUnitsWhat the protocol is expected to return.
minimumOutBaseUnitsThe least the run may bring back: expectedOut after slippage, or the minimumOut of the request.
minimumOutFromCalleroptionalbooleantrue when minimumOut is the one the request sent. expectedOut then equals it.
slippageBpsintegerThe slippage applied.
feesQuoteFeesSee below.
netOutBaseUnitsexpectedOut less the run fee and the relayer's fee.
minimumNetOutoptionalBaseUnitsminimumOut less the run fee and the relayer's fee: the least that reaches the holder. The program checks minimumOut, before fees.
resolvedAccountsResolvedAccount[]Every account passed to the protocol, in order: index, name, address, writable, signer.
resolvedDataBase64Base64The instruction data after the slots are filled.
callHashHexoptionalHexThe 32-byte call hash the proof binds.
callerDataBase64optionalBase64The bytes that fill the hook's caller slots.
callerAccountsoptionalAccountMeta[]The accounts the caller supplies to the run instruction.
callerRemainingWritableoptionalinteger[]A 0 or 1 writable flag for each trailing caller account.
setupInstructionsoptionalInstruction[]Instructions the relayer places before the run, such as creating a token account for the stage.
companionInstructionsInstruction[]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.
routeSummarystring | nullThe route in words.
expiresAtTimestampWhen the quote stops holding, five minutes after it was made.

QuoteFees. Every amount is in the asset feeAssetMint names.

FieldTypeMeaning
runFeeAmountBaseUnitsThe run fee.
runFeeBpsinteger | nullIts rate in basis points.
authorShareAmountBaseUnitsThe author's share of the run fee.
authorShareBpsinteger | nullIts rate in basis points of the run fee.
protocolShareAmountBaseUnitsThe protocol share of the run fee.
relayerFeeAmountBaseUnitsThe relayer's fee.
feeAssetMintAddress | nullThe asset the fees are taken in.
feeAssetSymbolstring | nullIts 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.

QueryTypeMeaning
hookIdoptionalHookIdOnly runs of this hook.
protocoloptionalstringOnly runs of this protocol, 1 to 32 characters. Case is ignored.
cursoroptionalstringSee Pagination.
limitoptionalintegerSee 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:

FieldTypeMeaning
typestringThe event type, the same as the event line.
idstringThe event id, the same as the id line.
timestampTimestampWhen the API sent it.
dataobjectThe payload, by type.
EventWhendata
readyFirst, on every connectionstatus: ready or waiting
runA run was indexedA PublicRun
resyncThe stream cannot give you what you missedreason: 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.

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

QueryTypeMeaning
mintoptionalAddressThe asset. Default wrapped SOL, which reads the SOL balance of the wallet.
FieldTypeMeaning
walletAddressThe wallet read.
mintAddressThe asset. SOL is reported under the wrapped SOL mint.
symbolstring | nullThe symbol, for an asset the API names.
decimalsintegerThe decimals of the mint.
amountBaseUnitsThe balance. For a token, the balance of the associated token account of the wallet.
asOfTimestampWhen 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.

QueryTypeMeaning
ownerTagoptionalAddressOnly records under this owner tag.
afterSlotoptionalU64Only records after this slot.
cursoroptionalstringSee Pagination.
limitoptionalintegerSee Pagination.

The response is items, page and asOf. Each item:

FieldTypeMeaning
commitmentstringThe note commitment.
treeIdintegerThe state tree it is in.
leafIndexintegerIts leaf in that tree.
slotU64The slot it was written in.
signatureSignatureThe transaction that wrote it.
ownerTagAddressThe tag a holder matches against its own one-time keys.
ciphertextBase64Base64The encrypted note.
txViewingPkBase64Base64The viewing public key of the transaction.
saltBase64Base64The salt of the encryption.
timestampTimestampThe block time.

POST /v1/notes/nullifiers

BodyTypeMeaning
nullifiersstring[]1 to 200 nullifiers, each 1 to 128 characters.
FieldTypeMeaning
spentRecord<string, boolean>One entry per nullifier sent.
asOfTimestampWhen 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.

BodyTypeMeaning
seatAddressesAddress[]Up to 50 seat addresses.

The response is seats and asOf. Each seat is a SeatPosition, in the order sent:

FieldTypeMeaning
seatAddressAddressThe seat.
commitmentHexoptionalHexThe commitment the seat was opened with.
openerRelayeroptionalAddress | nullThe relayer that opened it.
protocolstringThe protocol the position is in.
protocolNamestringThe protocol, as shown to people.
obligationAddressAddress | nullThe protocol's own account for the position.
status'open' | 'empty' | 'closed'open holds collateral or debt. empty holds neither.
collateralSeatAssetPosition[]Deposits: mint, symbol, decimals, amount (BaseUnits) and usdValue (string or null).
debtSeatAssetPosition[]Borrows, in the same shape.
depositedValueUsdoptionalstring | nullThe value of the collateral in USD, as the protocol reports it.
borrowFactorAdjustedDebtUsdoptionalstring | nullThe debt in USD after the borrow factor.
unhealthyBorrowValueUsdoptionalstring | nullThe debt value at which the position can be liquidated.
healthFactorstring | nullThe health of the position, computed from the two values above.
actionsstring[]The ids of the hooks that act on this seat.
updatedAtTimestampWhen 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.

BodyTypeMeaning
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.
walletAddressThe wallet that signs and pays the network fee.
mintAddressThe asset. The wrapped SOL mint enters SOL.
amountPositiveU64The amount to enter.
outputOwnerHashstringThe one-time owner of the note that receives the amount: 32 bytes as hex when source is wallet.
outputViewingPkBase64optionalBase64The viewing public key of the output note.
transactDataBase64optionalBase64Required when source is rings: the Privacy Program transact data the client built.
transactAccountsoptionalAccountMeta[]Required when source is rings: the accounts of that transact, up to 64.
JSON
{
  "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.

BodyTypeMeaning
buildIdstringThe buildId of the build, 1 to 128 characters.
signedTransactionBase64optionalBase64The signed transaction. The API checks it against the build and broadcasts it.
signatureoptionalSignatureThe 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

FieldTypeMeaning
status'ready' | 'waiting'ready when at least one circuit is available.
circuitsProverCircuitArtifact[]One entry per circuit.
circuits[].circuitstringThe circuit name.
circuits[].xbcSha256Hex | nullSHA-256 of circuit.xbc.
circuits[].pkSha256Hex | nullSHA-256 of pk.bin.
circuits[].vkSha256Hex | nullSHA-256 of vk.bin.
circuits[].availablebooleanWhether all three files are served.
asOfTimestampWhen 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:

StatusCodeWhen
409TRANSACTION_EXPIREDexpiryUnixTs is not in the future
409PROGRAM_UNAVAILABLEThe relayer has no Pook program to send to
409CONFIGURATION_REQUIREDThe relayer has no signing key
409CONFIGURATION_REQUIREDThe relayer has no fee set for the instruction's asset
422RELAY_REFUSEDThe 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.

QueryTypeMeaning
kind'run' | 'leave' | 'open_seat' | 'close_seat'What will be relayed.
mintAddressThe asset the fee is paid in: the asset out of a run, or the asset leaving.
hookIdoptionalHookIdThe hook, for a run.
FieldTypeMeaning
relayerAddressThe relayer's address, the fee payer of what it sends.
mintAddressThe asset of the fee.
feeAmountBaseUnitsThe fee. A submission that names less is refused.
expiresAtTimestampWhen 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.

BodyTypeMeaning
hookIdHookIdThe hook.
quoteIdoptionalstringThe quote the run was built from, up to 128 characters.
appProofBase64Base64The proof for Pook's run.
sppProofBase64Base64The proof for the Solana Privacy Program spend.
transactDataBase64Base64The Privacy Program transact data.
resolvedAccountsAddress[]The accounts passed to the protocol, in order, up to 64.
resolvedDataBase64Base64The instruction data sent to the protocol.
instructionDataBase64Base64The data of the run instruction. Its first byte is the run tag, 4.
accountsAccountMeta[]The accounts of the run instruction, in order, 1 to 64.
companionInstructionsoptionalInstruction[]The companion instructions from the quote, up to 8.
setupInstructionsoptionalInstruction[]The setup instructions from the quote, up to 8.
computeUnitLimitoptionalintegerThe compute limit, 100,000 to 1,400,000. Default 1,400,000.
mintInoptionalAddressThe asset in.
mintOutoptionalAddressThe asset out. When present, relayerFee is checked against the relayer's fee for it.
amountInBaseUnitsThe amount in.
minimumOutBaseUnitsThe minimum out.
relayerFeeBaseUnitsThe relayer's fee the proof fixes.
expiryUnixTsU64The expiry the proof fixes, as Unix seconds.
seatAddressoptionalAddressThe 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.

BodyTypeMeaning
destinationType'wallet' | 'rings'Where the amount goes.
destinationstringThe destination, 16 to 160 characters: the receiving address for wallet, the owner hash of the recipient as 64 hex characters for rings.
mintAddressThe asset leaving.
amountPositiveU64The amount leaving.
appProofBase64Base64The proof for Pook's leave.
sppProofBase64Base64The proof for the Privacy Program spend.
transactDataBase64Base64The Privacy Program transact data.
instructionDataBase64Base64The data of the leave instruction. Its first byte is the leave tag, 5.
accountsAccountMeta[]The accounts of the leave instruction, in order, 1 to 64.
setupInstructionsoptionalInstruction[]Instructions placed before the leave, up to 8.
computeUnitLimitoptionalintegerThe compute limit, 100,000 to 1,400,000. Default 1,400,000.
relayerFeeBaseUnitsThe relayer's fee, taken from the amount leaving.
expiryUnixTsU64The 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.

BodyTypeMeaning
seatCommitmentHexHexThe commitment the seat is opened with.
seatAddressoptionalAddressThe seat address, echoed in the response.
instructionDataBase64Base64The data of the instruction. Its first byte is the open tag, 6.
accountsAccountMeta[]The accounts of the instruction, in order, up to 64.
computeUnitLimitoptionalintegerThe compute limit, 100,000 to 1,400,000. Default 1,400,000.
expiryUnixTsU64The 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.

BodyTypeMeaning
programIdoptionalAddressThe program. Without idlJson, the API reads the program's IDL account from the cluster.
idlJsonoptionalstringThe IDL as JSON text, 2 to 524,288 characters.

Send at least one of the two.

FieldTypeMeaning
programIdAddress | nullThe program the IDL belongs to.
programNamestringThe name in the IDL.
versionstring | nullThe version in the IDL.
instructionsParsedIdlInstruction[]One entry per instruction.
instructions[].namestringThe instruction name.
instructions[].discriminatorHexIts discriminator.
instructions[].argsParsedIdlArg[]Its arguments in order: name, type, and the offset and length in bytes within the instruction data.
instructions[].accountsParsedIdlAccount[]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.

BodyTypeMeaning
hookHookDraftThe hook, as below.
sampleAmountInPositiveU64The amount written into the amount slot.
sampleMintInoptionalAddressAn asset in for the sample.
sampleMintOutoptionalAddressAn asset out for the sample.
sampleArgsoptionalRecord<string, string>Sample values. A key that matches a caller account slot sets its address, and callerDataHex sets the caller bytes.
FieldTypeMeaning
passedbooleanWhether the simulation succeeded.
computeUnitsinteger | nullCompute units the call used.
logsstring[]The program logs.
estimatedTxBytesinteger | nullThe size of the simulated transaction in bytes.
accountCountintegerHow many accounts the call passes.
erroroptionalobjectPresent when passed is false, with code SIMULATION_FAILED.

A simulation that fails still answers 200, with passed false. Answers 409 PROGRAM_UNAVAILABLE.

A HookDraft:

FieldTypeMeaning
idHookIdThe id to publish under.
protocolstringThe protocol, 1 to 32 characters.
protocolNamestringThe protocol as shown to people, 1 to 64 characters.
labelstringThe name of the action, 1 to 64 characters.
descriptionstringWhat it does, 1 to 280 characters.
kind'flow' | 'seat'Whether the hook acts on a seat.
targetProgramAddressThe protocol's program.
instructionNamestringThe instruction, 1 to 64 characters.
discriminatorHexIts 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).
accountsTemplateAccountSlot[]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).
companionInstructionsoptionalCompanionInstruction[]Up to 8: programId, instructionName (1 to 64), discriminator (at most 8 bytes), position ('before' or 'after') and optional description (up to 240).
mintInAddress | nullThe asset in, or null to leave it open.
mintOutAddress | nullThe asset out, or null to leave it open.
assetInSymboloptionalstring | nullIts symbol, up to 24 characters.
assetOutSymboloptionalstring | nullIts symbol, up to 24 characters.
mintInConstraintoptionalMintConstraintThe constraint on the asset in, used as given: kind 'None', 'Any', 'Sol' or 'Spl' with mint.
mintOutConstraintoptionalMintConstraintThe same for the asset out.
wrapSolInoptionalbooleanWrap SOL in before the call. Default false.
unwrapSolOutoptionalbooleanUnwrap SOL out after the call. Default false.
dataTemplateHexoptionalHexThe data template as stored, at most 256 bytes, used as given.
dataSlotsoptionalOnChainDataSlot[]Up to 16 data slots as stored: offset and len (0 to 256) and kind.
accountSlotsoptionalOnChainAccountSlot[]Up to 48 account slots as stored: kind, isWritable, isSigner and pubkey.
companionsoptionalOnChainCompanion[]Up to 8 companions as stored: programId, discriminatorHex (at most 8 bytes), discLen (0 to 8) and mustPrecede.
formFieldsoptionalHookFormField[]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.

BodyTypeMeaning
authorAddressThe wallet that signs. It becomes the author of the hook.
hookHookDraftThe 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.

FieldTypeMeaning
authorAddressThe author.
hooksAuthorHookFee[]One entry per hook and asset.
hooks[].hookIdstringThe hook.
hooks[].hookAddressAddressThe hook's account.
hooks[].mintAddressThe asset of the fees.
hooks[].assetSymbolstring | nullIts symbol.
hooks[].decimalsintegerIts decimals.
hooks[].claimableAmountBaseUnitsWhat can be claimed now, read from the author's fee account for that asset.
hooks[].totalEarnedAmountBaseUnitsEverything the hook has earned in that asset.
hooks[].lastClaimedAtTimestamp | nullThe last claim.
asOfTimestampWhen 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.

BodyTypeMeaning
hookIdsHookId[]1 to 16 hooks to claim for.
mintoptionalAddressClaim 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:

HTTPJSON-RPC codeWhen
400-32700The body is not JSON
400-32600Not a single JSON-RPC 2.0 request with an id, a method and array params
413-32600The body is too large
400-32601The method is not relayed
200-32601A getProgramAccounts query other than the one relayed
429-32005Over the rate. Retry-After says when to try again
200-32004The API is waiting
502-32603The 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.