Build
API reference
Every route of the Una API, with its parameters, the objects it returns and the errors it raises.
The API serves the exchange as JSON at https://api.una.markets. It reads batches, orders, positions, pairs, prices, solvers and stake, and it builds every transaction a wallet signs. This page is contract version 0.1.9; GET /health reports the version a server runs, and GET /openapi.json returns the same contract as an OpenAPI 3.1 document.
The SDK wraps each route in one typed call.
Conventions
| Type on this page | On the wire |
|---|---|
address | A base58 string of 32 bytes: a wallet, a mint or an account. |
signature | A base58 string of 64 bytes: a transaction signature. |
u64 string, u128 string, i128 string | An integer as a decimal string. Amounts are in atoms, the smallest unit of a token, and SOL amounts are in lamports. Parse them as big integers, since they pass 2^53. |
decimal string | A number formatted for display, such as "162.4". Use the integer field beside it for arithmetic. |
time | An ISO 8601 time in UTC, such as "2026-11-22T09:30:00.000Z". |
hex | Lowercase hexadecimal bytes. |
base64 | Standard base64. |
A field whose name ends in Q64 is a Q64.64 fixed-point number: the integer stands for itself divided by 2^64. Prices are lamports per atom, and a limit is atoms of the buy token per atom of the sell token. A field ending in Bps is in basis points, hundredths of a percent.
Requests are strict: an unknown field in a body or a query is a VALIDATION_ERROR. Responses may gain fields and enum values in later versions, so a client ignores what it does not know.
Pages
A list route returns one page.
Query, on every list route
cursorstring- Where the page starts: the
nextCursorof the page before. Leave it out for the first page. limitinteger, 1 to 100- How many items to return. Default
24.
Every page carries items, asOf and page, a PageInfo.
How a transaction is sent
The API never holds a key. A route that changes something returns an unsigned transaction, the wallet signs it, and the signed bytes go back to the API or straight to the chain.
Build
Call the route for the action, such as
POST /v1/orders/place, with the wallet that will sign. The API builds a v0 transaction, simulates it, and returns a TxBuild. If the simulation fails, the route answers with the error and the program's own error name.Sign
Decode
transactionBase64, sign it with the wallet, and keep the build'sid.Submit
Send the signed bytes to
POST /v1/transactions/submitwith moderelay. If the wallet sent the transaction itself, report its signature with modewallet-sent.Follow
Poll
GET /v1/transactions/{id}untilstatusisconfirmed,finalized,failedorexpired.
Errors
Every failed request answers with one envelope, whatever the route:
error
codestring- The error's code, from the table below.
messagestring- What went wrong, as a sentence.
retryableboolean- Whether the same request can succeed later.
stage"validation" | "auth" | "read" | "upload" | "build" | "wallet" | "co_sign" | "simulation" | "send" | "confirmation"- The step of the flow that failed.
fieldErrorsRecord<string, string[]>, may be absent- For
VALIDATION_ERROR: each rejected field with what is wrong with it. programErrorProgramError, may be absent- The on-chain program that refused the transaction, with its error name and number. See ProgramError.
retryAfterSecondsinteger, may be absent- For
RATE_LIMITED: how long to wait. requestIdstring, may be absent- The id of the request in the API's logs.
Branch on code. message is a sentence fit to show a person.
| Code | HTTP | Raised when |
|---|---|---|
VALIDATION_ERROR | 400 | A path, query or body field is missing, malformed or unknown. fieldErrors names each field. |
UNAUTHORIZED | 401 | The request needs a session it does not carry. |
ORIGIN_NOT_ALLOWED | 403 | A browser request came from an origin the API does not serve. |
NOT_FOUND | 404 | The order, position, stake, token or transaction named in the request does not exist. |
PROGRAM_UNAVAILABLE | 409 | The program is not deployed yet. Every route that builds a transaction raises it while GET /health says waiting. |
CONFIGURATION_REQUIRED | 409 | The action needs a protocol setting that is not set yet. |
IDEMPOTENCY_CONFLICT | 409 | The idempotencyKey was already used with a different build. |
TRANSACTION_EXPIRED | 409 | The build's blockhash expired before the signed transaction arrived. Build again. |
PAYLOAD_TOO_LARGE | 413 | The request body is larger than the API accepts. |
UNSUPPORTED_MEDIA_TYPE | 415 | A body was sent without Content-Type: application/json. |
SIMULATION_FAILED | 422 | The built transaction failed when simulated. programError names the program's error when the program refused it. |
CHAIN_REFUSED | 422 | The chain refused the submitted transaction. programError names the program's error when there is one. |
RATE_LIMITED | 429 | Too many requests. retryAfterSeconds says when to try again. |
INTERNAL_ERROR | 500 | The API failed on its own side. |
UPSTREAM_UNAVAILABLE | 502 | The API could not reach the chain. Retry. |
BATCH_NOT_FOUND | 404 | No batch has that number. |
PAIR_NOT_FOUND | 404 | No pair has that address or slug. |
SOLVER_NOT_FOUND | 404 | No solver has that address or operator. |
BATCH_SEALED | 409 | The action needs an open batch and the batch has sealed. |
ORDER_NOT_CANCELLABLE | 409 | The order's batch has sealed, or the order is already filled, settled or cancelled. |
ORDER_LOCKED | 409 | The order sits in a sealed batch that has not cleared yet, or its batch has cleared and the API has not read the order's fill yet. Either lasts about a second. Retry. |
ORDER_NOT_SETTLEABLE | 409 | The order's batch has not cleared yet, or the order is already settled. |
COOLDOWN_ACTIVE | 409 | The unstake cooldown has not finished. GET /v1/stakes shows the slots left. |
NOTHING_TO_CLAIM | 409 | The position has no fees owed, the stake has no rewards, or the wallet has no unclaimed share of the cover. |
INVALID_TICK_RANGE | 400 | A tick is not a multiple of the pair's tick spacing, or the lower tick is not below the upper. |
INSUFFICIENT_BALANCE | 422 | The wallet holds less than the amount to sell, add or stake, or the stake holds less than the amount to unstake. |
PRICE_OUT_OF_BAND | 422 | A posted price is outside its token's band. |
INSUFFICIENT_BOND | 422 | The solver has less free bond than the batch moves. |
stage is one of validation, auth, read, upload, build, wallet, co_sign, simulation, send, confirmation. When the program refuses a transaction, programError.name is one of the names in the program reference.
Health and protocol
GET /health
Whether the API is serving the program.
Returns HealthResponse. status is waiting until the program is deployed; while it is, list routes return empty lists and every route that builds a transaction answers PROGRAM_UNAVAILABLE.
GET /v1/protocol
The protocol's settings as the program's configuration holds them, and the mints a stake can be in.
Returns ProtocolParams.
GET /v1/live
The market at this moment in one read: the open batch, the last cleared batch with its prices, the recent batches and the protocol settings.
Returns LiveOverview.
Tokens and quotes
GET /v1/tokens
Every listed token with its last proven price and the band the next batch may price it in.
Returns TokensResponse.
GET /v1/wallets/{wallet}/balances
A wallet's SOL and its balance of every listed token.
Path
walletaddressrequired- The wallet to read.
Returns WalletBalancesResponse.
GET /v1/quote
What an order between two tokens would receive at the last proven prices, and a limit to place it with.
Query
sellMintaddressrequired- The token to sell.
buyMintaddressrequired- The token to buy.
amountu64 string, above 0- Atoms of the sell token. With it, the response carries the output estimates.
Returns QuoteResponse. The estimates are null when amount is left out or the clearing fee is not set. A quote is an estimate from the last proven prices: the fill is decided by the batch the order clears in.
Orders
GET /v1/orders
Orders, newest first, filtered by any of the query fields.
Query
cursorstring- Where the page starts: the
nextCursorof the page before. Leave it out for the first page. limitinteger, 1 to 100- How many items to return. Default
24. walletaddress- Only this wallet's orders.
batchIdu64 string- Only orders in this batch.
status"open" | "filled" | "partial" | "rolled" | "expired" | "cancelled" | "settled"- Only orders in this status.
sellMintaddress- Only orders selling this token.
buyMintaddress- Only orders buying this token.
Returns OrdersPage.
GET /v1/orders/{address}
One order by its address.
Path
addressaddressrequired- The order's address.
Returns Order.
POST /v1/orders/place
Builds the transaction that places an order in the open batch. The sell amount moves from the wallet to the token's vault when it lands.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
sellMintaddressrequired- The token to sell. It must differ from
buyMint. buyMintaddressrequired- The token to buy.
amountu64 string, above 0required- Atoms of the sell token.
limitQ64u128 string, above 0required- The limit: least atoms of the buy token per atom of the sell token, as Q64.64.
expiryBatchIdu64 string, above 0- The last batch the order may clear in. Left out, the API sets it about five minutes of batches ahead.
Returns PlaceOrderBuild. If that batch seals before the transaction lands, the order is placed in the batch open at that moment, so the order's batch can be later than batchId. Read it from the order.
POST /v1/orders/{address}/cancel
Builds the transaction that takes an order back. While the order's batch is open it cancels the order and returns its sell amount. After that batch has cleared it settles the order first and cancels whatever remainder moved on into the open batch.
Path
addressaddressrequired- The order's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
Returns CancelOrderBuild. Its outcome says which of these the transaction does. While the order's batch is sealed and not yet cleared the route answers ORDER_LOCKED.
POST /v1/orders/{address}/settle
Builds the transaction that settles an order after its batch cleared: the bought tokens go to the owner, and the remainder returns or joins the open batch. Anyone may send it; the keeper does by default.
Path
addressaddressrequired- The order's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
Returns TxBuild.
Pairs and positions
GET /v1/pairs
Every pair with its fee, its price and its liquidity.
Returns PairsResponse.
GET /v1/pairs/{pair}
One pair with its liquidity tick by tick.
Path
pairstringrequired- The pair's address or slug.
Returns PairDetail.
GET /v1/pairs/{pair}/candles
Price candles for a pair, built only from proven batches.
Path
pairstringrequired- The pair's address or slug.
Query
interval"S1" | "M1" | "M5" | "M15" | "H1"- The length of a candle. Default
M5. fromtime- Only candles starting at or after this time.
totime- Only candles starting before this time.
limitinteger, 1 to 500- How many candles to return, 1 to 500. Default
120.
Returns CandlesResponse.
GET /v1/pairs/{pair}/quote-liquidity
The token amounts a position over a tick range takes at the pair's current price. Give one amount and it returns the other.
Path
pairstringrequired- The pair's address or slug.
Query
tickLowerintegerrequired- The lower tick of the range.
tickUpperintegerrequired- The upper tick of the range.
amountXu64 string- Atoms of the first token to place. Give this or
amountY. amountYu64 string- Atoms of the second token to place.
Returns LiquidityQuote.
GET /v1/positions
Liquidity positions, filtered by wallet or pair.
Query
cursorstring- Where the page starts: the
nextCursorof the page before. Leave it out for the first page. limitinteger, 1 to 100- How many items to return. Default
24. walletaddress- Only this wallet's positions.
pairstring- Only positions on this pair, by address or slug.
Returns PositionsPage.
POST /v1/pairs/{pair}/liquidity/add
Builds the transaction that places liquidity on a pair over a tick range and creates the position.
Path
pairstringrequired- The pair's address or slug.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
tickLowerintegerrequired- The lower tick of the range.
tickUpperintegerrequired- The upper tick of the range.
amountXu64 stringrequired- The most atoms of the first token to place.
amountYu64 stringrequired- The most atoms of the second token to place. One of the two may be
"0"when the range is out of range. liquidityDeltau128 string, above 0- The liquidity to add, from
quote-liquidity. Left out, the API computes it from the amounts.
Returns AddLiquidityBuild.
POST /v1/positions/{address}/remove
Builds the transaction that removes liquidity from a position and pays its tokens to the owner.
Path
addressaddressrequired- The position's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
liquidityDeltau128 string, above 0required- The liquidity to remove. The position's whole
liquidityremoves all of it. minAmountXu64 string- The least atoms of the first token to accept. Below it the transaction fails with
SlippageExceeded. minAmountYu64 string- The least atoms of the second token to accept.
Returns TxBuild.
POST /v1/positions/{address}/collect
Builds the transaction that pays a position's earned fees to its owner.
Path
addressaddressrequired- The position's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
Returns TxBuild.
POST /v1/positions/{address}/settle
Builds the transaction that pays a position's earnings to its owner. Anyone may send it; the payment goes to the owner.
Path
addressaddressrequired- The position's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
Returns TxBuild.
Solvers and stake
GET /v1/solvers
Every solver with its stake, its bond in use, its commission and what it has paid its stakers.
Query
cursorstring- Where the page starts: the
nextCursorof the page before. Leave it out for the first page. limitinteger, 1 to 100- How many items to return. Default
24.
Returns SolversPage.
GET /v1/solvers/{address}
One solver with its recent batches and its slashes.
Path
addressaddressrequired- The solver's account or its operator's wallet.
Returns SolverDetail.
GET /v1/stakes
A wallet's stakes with their rewards and any unstake in progress.
Query
cursorstring- Where the page starts: the
nextCursorof the page before. Leave it out for the first page. limitinteger, 1 to 100- How many items to return. Default
24. walletaddressrequired- The wallet whose stakes to return.
solveraddress- Only stakes behind this solver.
Returns StakesPage.
POST /v1/stakes/deposit
Builds the transaction that stakes SOL or a listed liquid staking token behind a solver.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
solveraddressrequired- The solver to stake behind.
bondMintaddressrequired- The mint to stake: wSOL or a listed liquid staking token.
amountu64 string, above 0required- Atoms of that mint.
Returns TxBuild.
POST /v1/stakes/{address}/unstake
Builds the transaction that moves part or all of a stake into its cooldown.
Path
addressaddressrequired- The stake's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
amountu64 string, above 0required- Atoms of the bond mint to unstake. The API converts them to shares of the solver's pool.
Returns TxBuild.
POST /v1/stakes/{address}/withdraw
Builds the transaction that returns an unstaked deposit once its cooldown has passed.
Path
addressaddressrequired- The stake's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
Returns TxBuild.
POST /v1/stakes/{address}/claim
Builds the transaction that pays a stake's rewards to its owner.
Path
addressaddressrequired- The stake's address.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
Returns TxBuild.
POST /v1/solvers/{address}/commission/claim
Builds the transaction that pays a solver's accrued commission to its operator, in every token it has accrued in or in one.
Path
addressaddressrequired- The solver's account or its operator's wallet.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
tokenIndexinteger- Claim only this token. Left out, every token with commission accrued is claimed in one transaction.
Returns TxBuild.
Batches and cover
GET /v1/batches
Batches, newest first.
Query
cursorstring- Where the page starts: the
nextCursorof the page before. Leave it out for the first page. limitinteger, 1 to 100- How many items to return. Default
24. status"open" | "sealed" | "cleared" | "proven" | "slashed" | "rolled"- Only batches in this status.
solveraddress- Only batches this solver cleared.
Returns BatchesPage.
GET /v1/batches/{id}
One batch: its hashes, its prices, its fill fractions, its solver and bond, its proof or its slash and cover. Pass wallet to get that wallet's orders in the batch and its share of the cover.
Path
idu64 stringrequired- The batch's number.
Query
walletaddress- A wallet whose orders and cover share to include.
Returns BatchDetail.
GET /v1/batches/{id}/input
Every record folded into a batch's input hash, in the order the program folded them. Hashing them in order reproduces inputHash.
Path
idu64 stringrequired- The batch's number.
Returns BatchInputResponse.
GET /v1/batches/{id}/state
The state a cleared batch was solved against and the result posted for it, as its solver published them. With the input records they are everything the guest program reads, so anyone can run the check on the batch.
Path
idu64 stringrequired- The batch's number.
Returns BatchStateResponse. It answers NOT_FOUND until the batch's solver has published them.
POST /v1/batches/{id}/state
Publishes the state and result of a cleared batch. The API hashes both and accepts them only when the hashes equal the batch's state_hash and result_hash on chain, so what it serves is what the proof commits to. The solver node sends this after each clearing.
Path
idu64 stringrequired- The batch's number.
Body
stateBatchStateDatarequired- The state the clearing was solved against. See BatchStateData.
resultBatchResultDatarequired- The clearing posted. See BatchResultData.
Returns BatchStateResponse.
POST /v1/batches/{id}/cover/claim
Builds the transaction that pays a wallet its share of a slashed batch's cover.
Path
idu64 stringrequired- The batch's number.
Body
walletaddressrequired- The wallet that signs the transaction and pays its fee.
participantaddress- The order or position to claim with. Left out, the API picks one of the wallet's that has not claimed.
Returns TxBuild.
Transactions
POST /v1/transactions/submit
Hands a signed transaction to the API to send, or reports the signature of one the wallet sent itself.
Body when mode is relay
mode"relay"required- The API sends the transaction.
buildIdstringrequired- The
idof the build that was signed. signedTransactionBase64base64required- The transaction as the wallet returned it, signed.
idempotencyKeystringrequired- A key you choose, unique to this submission, such as a UUID.
Body when mode is wallet-sent
mode"wallet-sent"required- The wallet sent the transaction itself.
buildIdstringrequired- The
idof the build that was signed. signaturesignaturerequired- The signature the wallet returned.
idempotencyKeystringrequired- A key you choose, unique to this submission.
Returns TxStatus. Sending the same idempotencyKey again returns the same status and sends nothing twice.
GET /v1/transactions/{id}
Where a submitted transaction stands.
Path
idstringrequired- The build's id.
Returns TxStatus.
The batch stream
GET /v1/batches/stream
A server-sent event stream of batches as they change. Open it with EventSource. Each event is named by its type, so listen with addEventListener(type, ...), and its data is this object as JSON:
Event
type"ready" | "batch" | "resync"- What happened.
idstring- The event's id.
timestamptime- When it was sent.
dataany- The event's payload, by type as below.
type | data | Sent |
|---|---|---|
ready | status, openBatchId and latestBatch, a BatchSummary or null | Once, when the stream opens. |
batch | A BatchSummary | Each time a batch changes: an order joins it, it seals, clears, is proven, slashed or rolled. |
resync | Nothing to read | When the client has fallen behind. Fetch GET /v1/live or GET /v1/batches again and carry on. |
Objects
Every object a route returns, in the order the routes above reach them.
ProgramError
ProgramError
programIdaddress- The program that raised the error.
namestring- The error's name in that program.
numberinteger, may be absent- The error's number in that program.
HealthResponse
HealthResponse
status"live" | "waiting"livewhen the program is deployed and the API is serving it,waitingbefore that.mode"fixture" | "chain"chainwhen the API reads the program.programIdaddress- The address of the
unaprogram. cluster"localnet" | "devnet" | "mainnet"- The Solana cluster the API serves.
contractVersionstring- The version of this contract the server runs.
currentSlotu64 string | null- The slot the API last saw, or
nullwhile it is waiting. asOftime- When the API read this.
ProtocolParams
ProtocolParams
programIdaddress- The address of the
unaprogram. feeRecipientaddress- The address that receives the protocol share of the clearing fee.
unaMintaddress | null- The mint of UNA, or
nulluntil it exists. slotMsinteger- The length of a slot in milliseconds.
batchWindowSlotsinteger- The batch window, in slots.
clearingTimeoutSlotsinteger | null- How long a sealed batch waits for a clearing before it rolls, in slots.
proofWindowSlotsinteger- The proof window, in slots.
unstakeCooldownSlotsinteger- The unstake cooldown, in slots.
bandBpsinteger, 0 to 10000 | null- How far a batch may price a token from its last proven price.
clearingFeeBpsinteger, 0 to 10000 | null- The clearing fee, taken from each filled order's output.
nulluntil it is set. protocolFeeShareBpsinteger, 0 to 10000 | null- The share of the clearing fee that goes to the fee recipient.
nulluntil it is set. bondMintsBondMint[]- The mints a stake can be in, each with its rate in SOL. See BondMint.
LiveOverview
LiveOverview
status"live" | "waiting"- The same as
GET /health. currentSlotu64 string- The slot the API last saw.
slotMsinteger- The length of a slot in milliseconds.
protocolProtocolParams- The protocol settings. See ProtocolParams.
openBatchOpenBatchSummary | null- The batch collecting orders now, or
nullwhile waiting. See OpenBatchSummary. lastClearedBatchBatchSummary with prices | null- The most recent batch with a clearing, as a BatchSummary with its
prices, an array of BatchTokenPrice. totalBondLockedLamportsu64 string- The bond locked behind all cleared batches awaiting proof, across solvers.
recentBatchesBatchSummary[]- The latest batches, newest first. See BatchSummary.
asOftime- When the API read this.
TokensResponse
TokensResponse
itemsToken[]- Every listed token. See Token.
asOftime- When the API read this.
WalletBalancesResponse
WalletBalancesResponse
walletaddress- The wallet read.
solLamportsu64 string- The wallet's SOL, in lamports.
itemsWalletTokenBalance[]- One entry per listed token. See WalletTokenBalance.
asOftime- When the API read this.
QuoteResponse
QuoteResponse
sellTokenTokenRef- The token sold. See TokenRef.
buyTokenTokenRef- The token bought. See TokenRef.
lastPriceRatioQ64u128 string- The rate at the last proven prices: atoms of the buy token per atom of the sell token.
lastPriceUidecimal string- The same rate in whole tokens.
suggestedLimitQ64u128 string- A limit to place the order with, set from the last proven rate. Pass it as
limitQ64. suggestedLimitUidecimal string- The same limit in whole tokens.
estimatedGrossOutu64 string | null- Atoms of the buy token at the last proven rate, before the clearing fee.
estimatedFeeu64 string | null- The clearing fee on that, in atoms of the buy token.
estimatedNetOutu64 string | null- What the order would receive.
clearingFeeBpsinteger, 0 to 10000 | null- The clearing fee the estimate used.
openBatchIdu64 string | null- The batch an order placed now would join.
slotsLeftinteger | null- Slots until the batch's window ends, or
nullonce it has sealed. estimatedEndAttime | null- When the window is expected to end, from the slots left and the slot time.
asOftime- When the API read this.
OrdersPage
OrdersPage
Order
Order
addressaddress- The order's account.
owneraddress- The wallet that owns it.
batchIdu64 string- The batch the order is in now.
originBatchIdu64 string- The batch the order was first placed in. It differs from
batchIdonce a remainder has moved on. expiryBatchIdu64 string- The last batch the order may clear in.
sellTokenTokenRef- The token sold. See TokenRef.
buyTokenTokenRef- The token bought. See TokenRef.
amountu64 string- Atoms of the sell token the order offers.
filledAmountu64 string- Atoms of the sell token filled.
remainderAmountu64 string- Atoms of the sell token not filled.
receivedAmountu64 string- Atoms of the buy token the owner receives, after the clearing fee.
feeAmountu64 string- The clearing fee, in atoms of the buy token.
limitQ64u128 string- The limit: least atoms of the buy token per atom of the sell token.
limitUidecimal string- The limit in whole tokens.
clearedPriceUidecimal string | null- The rate the batch gave this direction, in whole tokens, or
nullbefore it clears. fillFractionBpsinteger, 0 to 10000- The part of the order filled.
status"open" | "filled" | "partial" | "rolled" | "expired" | "cancelled" | "settled"openin a batch's window,filledorpartialonce cleared,rolledwhen its batch rolled,settledonce paid out,expiredorcancelledwhen returned.cancellableboolean- Whether
cancelwould succeed now. settleableboolean- Whether
settlewould succeed now. placedAttime- When the order was placed.
settledAttime | null- When it was settled.
placeSignaturesignature- The transaction that placed it.
settleSignaturesignature | null- The transaction that settled it.
PlaceOrderBuild
PlaceOrderBuild
idstring- The build's id. Pass it back as
buildIdwhen submitting. transactionBase64base64- The unsigned v0 transaction.
blockhashbase58, 32 bytes- The blockhash the transaction was built on.
lastValidBlockHeightinteger- The block height after which the transaction can no longer land.
cosignedboolean- Whether the API adds a signature of its own after the wallet's.
orderAddressaddress- The address the order will have once the transaction lands.
batchIdu64 string- The open batch the order was built for.
CancelOrderBuild
CancelOrderBuild
idstring- The build's id. Pass it back as
buildIdwhen submitting. transactionBase64base64- The unsigned v0 transaction.
blockhashbase58, 32 bytes- The blockhash the transaction was built on.
lastValidBlockHeightinteger- The block height after which the transaction can no longer land.
cosignedboolean- Whether the API adds a signature of its own after the wallet's.
outcome"cancelled" | "filled" | "expired"- What the transaction does.
cancelled: it cancels the order, or settles it and cancels the remainder that moved into the open batch.filled: the batch filled the order, in full or with a remainder too small to move on, and the transaction only settles it.expired: the order is past its expiry and the transaction only settles it, returning any remainder.
TxBuild
TxBuild
idstring- The build's id. Pass it back as
buildIdwhen submitting. transactionBase64base64- The unsigned v0 transaction.
blockhashbase58, 32 bytes- The blockhash the transaction was built on.
lastValidBlockHeightinteger- The block height after which the transaction can no longer land.
cosignedboolean- Whether the API adds a signature of its own after the wallet's. When
true, submit with moderelay.
PairsResponse
PairsResponse
itemsPairSummary[]- Every pair. See PairSummary.
asOftime- When the API read this.
PairDetail
PairDetail
addressaddress- The pair's account.
indexinteger- The pair's index in the program.
slugstring- The pair's name in addresses.
tokenXTokenRef- The pair's first token, the one with the lower index. See TokenRef.
tokenYTokenRef- The pair's second token. The pair's price is atoms of this token per atom of the first. See TokenRef.
feeBpsinteger, 0 to 10000- The pair's liquidity fee.
tickSpacinginteger- Ticks of a range must be multiples of this.
currentTickinteger- The tick the pair's price is in.
sqrtPriceQ64u128 string- The square root of the pair's price, as Q64.64.
currentPriceUidecimal string- The pair's price in whole tokens of the second per whole token of the first.
activeLiquidityu128 string- The liquidity in range at the current price.
tvlLamportsu64 string- The value of all liquidity on the pair, at last proven prices.
volume24hLamportsu64 string- What traded against the pair's liquidity in the last 24 hours.
fees24hLamportsu64 string- The liquidity fees the pair's positions earned in the last 24 hours.
lastProvenBatchIdu64 string | null- The last proven batch that moved the pair.
ticksTickLiquidity[]- The initialized ticks, lowest first. See TickLiquidity.
asOftime- When the API read this.
CandlesResponse
CandlesResponse
pairaddress- The pair's account.
slugstring- The pair's slug.
interval"S1" | "M1" | "M5" | "M15" | "H1"- The length of a candle.
itemsCandle[]- The candles, oldest first. See Candle.
asOftime- When the API read this.
LiquidityQuote
LiquidityQuote
pairaddress- The pair's account.
tickLowerinteger- The lower tick of the range.
tickUpperinteger- The upper tick of the range.
currentTickinteger- The tick the pair's price is in.
sqrtPriceQ64u128 string- The square root of the pair's price, as Q64.64.
priceLowerUidecimal string- The price at the lower tick, in whole tokens.
priceUpperUidecimal string- The price at the upper tick, in whole tokens.
inRangeboolean- Whether the pair's price is inside the range.
amountXu64 string- Atoms of the first token the position takes.
amountYu64 string- Atoms of the second token the position takes.
liquidityDeltau128 string- The liquidity those amounts make over the range. Pass it to
add. asOftime- When the API read this.
PositionsPage
PositionsPage
itemsLiquidityPosition[]- The items of this page. See LiquidityPosition.
pagePageInfo- Where this page sits in the list. See PageInfo.
asOftime- When the API read this.
AddLiquidityBuild
AddLiquidityBuild
idstring- The build's id. Pass it back as
buildIdwhen submitting. transactionBase64base64- The unsigned v0 transaction.
blockhashbase58, 32 bytes- The blockhash the transaction was built on.
lastValidBlockHeightinteger- The block height after which the transaction can no longer land.
cosignedboolean- Whether the API adds a signature of its own after the wallet's.
positionAddressaddress- The address the position will have once the transaction lands.
SolversPage
SolversPage
itemsSolverSummary[]- The items of this page. See SolverSummary.
pagePageInfo- Where this page sits in the list. See PageInfo.
asOftime- When the API read this.
SolverDetail
SolverDetail
addressaddress- The solver's account.
operatoraddress- The wallet that runs the solver.
namestring | null- The solver's name, if it has one.
commissionBpsinteger, 0 to 10000- The part of its clearing fees the operator keeps.
totalStakeLamportsu64 string- All stake behind the solver, valued in lamports.
bondFreeLamportsu64 string- Stake free to back a new batch.
bondLockedLamportsu64 string- Stake locked behind cleared batches awaiting proof.
batchesClearedinteger- Batches the solver has cleared.
batchesProveninteger- Of those, the ones it has proven.
slashCountinteger- How many of its batches were slashed.
feesPaidToStakersLamportsu64 string- Clearing fees paid to its stakers so far.
operatorCommissionAccruedCommission[]- Commission accrued and not yet claimed, one entry per token. See AccruedCommission.
medianProofTimeMsinteger | null- Its median time from clearing to proof.
activeboolean- Whether the solver is registered and able to clear.
registeredAttime- When it registered.
recentBatchesBatchSummary[]- The latest batches it cleared, newest first. See BatchSummary.
slashesSolverSlash[]- Every slash against it. See SolverSlash.
acceptedBondMintsBondMint[]- The mints a stake behind it can be in. See BondMint.
asOftime- When the API read this.
StakesPage
StakesPage
itemsStakePosition[]- The items of this page. See StakePosition.
pagePageInfo- Where this page sits in the list. See PageInfo.
asOftime- When the API read this.
BatchesPage
BatchesPage
itemsBatchSummary[]- The items of this page. See BatchSummary.
pagePageInfo- Where this page sits in the list. See PageInfo.
asOftime- When the API read this.
BatchDetail
BatchDetail
batchIdu64 string- The batch's number.
addressaddress- The batch's account.
status"open" | "sealed" | "cleared" | "proven" | "slashed" | "rolled"open,sealed,cleared,proven,slashedorrolled.openedAttime- When the window opened.
sealedAttime | null- When it sealed.
clearedAttime | null- When a solver cleared it.
provenAttime | null- When its proof verified.
slashedAttime | null- When it was slashed.
startSlotu64 string- The slot the window opened at.
sealSlotu64 string- The slot the window ends at.
clearSlotu64 string | null- The slot the clearing landed in.
proofDeadlineSlotu64 string | null- The last slot a proof may land in.
proofDeadlineAttime | null- That slot as a time.
volumeLamportsu64 string- What the batch's fills moved, valued at its cleared prices.
tokensPricedinteger- How many tokens the clearing priced.
orderCountinteger- Orders in the batch.
fillsCountinteger- Orders that filled, in full or in part.
solveraddress | null- The solver that cleared it, or
nullbefore clearing. solverNamestring | null- That solver's name, if it has one.
bondLockedLamportsu64 string- The bond locked behind the batch: its value moved.
proofTimeMsinteger | null- The time from clearing to proof, in milliseconds.
proofSignaturesignature | null- The
prove_batchtransaction. slashSignaturesignature | null- The
slash_batchtransaction. slotsLeftinteger | null- Slots until the batch's window ends, or
nullonce it has sealed. estimatedEndAttime | null- When the window is expected to end, from the slots left and the slot time.
inputHashhex, 32 bytes- The running hash of every order placed in or cancelled from the batch.
stateHashhex, 32 bytes | null- The hash of the state the clearing was solved against.
resultHashhex, 32 bytes | null- The hash of the posted prices, fees and fill fractions.
publicValuesHexhex | null- The 104 bytes the proof commits to: the batch number and the three hashes.
pricesBatchTokenPrice[]- The price vector, one entry per token in the batch. See BatchTokenPrice.
fillsBatchFillFraction[]- The fill fractions of the rationed directions. See BatchFillFraction.
clearSignaturesignature | null- The
clear_batchtransaction. coverBatchCover | null- The cover, when the batch was slashed. See BatchCover.
walletOrdersOrder[]- The orders of the
walletin the query. Empty without one. See Order. asOftime- When the API read this.
BatchInputResponse
BatchInputResponse
batchIdu64 string- The batch's number.
inputHashhex, 32 bytes- The batch's input hash on chain.
recordsBatchInputRecord[]- The records, in fold order. See BatchInputRecord.
asOftime- When the API read this.
BatchStateResponse
BatchStateResponse
batchIdu64 string- The batch's number.
stateHashhex, 32 bytes- The hash of
state, equal to the batch's on chain. resultHashhex, 32 bytes- The hash of
result, equal to the batch's on chain. stateBatchStateData- The state the clearing was solved against. See BatchStateData.
resultBatchResultData- The clearing posted. See BatchResultData.
asOftime- When the API read this.
BatchStateData
BatchStateData
batchIdu64 string- The batch's number.
bandBpsinteger, 0 to 10000- The price band the batch was cleared under.
clearingFeeBpsinteger, 0 to 10000- The clearing fee rate the batch was cleared with.
tokensBatchStateToken[]- The batch tokens, ascending by index. See BatchStateToken.
pairsBatchStatePair[]- The batch pairs as they stood before the clearing moved them, ascending by index. See BatchStatePair.
BatchResultData
BatchResultData
batchIdu64 string- The batch's number.
pricesBatchResultPrice[]- One entry per batch token, ascending by index. See BatchResultPrice.
fillsBatchResultFill[]- The fill fractions of the rationed directions. See BatchResultFill.
TxStatus
TxStatus
idstring- The build's id.
status"submitted" | "unconfirmed" | "confirmed" | "finalized" | "failed" | "expired"submittedandunconfirmedare still in flight.confirmed,finalized,failedandexpiredare final.signaturesignature, may be absent- The transaction's signature, once it is known.
errorTxFailure, may be absent- Why it failed, when
statusisfailedorexpired. See TxFailure.
BatchSummary
BatchSummary
batchIdu64 string- The batch's number.
addressaddress- The batch's account.
status"open" | "sealed" | "cleared" | "proven" | "slashed" | "rolled"open,sealed,cleared,proven,slashedorrolled.openedAttime- When the window opened.
sealedAttime | null- When it sealed.
clearedAttime | null- When a solver cleared it.
provenAttime | null- When its proof verified.
slashedAttime | null- When it was slashed.
startSlotu64 string- The slot the window opened at.
sealSlotu64 string- The slot the window ends at.
clearSlotu64 string | null- The slot the clearing landed in.
proofDeadlineSlotu64 string | null- The last slot a proof may land in.
proofDeadlineAttime | null- That slot as a time.
volumeLamportsu64 string- What the batch's fills moved, valued at its cleared prices.
tokensPricedinteger- How many tokens the clearing priced.
orderCountinteger- Orders in the batch.
fillsCountinteger- Orders that filled, in full or in part.
solveraddress | null- The solver that cleared it, or
nullbefore clearing. solverNamestring | null- That solver's name, if it has one.
bondLockedLamportsu64 string- The bond locked behind the batch: its value moved.
"0"before clearing. proofTimeMsinteger | null- The time from clearing to proof, in milliseconds.
proofSignaturesignature | null- The
prove_batchtransaction. slashSignaturesignature | null- The
slash_batchtransaction.
BondMint
BondMint
mintaddress- The token's mint.
symbolstring- The token's symbol.
namestring- The token's name.
decimalsinteger, 0 to 18- How many decimals the token has. One whole token is 10 to that power in atoms.
stakePooladdress | null- The stake pool that issues the token, or
nullfor SOL. solPerTokenQ64u128 string- What one atom of the token counts as in lamports of bond, as Q64.64. It is read from the stake pool.
solPerTokenUidecimal string- The same rate in SOL per whole token.
OpenBatchSummary
OpenBatchSummary
batchIdu64 string- The batch's number.
addressaddress- The batch's account.
status"open" | "sealed" | "cleared" | "proven" | "slashed" | "rolled"- Always
open. startSlotu64 string- The slot the window opened at.
sealSlotu64 string- The slot the window ends at.
slotsLeftinteger- Slots until the window ends.
estimatedEndAttime- When the window is expected to end, from the slots left and the slot time.
orderCountinteger- Orders in the batch so far.
tokensTokenRef[]- The tokens those orders sell and buy. See TokenRef.
offeredValueLamportsu64 string- What the orders offer, valued at last proven prices.
Token
Token
indexinteger- The token's index in the program. wSOL is 0.
mintaddress- The token's mint.
symbolstring- The token's symbol.
namestring- The token's name.
decimalsinteger, 0 to 18- How many decimals the token has. One whole token is 10 to that power in atoms.
vaultaddress- The program's vault for this token. Sell amounts and liquidity rest here.
tokenProgramaddress- The token program that owns the mint: SPL Token or Token-2022.
lastPriceQ64u128 string- The last proven price, in lamports per atom, as Q64.64.
lastPriceSoldecimal string- The last proven price in SOL per whole token.
lastProvenBatchIdu64 string | null- The batch that proved that price, or
nullif no batch has priced the token yet. lastProvenAttime | null- When that batch was proven.
bandLoQ64u128 string | null- The lowest price the next batch may give the token, or
nullwhile the band is not set. bandHiQ64u128 string | null- The highest price the next batch may give the token.
isBondMintboolean- Whether a stake can be made in this token.
WalletTokenBalance
WalletTokenBalance
tokenIndexinteger- The token's index in the program.
mintaddress- The token's mint.
symbolstring- The token's symbol.
decimalsinteger, 0 to 18- How many decimals the token has. One whole token is 10 to that power in atoms.
amountu64 string- The balance, in atoms.
uiAmountdecimal string- The balance in whole tokens.
lastPriceQ64u128 string- The token's last proven price.
TokenRef
TokenRef
indexinteger- The token's index in the program. wSOL is 0.
mintaddress- The token's mint.
symbolstring- The token's symbol.
namestring- The token's name.
decimalsinteger, 0 to 18- How many decimals the token has. One whole token is 10 to that power in atoms.
PageInfo
PageInfo
nextCursorstring | null- The
cursorof the next page, ornullon the last one. hasMoreboolean- Whether another page follows.
PairSummary
PairSummary
addressaddress- The pair's account.
indexinteger- The pair's index in the program.
slugstring- The pair's name in addresses, such as
sol-usdc. tokenXTokenRef- The pair's first token, the one with the lower index. See TokenRef.
tokenYTokenRef- The pair's second token. The pair's price is atoms of this token per atom of the first. See TokenRef.
feeBpsinteger, 0 to 10000- The pair's liquidity fee.
tickSpacinginteger- Ticks of a range must be multiples of this.
currentTickinteger- The tick the pair's price is in.
sqrtPriceQ64u128 string- The square root of the pair's price, as Q64.64.
currentPriceUidecimal string- The pair's price in whole tokens of the second per whole token of the first.
activeLiquidityu128 string- The liquidity in range at the current price.
tvlLamportsu64 string- The value of all liquidity on the pair, at last proven prices.
volume24hLamportsu64 string- What traded against the pair's liquidity in the last 24 hours.
fees24hLamportsu64 string- The liquidity fees the pair's positions earned in the last 24 hours.
lastProvenBatchIdu64 string | null- The last proven batch that moved the pair.
TickLiquidity
TickLiquidity
tickinteger- The tick.
priceUidecimal string- The price at the tick, in whole tokens.
liquidityNeti128 string- The change in active liquidity when the price crosses the tick upward.
liquidityActiveu128 string- The liquidity active from this tick to the next.
Candle
Candle
startAttime- When the candle starts.
opendecimal string- The pair's price in the first proven batch of the candle.
highdecimal string- The highest proven price.
lowdecimal string- The lowest proven price.
closedecimal string- The price in the last proven batch of the candle.
volumeXu64 string- Atoms of the first token traded.
volumeYu64 string- Atoms of the second token traded.
volumeLamportsu64 string- The volume valued in lamports.
batchCountinteger- How many proven batches the candle holds.
LiquidityPosition
LiquidityPosition
addressaddress- The position's account.
owneraddress- The wallet that owns it.
pairAddressaddress- The pair's account.
pairSlugstring- The pair's slug.
tokenXTokenRef- The pair's first token, the one with the lower index. See TokenRef.
tokenYTokenRef- The pair's second token. The pair's price is atoms of this token per atom of the first. See TokenRef.
tickLowerinteger- The lower tick of the range.
tickUpperinteger- The upper tick of the range.
priceLowerUidecimal string- The price at the lower tick, in whole tokens.
priceUpperUidecimal string- The price at the upper tick, in whole tokens.
currentPriceUidecimal string- The pair's price in whole tokens of the second per whole token of the first.
inRangeboolean- Whether the pair's price is inside the range.
liquidityu128 string- The position's liquidity.
amountXu64 string- Atoms of the first token the position holds at the current price.
amountYu64 string- Atoms of the second token it holds.
feesOwedXu64 string- Earned and not yet collected, in atoms of the first token.
feesOwedYu64 string- Earned and not yet collected, in atoms of the second token.
surplusEarnedXu64 string- The part of those earnings that is surplus from trading at the cleared price, in the first token.
surplusEarnedYu64 string- The same in the second token.
updatedAttime- When the position last changed.
SolverSummary
SolverSummary
addressaddress- The solver's account.
operatoraddress- The wallet that runs the solver.
namestring | null- The solver's name, if it has one.
commissionBpsinteger, 0 to 10000- The part of its clearing fees the operator keeps.
totalStakeLamportsu64 string- All stake behind the solver, valued in lamports.
bondFreeLamportsu64 string- Stake free to back a new batch.
bondLockedLamportsu64 string- Stake locked behind cleared batches awaiting proof.
batchesClearedinteger- Batches the solver has cleared.
batchesProveninteger- Of those, the ones it has proven.
slashCountinteger- How many of its batches were slashed.
feesPaidToStakersLamportsu64 string- Clearing fees paid to its stakers so far.
operatorCommissionAccruedCommission[]- Commission accrued and not yet claimed, one entry per token. See AccruedCommission.
medianProofTimeMsinteger | null- Its median time from clearing to proof.
activeboolean- Whether the solver is registered and able to clear.
registeredAttime- When it registered.
AccruedCommission
AccruedCommission
tokenIndexinteger- The token's index in the program.
mintaddress- The token's mint.
symbolstring- The token's symbol.
decimalsinteger, 0 to 18- How many decimals the token has. One whole token is 10 to that power in atoms.
amountu64 string- Atoms of the token accrued.
SolverSlash
SolverSlash
batchIdu64 string- The slashed batch.
slashedAttime- When it was slashed.
amountLamportsu64 string- The bond that moved to the batch's cover.
slashSignaturesignature- The
slash_batchtransaction.
StakePosition
StakePosition
addressaddress- The stake's account.
owneraddress- The wallet that owns it.
solverAddressaddress- The solver the stake is behind.
solverOperatoraddress- That solver's operator.
solverNamestring | null- That solver's name, if it has one.
bondMintaddress- The mint the stake is in.
bondSymbolstring- Its symbol.
bondDecimalsinteger, 0 to 18- Its decimals.
sharesu64 string- The stake's shares of the solver's vault.
stakedAmountu64 string- What those shares are worth now, in atoms of the bond mint.
stakedLamportsu64 string- The same, valued in lamports.
rewardsClaimableLamportsu64 string- Rewards earned and not yet claimed.
slashedLamportsu64 string- What slashes have taken from this stake.
status"staked" | "unstaking" | "withdrawable"staked,unstakingduring the cooldown, orwithdrawableafter it.unstakeRequestUnstakeRequest | null- The unstake in progress, if there is one. See UnstakeRequest.
BatchTokenPrice
BatchTokenPrice
tokenIndexinteger- The token's index in the program.
mintaddress- The token's mint.
symbolstring- The token's symbol.
decimalsinteger, 0 to 18- How many decimals the token has. One whole token is 10 to that power in atoms.
priceQ64u128 string- The token's cleared price, in lamports per atom, as Q64.64.
priceSoldecimal string- The same price in SOL per whole token.
feeAmountu64 string- The clearing fee the batch's buyers of this token paid, in its atoms.
offeredAmountu64 string- The total of order amounts selling this token in the batch.
BatchFillFraction
BatchFillFraction
sellTokenIndexinteger- The index of the token the direction sells.
sellSymbolstring- Its symbol.
buyTokenIndexinteger- The index of the token the direction buys.
buySymbolstring- Its symbol.
phiQ63u64 string- The fill fraction out of
FILL_ONE, 2^63. fillPercentdecimal string- The same fraction as a percentage.
BatchCover
BatchCover
addressaddress- The cover's account.
totalLamportsu64 string- The bond that moved to the cover.
claimedLamportsu64 string- What has been claimed.
remainingLamportsu64 string- What is left to claim.
walletClaimableLamportsu64 string | null- The share of the
walletin the query, ornullwithout one. walletClaimedboolean- Whether that wallet has claimed.
participantsCoverParticipant[], may be absent- With a
walletin the query: each of its orders and positions in the batch, with its share. See CoverParticipant.
BatchInputRecord
BatchInputRecord when type is place
type"place"- An order was placed in the batch, or its remainder moved into it.
orderaddress- The order's address.
sellTokeninteger- The index of the token sold.
buyTokeninteger- The index of the token bought.
amountu64 string- Atoms of the sell token.
limitQ64u128 string- The order's limit.
slotu64 string- The slot of the transaction that folded the record.
txIndexinteger- That transaction's position in its block.
ixIndexinteger- The instruction's position in the transaction.
signaturesignature- The transaction.
BatchInputRecord when type is cancel
type"cancel"- An order was cancelled before the batch sealed.
orderaddress- The order's address.
slotu64 string- The slot of the transaction that folded the record.
txIndexinteger- That transaction's position in its block.
ixIndexinteger- The instruction's position in the transaction.
signaturesignature- The transaction.
BatchStateToken
BatchStateToken
indexinteger- The token's index.
lastPriceQ64u128 string- The token's last proven price before the batch.
BatchStatePair
BatchStatePair
pairIndexinteger- The pair's index.
tokenXinteger- The index of the pair's first token.
tokenYinteger- The index of the pair's second token.
feeBpsinteger, 0 to 10000- The pair's liquidity fee.
tickSpacinginteger- The pair's tick spacing.
sqrtPriceQ64u128 string- The square root of the pair's price before the clearing.
tickinteger- The tick that price was in.
liquidityu128 string- The pair's active liquidity before the clearing.
ticksBatchStateTick[]- The pair's initialized ticks, ascending. See BatchStateTick.
BatchResultPrice
BatchResultPrice
indexinteger- The token's index.
priceQ64u128 string- The token's cleared price.
feeu64 string- The clearing fee the batch's buyers of the token pay, in its atoms.
BatchResultFill
BatchResultFill
sellinteger- The index of the token the direction sells.
buyinteger- The index of the token the direction buys.
phiu64 string- The fill fraction out of
FILL_ONE.
TxFailure
TxFailure
stage"build" | "wallet-rejected" | "wallet-changed" | "simulation" | "send" | "confirm"- Where it failed:
build,wallet-rejected,wallet-changed,simulation,sendorconfirm. messagestring- A sentence fit to show a person.
nextStepstring, may be absent- What the person can do next.
retryableboolean- Whether building and signing again can succeed.
programTxProgramFailure, may be absent- The program that refused the transaction and its error. See TxProgramFailure.
UnstakeRequest
UnstakeRequest
amountu64 string- Atoms of the bond mint being unstaked.
amountLamportsu64 string- The same, valued in lamports.
requestedAttime- When the unstake was requested.
unlockSlotu64 string- The slot the cooldown ends at.
unlockAttime- That slot as a time.
slotsLeftinteger- Slots of cooldown left.
secondsLeftinteger- The same in seconds.
withdrawableboolean- Whether
withdrawwould succeed now.
CoverParticipant
CoverParticipant
addressaddress- The order or position.
kind"order" | "position"- Which of the two it is.
claimableLamportsu64 string- Its share of the cover.
claimedboolean- Whether it has claimed.
BatchStateTick
BatchStateTick
tickinteger- The tick.
liquidityNeti128 string- The change in active liquidity when the price crosses the tick upward.
TxProgramFailure
TxProgramFailure
addressaddress- The program that raised the error.
codeinteger | null- The program's error number.
namestring | null- The program's error name.