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 pageOn the wire
addressA base58 string of 32 bytes: a wallet, a mint or an account.
signatureA base58 string of 64 bytes: a transaction signature.
u64 string, u128 string, i128 stringAn 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 stringA number formatted for display, such as "162.4". Use the integer field beside it for arithmetic.
timeAn ISO 8601 time in UTC, such as "2026-11-22T09:30:00.000Z".
hexLowercase hexadecimal bytes.
base64Standard 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 nextCursor of 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.

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

  2. Sign

    Decode transactionBase64, sign it with the wallet, and keep the build's id.

  3. Submit

    Send the signed bytes to POST /v1/transactions/submit with mode relay. If the wallet sent the transaction itself, report its signature with mode wallet-sent.

  4. Follow

    Poll GET /v1/transactions/{id} until status is confirmed, finalized, failed or expired.

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.

CodeHTTPRaised when
VALIDATION_ERROR400A path, query or body field is missing, malformed or unknown. fieldErrors names each field.
UNAUTHORIZED401The request needs a session it does not carry.
ORIGIN_NOT_ALLOWED403A browser request came from an origin the API does not serve.
NOT_FOUND404The order, position, stake, token or transaction named in the request does not exist.
PROGRAM_UNAVAILABLE409The program is not deployed yet. Every route that builds a transaction raises it while GET /health says waiting.
CONFIGURATION_REQUIRED409The action needs a protocol setting that is not set yet.
IDEMPOTENCY_CONFLICT409The idempotencyKey was already used with a different build.
TRANSACTION_EXPIRED409The build's blockhash expired before the signed transaction arrived. Build again.
PAYLOAD_TOO_LARGE413The request body is larger than the API accepts.
UNSUPPORTED_MEDIA_TYPE415A body was sent without Content-Type: application/json.
SIMULATION_FAILED422The built transaction failed when simulated. programError names the program's error when the program refused it.
CHAIN_REFUSED422The chain refused the submitted transaction. programError names the program's error when there is one.
RATE_LIMITED429Too many requests. retryAfterSeconds says when to try again.
INTERNAL_ERROR500The API failed on its own side.
UPSTREAM_UNAVAILABLE502The API could not reach the chain. Retry.
BATCH_NOT_FOUND404No batch has that number.
PAIR_NOT_FOUND404No pair has that address or slug.
SOLVER_NOT_FOUND404No solver has that address or operator.
BATCH_SEALED409The action needs an open batch and the batch has sealed.
ORDER_NOT_CANCELLABLE409The order's batch has sealed, or the order is already filled, settled or cancelled.
ORDER_LOCKED409The 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_SETTLEABLE409The order's batch has not cleared yet, or the order is already settled.
COOLDOWN_ACTIVE409The unstake cooldown has not finished. GET /v1/stakes shows the slots left.
NOTHING_TO_CLAIM409The position has no fees owed, the stake has no rewards, or the wallet has no unclaimed share of the cover.
INVALID_TICK_RANGE400A tick is not a multiple of the pair's tick spacing, or the lower tick is not below the upper.
INSUFFICIENT_BALANCE422The wallet holds less than the amount to sell, add or stake, or the stake holds less than the amount to unstake.
PRICE_OUT_OF_BAND422A posted price is outside its token's band.
INSUFFICIENT_BOND422The 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 nextCursor of 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 nextCursor of 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 liquidity removes 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 nextCursor of 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 nextCursor of 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 nextCursor of 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 id of 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 id of 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.
typedataSent
readystatus, openBatchId and latestBatch, a BatchSummary or nullOnce, when the stream opens.
batchA BatchSummaryEach time a batch changes: an order joins it, it seals, clears, is proven, slashed or rolled.
resyncNothing to readWhen 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"
live when the program is deployed and the API is serving it, waiting before that.
mode"fixture" | "chain"
chain when the API reads the program.
programIdaddress
The address of the una program.
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 null while it is waiting.
asOftime
When the API read this.

ProtocolParams

ProtocolParams

programIdaddress
The address of the una program.
feeRecipientaddress
The address that receives the protocol share of the clearing fee.
unaMintaddress | null
The mint of UNA, or null until 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. null until it is set.
protocolFeeShareBpsinteger, 0 to 10000 | null
The share of the clearing fee that goes to the fee recipient. null until 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 null while 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 null once 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

itemsOrder[]
The items of this page. See Order.
pagePageInfo
Where this page sits in the list. See PageInfo.
asOftime
When the API read this.

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 batchId once 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 null before it clears.
fillFractionBpsinteger, 0 to 10000
The part of the order filled.
status"open" | "filled" | "partial" | "rolled" | "expired" | "cancelled" | "settled"
open in a batch's window, filled or partial once cleared, rolled when its batch rolled, settled once paid out, expired or cancelled when returned.
cancellableboolean
Whether cancel would succeed now.
settleableboolean
Whether settle would 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 buildId when 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 buildId when 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 buildId when 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 mode relay.

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 buildId when 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, slashed or rolled.
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 null before 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_batch transaction.
slashSignaturesignature | null
The slash_batch transaction.
slotsLeftinteger | null
Slots until the batch's window ends, or null once 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_batch transaction.
coverBatchCover | null
The cover, when the batch was slashed. See BatchCover.
walletOrdersOrder[]
The orders of the wallet in 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"
submitted and unconfirmed are still in flight. confirmed, finalized, failed and expired are final.
signaturesignature, may be absent
The transaction's signature, once it is known.
errorTxFailure, may be absent
Why it failed, when status is failed or expired. 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, slashed or rolled.
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 null before 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_batch transaction.
slashSignaturesignature | null
The slash_batch transaction.

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 null for 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 null if 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 null while 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 cursor of the next page, or null on 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_batch transaction.

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, unstaking during the cooldown, or withdrawable after 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 wallet in the query, or null without one.
walletClaimedboolean
Whether that wallet has claimed.
participantsCoverParticipant[], may be absent
With a wallet in 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, send or confirm.
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 withdraw would 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.