The markets a trader can trade, each market’s live mid and route bound, its price candles, and admission for a token the Pool has not admitted yet.
Routes#
GET /v1/markets#
Tokens Jupiter routes, each paired against SOL and against USDC, a page at a time, in base mint order: the assets the Pool has admitted and every token a search has found. On mainnet a search with q first asks Jupiter’s token search, and each token it returns joins the list; q then matches symbol, name or mint, ignoring case. Trade’s market picker searches it, and deposit, exit and readBalances read each asset’s decimals and Registry index from it.
| Parameter | Type | In | Meaning |
|---|---|---|---|
cursor |
string (optional) |
query | Where the page starts: the previous page's page.nextCursor, the number of markets before it. |
limit |
integer (optional) |
query, default 24 |
Markets per page, 1 to 100. |
q |
string (optional) |
query | Search text for the base token, up to 100 characters. |
quote |
string (optional) |
query | SOL or USDC: only markets quoted in that asset. |
Returns Markets, a page of Market.
Errors
VALIDATION_ERROR:qis over 100 characters,quoteis neitherSOLnorUSDC,cursororlimitis out of range, or the query carries another key.CONFIGURATION_REQUIRED: a listed pair has no price exponent configured, or a mainnet search runs without the API’s Jupiter key.UPSTREAM_UNAVAILABLE: Jupiter’s token search is unreachable; retryable.
const page = await api.markets({ limit: 1 })
for (const market of page.items) console.log(market.pair, market.base.symbol, market.quote.symbol)
if (page.page.nextCursor) await api.markets({ limit: 1, cursor: page.page.nextCursor })
curl 'https://api.privium.io/v1/markets?limit=1'
{
"items": [
{
"pair": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v_So11111111111111111111111111111111111111112",
"base": {
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"symbol": "USDC",
"name": "USD Coin",
"decimals": 6,
"icon": null,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"admitted": true,
"registryIndex": 1,
"denominationUnit": "10000"
},
"quote": {
"mint": "So11111111111111111111111111111111111111112",
"symbol": "SOL",
"name": "Solana",
"decimals": 9,
"icon": null,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"admitted": true,
"registryIndex": 0,
"denominationUnit": "10000000"
},
"priceExponent": -9
}
],
"page": {
"nextCursor": "1",
"hasMore": true
},
"asOf": "2026-11-17T07:29:42.570Z"
}
GET /v1/markets/{pair}#
One market’s panel: its mid, the route bound for a proposed order, whether it is open to trade, the fee rate and the next cutoff (Countdown). Trade’s market panel and order ticket poll it. trade reads it plain to check the market, then, for a market order, again with the order’s size and side, checks that routeBound.bps is no wider than the order’s maximum slippage, and sets the protective limit from mid widened by that maximum (Market and limit).
A market order needs trading to be open, a mid that is not stale with confidenceBps no wider than κ, and a routeBound for its exact size and side. A limit order needs none of the price checks and rests while the mid is invalid.
| Parameter | Type | In | Meaning |
|---|---|---|---|
pair |
PairId |
path | The market's pair, as the market list gives it. |
size |
string (optional) |
query | A proposed order size in base units of the base asset, above zero. With side, the response carries its route bound. |
side |
string (optional) |
query | buy or sell, sent together with size. |
Returns MarketPanel.
Errors
VALIDATION_ERROR:pairis not a pair id,sizeis not a positive integer,sideis neitherbuynorsell, or only one ofsizeandsideis sent.NOT_FOUND: no market has thispair: its quote is neither SOL nor USDC, or its base token is unknown.CONFIGURATION_REQUIRED: the pair has no price exponent configured, or a mainnet lookup of an unknown base token runs without the API’s Jupiter key.UPSTREAM_UNAVAILABLE: Jupiter’s token search, the oracle, Jupiter’s price or Jupiter’s route quote is unreachable, or the route quote is not the one asked for; retryable.INDEXER_UNAVAILABLE: the indexer has not verified the latest Commit yet, or its root disagrees with the chain; retryable.PROGRAM_UNAVAILABLE: the Pool is not indexed yet; retryable.
const { items } = await api.markets({ q: 'SOL', quote: 'USDC' })
const panel = await api.market(items[0].pair, { query: { size: '100000000', side: 'sell' } })
const tradable = panel.trading === 'open' && panel.mid !== null && !panel.mid.stale
curl 'https://api.privium.io/v1/markets/So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v?size=100000000&side=sell'
{
"market": {
"pair": "So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"base": {
"mint": "So11111111111111111111111111111111111111112",
"symbol": "SOL",
"name": "Solana",
"decimals": 9,
"icon": null,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"admitted": true,
"registryIndex": 0,
"denominationUnit": "10000000"
},
"quote": {
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"symbol": "USDC",
"name": "USD Coin",
"decimals": 6,
"icon": null,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"admitted": true,
"registryIndex": 1,
"denominationUnit": "10000"
},
"priceExponent": -9
},
"mid": {
"price": "72.68168",
"source": "pyth",
"observedAt": "2026-11-17T09:41:30.000Z",
"ageMs": 59000,
"confidenceBps": 1,
"stale": false
},
"routeBound": {
"size": "100000000",
"side": "sell",
"bps": 51,
"source": "jupiter",
"estimatedAt": "2026-11-17T09:42:29.415Z"
},
"countdown": {
"currentSlot": "470885217",
"lastCommitSlot": "470884581",
"deltaSlots": 4,
"nextCutoffSlot": "470885218",
"slotTimeMs": 200,
"observedAt": "2026-11-17T09:42:29.420Z"
},
"trading": "open",
"feeBps": 10
}
GET /v1/markets/{pair}/candles#
Price candles for the market’s chart: GeckoTerminal’s public OHLCV for the base token’s deepest pool, which the API keeps for 60 seconds per pair, interval and limit. Trade’s price chart reads it. When that pool trades against the market’s quote asset, its candles come in that asset as they are. Otherwise the base’s USD candles are divided by the quote token’s USD candles at the same times: open by open, close by close, the high by the quote’s low and the low by the quote’s high. A time missing from either side is left out.
While GeckoTerminal fails, the route answers with the last candles the API read for that pair, interval and limit, however old, and cachedAt says when it read them. The API sends GeckoTerminal one request at a time, 6.1 seconds apart, so a read it has not kept takes several seconds.
| Parameter | Type | In | Meaning |
|---|---|---|---|
pair |
PairId |
path | The market's pair. |
interval |
string (optional) |
query, default 5m |
Candle length: 1m, 5m, 1h or 1d. |
limit |
integer (optional) |
query, default 100 |
How many of the latest candles to return, 1 to 500. |
Returns Candles.
Errors
VALIDATION_ERROR:pairis not a pair id,intervalis not one of1m,5m,1hand1d, orlimitis outside 1 to 500.NOT_FOUND: no market has thispair.CONFIGURATION_REQUIRED: the pair has no price exponent configured, or a mainnet lookup of an unknown base token runs without the API’s Jupiter key.UPSTREAM_UNAVAILABLE: Jupiter’s token search is unreachable during a mainnet lookup of an unknown base token, or GeckoTerminal is unreachable or has no pool for the quote token to convert with while the API holds no earlier candles for this pair, interval andlimit; retryable.
const { items } = await api.markets({ q: 'SOL', quote: 'USDC' })
const candles = await api.candles(items[0].pair, { interval: '5m', limit: 100 })
curl 'https://api.privium.io/v1/markets/So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/candles'
{
"source": "geckoterminal",
"pool": "BnYUiV8e1CRcCYDkG34VLh9UhrJUKquVM7MYGXV771nB",
"cachedAt": "2026-11-17T07:30:06.452Z",
"items": [
{
"time": "2026-11-16T15:00:00.000Z",
"open": "71.942703590057890382878795610815867723",
"high": "71.942703590057890382878795610815867723",
"low": "71.075260607071798855941169340016153099",
"close": "71.075260607071798855941169340016153099",
"volumeUsd": "8.196570353494637"
}
]
}
POST /v1/markets/{pair}/admit#
Requests admission of a market’s base asset, on demand, with the protocol paying the rent of the new asset state and vaults (Assets the Pool admits). Trade’s order ticket sends it for a market whose trading is admission-required, and trade sends it before answering ASSET_NOT_ADMITTED. For a base asset admitted already, it answers admitted and queues nothing; otherwise it queues the asset and answers requested.
Outside an Escape, queued assets are taken in mint order, and each is admitted on chain once it passes every check:
| Check | Passes when |
|---|---|
| Mint | The mint belongs to SPL Token or Token-2022 and decodes as a mint. |
| Extensions | Each extension the mint carries is TransferFeeConfig, TransferHook, MintCloseAuthority, ConfidentialTransferMint, ConfidentialTransferFeeConfig, InterestBearingConfig, MetadataPointer, TokenMetadata, GroupPointer, TokenGroup, GroupMemberPointer or TokenGroupMember (Token and Token-2022). |
| Transfer hook | The mint has no transfer hook, or its hook program is the one approved for that mint. |
| Routes both ways | For SOL and for USDC, unless the asset is that token, Jupiter routes a buy of the asset with the Pool’s minimum amount of that token and the sale of what the buy delivers back into it, each with a price impact no higher than the Pool’s maximum. |
| Daily budget | The Pool has taken fewer assets for admission since 00:00 UTC than its daily number. Past it, the asset stays queued for the next day. |
The answer comes before any check runs, so the market itself carries the outcome: read it again until trading is open, then place the order. An asset that fails a check stays unadmitted and its market admission-required; sending the request again queues it for a fresh check.
The body is an empty JSON object.
| Parameter | Type | In | Meaning |
|---|---|---|---|
pair |
PairId |
path | The market's pair. |
Returns Admission.
Errors
UNSUPPORTED_MEDIA_TYPE: the body is notapplication/json.VALIDATION_ERROR: the body is not{}, orpairis not a pair id.NOT_FOUND: no market has thispair.CONFIGURATION_REQUIRED: the pair has no price exponent configured, or a mainnet lookup of an unknown base token runs without the API’s Jupiter key.UPSTREAM_UNAVAILABLE: Jupiter’s token search is unreachable during a mainnet lookup of an unknown base token; retryable.RATE_LIMITED: more than 60POSTrequests to/v1in a minute from this client.
const { items } = await api.markets({ q: 'SOL', quote: 'USDC' })
const admission = await api.admit(items[0].pair)
if (admission.status === 'requested') console.log('Queued for admission.')
curl -X POST https://api.privium.io/v1/markets/So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/admit \
-H 'Content-Type: application/json' \
-d '{}'
{
"pair": "So11111111111111111111111111111111111111112_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"status": "admitted",
"rentPaidBy": "protocol"
}
Types#
Markets#
| Field | Type | Meaning |
|---|---|---|
items |
Market[] |
The page's markets. |
page |
object |
Where the next page starts. |
page.nextCursor |
string or null |
The cursor of the next page; null on the last. |
page.hasMore |
boolean |
Whether another page follows. |
asOf |
Timestamp |
When the server read the list. |
Market#
| Field | Type | Meaning |
|---|---|---|
pair |
PairId |
The market's PairId: its base mint and quote mint joined by _. |
base |
Asset |
The asset bought and sold. |
quote |
Asset |
The asset prices and fees are in: SOL or USDC. |
priceExponent |
integer |
e, fixed when the pair is admitted: an Intent's price counts 10^e quote whole tokens per base whole token. |
Asset#
| Field | Type | Meaning |
|---|---|---|
mint |
Address |
The token's mint address. |
symbol |
string |
The token's symbol. |
name |
string |
The token's name. |
decimals |
integer |
Decimal places of one whole token. |
icon |
string or null |
The token's icon URL; null when it has none. |
tokenProgram |
Address |
The token program that owns the mint: SPL Token or Token-2022. |
admitted |
boolean |
Whether the Pool has admitted the asset. Only admitted assets deposit and trade. |
registryIndex |
integer or null |
The asset's index in the Pool's registry, as Intents and leaves name it; null until admitted. |
denominationUnit |
PositiveU64 or null |
The smallest Exit piece in base units; every piece is this times a power of two. null until admitted. |
MarketPanel#
| Field | Type | Meaning |
|---|---|---|
market |
Market |
The market. |
mid |
Mid or null |
The live mid; null when no price is available. |
routeBound |
RouteBound or null |
The route bound for the queried size and side; null without them, or while the market has no mid. |
countdown |
Countdown |
The earliest cutoff an Intent sent now can make. |
trading |
"open", "escape", "admission-required" |
open; escape while the Escape is active and trading is closed; admission-required until both assets are admitted. |
feeBps |
integer (optional) |
φ in basis points, the rate the order ticket's fee estimate uses; null until configured. |
Mid#
| Field | Type | Meaning |
|---|---|---|
price |
UnsignedDecimal |
The mid in quote whole tokens per base whole token, as a decimal. |
source |
"pyth", "jupiter" |
pyth when the base token's price comes from Pyth's sponsored price account for its feed, read on chain; jupiter when it comes from Jupiter's price. |
observedAt |
Timestamp |
When the older of the base's and the quote's prices was published. |
ageMs |
number |
The price's age in milliseconds by the chain's clock when the server answered. |
confidenceBps |
number or null |
The wider of the base's and the quote's Pyth confidence intervals, in basis points of price; null when neither price has one. Wider than κ blocks market orders. |
stale |
boolean |
true when the price is older than maxPriceAgeMs or its confidence is wider than κ, or, for a pyth mid, when it lies more than κ from Jupiter's live price or that price cannot be read: market orders are refused and the pair's orders rest. |
RouteBound#
| Field | Type | Meaning |
|---|---|---|
size |
PositiveU64 |
The order size the bound is for, in base units, as queried. |
side |
"buy", "sell" |
The side it is for, as queried. |
bps |
integer |
β in basis points: β₀ widened by Jupiter's quoted price impact for this size and side, never below β₀. |
source |
"jupiter" |
Where the estimate comes from. |
estimatedAt |
Timestamp |
When the estimate was made. |
Countdown#
The next cutoff an Intent sent now can make, in MarketPanel, Home and the stream’s ready event. A Crossing begins once there is work and Δ slots have passed since the last Commit, so nextCutoffSlot is the last Commit’s slot plus Δ, or the slot after the current one once that has passed. While a Crossing is open, the cutoff after it falls Δ after its Commit lands (The batch).
| Field | Type | Meaning |
|---|---|---|
currentSlot |
U64 |
The cluster's slot when the server read it. |
lastCommitSlot |
U64 |
The slot of the last Commit. |
deltaSlots |
4 |
Δ, in slots. |
nextCutoffSlot |
U64 |
The earliest cutoff an Intent sent now can make: lastCommitSlot + deltaSlots, or currentSlot + 1 once that has passed. While a Crossing is open, the cutoff after it falls deltaSlots after its Commit. |
slotTimeMs |
number |
Milliseconds per slot, to turn slots into time. |
observedAt |
Timestamp |
When the server read the slot. |
Candles#
| Field | Type | Meaning |
|---|---|---|
source |
"geckoterminal" |
GeckoTerminal's public OHLCV. |
pool |
Address or null |
The token's deepest pool, which the candles describe; null when there is none. |
cachedAt |
Timestamp |
When the API read the candles from GeckoTerminal. It keeps them for 60 seconds per pair, interval and limit, and serves the last it read, however old, while GeckoTerminal fails. |
items |
Candle[] |
The latest limit candles, oldest first. |
Candle#
| Field | Type | Meaning |
|---|---|---|
time |
Timestamp |
The start of the candle's interval. |
open |
UnsignedDecimal |
The price at the interval's open, in the pair's quote asset per base whole token (an X/SOL chart is in SOL). |
high |
UnsignedDecimal |
The highest price in the interval, in the quote asset. |
low |
UnsignedDecimal |
The lowest price in the interval, in the quote asset. |
close |
UnsignedDecimal |
The price at the interval's close, in the quote asset. |
volumeUsd |
UnsignedDecimal |
USD volume traded in the interval. |
Admission#
| Field | Type | Meaning |
|---|---|---|
pair |
PairId |
The market. |
status |
"requested", "admitted" |
admitted when the base asset is admitted already; requested once its admission is queued. The market's trading turns open when the Pool admits it. |
rentPaidBy |
"protocol" |
The protocol pays the rent of the new asset state and vaults. |