Developers: DEX service API
Where it is
Section titled “Where it is”- Through a Kadia site:
/api/dex/testnet/v1/<route>on the same origin. The site forwards only the routes listed below, with their query parameters checked, and answers anything else with 404 (or 405 for the wrong method). - The service itself:
/api/v1/<route>. The path must start with/api/v1/, and routes match exactly (a trailing slash is a 404).
For a typed client, use dex-sdk.
Conventions
Section titled “Conventions”- Success: HTTP 200,
{"apiVersion": "1", "context": {…}, "data": …}. - Error:
{"apiVersion": "1", "context": {…}, "error": {"code": "…", "message": "…"}}, with the HTTP status from the error. context:tipId,branchGeneration,manifestId,activationHash,upcomingHeight(the tip plus one),parametersDigest,rulesDigest. Every POST must send back a currentcontext. A stale one is409 STALE_CONTEXT.- Values: amounts are decimal strings of base units, never JSON numbers. Prices are decimal strings with 12 digits after the point. Times are milliseconds from block timestamps. Ids are 64 lowercase hex characters.
- POST bodies: a JSON object of 1 byte to 2 MiB.
- Caching: every reply is
Cache-Control: no-store. - Rate limits, per client in a sliding minute: 600 GETs, 60 POSTs, 10 submits. Over the limit is
429 RATE_LIMITEDwithRetry-After. - Common errors:
INVALID_SCHEMA400,INVALID_BODY400,INVALID_CONTEXT400,NOT_FOUND404,STALE_CONTEXT409,NODE_TIP_MOVED409,RATE_LIMITED429,INTERNAL_ERROR500,ADAPTER_UNAVAILABLE503. - Market refusals on quote and build (409):
UNSAFE_MARKET,DORMANT_MARKET,UNOFFICIAL_MARKET,MARKET_WOUND_DOWN,GOVERNANCE_UNKNOWN,DEPOSITS_PAUSED.
Routes
Section titled “Routes”Every route below is forwarded by a Kadia site, unless it’s listed under not forwarded.
Health and markets
Section titled “Health and markets”-
GET /health: Service, chain, ledger and capability status -
GET /markets: Every non-dormant market, sorted by id -
GET /markets/{id}: One market, dormant included -
GET /markets/{id}/stats: Reserves, value locked, prices, the 24-hour window -
GET /markets/{id}/candles: Price candles (parameters below) -
GET /markets/{id}/book: The order book -
GET /feeds: The oracle feeds stop orders use -
GET /liquidity?owner=<key>: LP tokens held by a compressed key -
GET /protocol/stats: The protocol’s public figures: markets, swaps and volume (kadia-dex cfcaaf0) -
/healthincludescapabilities,ledger,signing,assuranceandtradingBlockedBy. -
Candles:
intervalis5m,15m,1h,4hor1d, or blocksb1tob21600;basisispoolororders;fromandtoare in ms;limitis 1 to 1000.
-
/liquidity: the service takes up to 8owners; a Kadia site forwards one.
POST /quote
Section titled “POST /quote”Prices an order. Every request sends context and marketId.
- A swap (no
kind) takes:side, 0 or 1;amount;slippageBps, 0 to 10,000;expiryHeight, afterupcomingHeightand at most 262,800 blocks ahead.
- A swap answers
id,expectedOutput,minimumOutput,executionFee,minerFee,feeBps, and more. - Other kinds:
lp-deposit,lp-redeem,zap,dca,grid,partial,route, each with its own fields. - A quote lives 300 seconds, and can’t be built once the chain’s tip has moved.
POST /build
Section titled “POST /build”Returns the unsigned transaction.
operationis one of:create, from aquoteId;cancelorrefund, from anorderId.
- It answers:
chainIdandcontext;transactionId, the blake2b-256 ofsigningMessageHex;signingMessageHexandunsignedTransaction;requiredProofs;ergoPay, when asked.
- Name the
boxIdwhen you cancel or refund a DCA, grid, partial, stop or route order. dex-sdk refuses a cancel or refund without it. - Errors include
QUOTE_UNAVAILABLE,STALE_QUOTE,QUOTE_KIND_MISMATCH,FUNDING_UNAVAILABLE,ORDER_SPENT,ORDER_BOX_MOVEDandNOT_EXPIRED. - Always check a build before a wallet signs it. dex-sdk’s
verifyBuilddoes this.
Signing, submit, orders
Section titled “Signing, submit, orders”-
POST /wallet/boxes: A compressedpublicKey’s P2PK funding boxes -
POST /signing/authorize: Authorises a wallet to sign a build -
POST /signing/validate: Checks the signed bytes before submit -
POST /submit: Submits the exact signed bytes -
GET /orders?owner=<key>: Order records -
GET /transactions/{id}: One transaction, live or archived -
GET /vaults?owner=<key>,GET /vaults/{id},GET /vaults/{id}/quotes: Maker vaults and their quotes -
POST /governance/build: The unsigned transaction for a governance or treasury proposal, on testnet only, for the console to check against its own node -
POST /ergopay/reduce: Reduces a page-built transaction’s signing message over the boxes given, for ErgoPay -
POST /pool/check: Judges a proposed pool creation -
/submittakessignedBytesHexandsigningMessageHex, and answerstransactionId,wireSha256andstatus: "pending". -
/orders: a Kadia site also forwardsstatus=active,limit(1 to 500) andafter. -
/pool/checkalways answers HTTP 200, withokandreasons. -
/governance/build: a Kadia site forwards it on testnet only, at most 16 KiB, with only the documented fields. D-6 (announcing a market upgrade) isn’t forwarded. -
/ergopay/reducetakescontext,messageHex(at most 96 KiB),inputBoxesHex(1 to 50) anddataInputBoxesHex(at most 32), each box at most 4 KiB, in a body of at most 512 KiB. It checks nothing about the transaction itself, and nothing signs.
Dashboard
Section titled “Dashboard”GET /dashboard/markets: A row per market: reserves, value locked, 24-hour and 7-day windows, protocol feeGET /dashboard/treasury: The treasury’s boxes, balance and custodyGET /dashboard/governance: The governance box at the tip: mode, pause, announcement, keysGET /dashboard/series: Daily series (below)GET /dashboard/treasury/series: The treasury balance per dayGET /dashboard/activity: Governance and treasury events, newest first.limitis 1 to 200, with abeforecursor and a comma list ofkinds
Keys appear only as fingerprints: the first 8 bytes of the compressed key’s blake2b-256, as 16 hex characters.
Not forwarded by a Kadia site
Section titled “Not forwarded by a Kadia site”On the service only: GET /stats, GET /markets/{id}/swaps, /trades and /tvl, and GET /orders/{id}.
Forwarded, but not in the four docs: GET /markets/{id}/book, GET /feeds, the /vaults routes, POST /governance/build, POST /ergopay/reduce, /orders’s status, limit and after, and GET /dashboard/settler (kadia-dex #299: the settler’s last batch and the orders it may still fill).
/dashboard/series
Section titled “/dashboard/series”One row per UTC day by block time (the block header’s timestamp, never the wall clock), oldest first.
-
market: a market’s id, orall(the default). Dormant markets keep their history; an unknown id is 404. -
from,to: days,YYYY-MM-DD, inclusive.fromaftertois400 INVALID_SCHEMA. -
limit: days per page, 1 to 366, default 90. -
Range and paging: days run from the first indexed day to the last. A range outside that is clamped and may be empty. Without
from, a page is thelimitdays ending atto. Rows are dense (an empty day is a zero row), andnextis the next page’sfrom, ornull. -
Also in every answer:
interval("1d"),market,days,indexedHeight,tipHeight,asOf. -
Units: base units; ERG figures are nanoERG at the day’s closing reserves, and
nullwhen part had no price that day.
One market, a row per day: day, start (its first millisecond), swaps, netted, volumeX, volumeY, volumeErg (volumeX in ERG, or volumeY when X has no price), lpFees ({x, y, erg, poolFeeBps}, the whole pool fee), protocolFees.estimated ({x, y, erg, shareBps}, the treasury’s share, r12 markets only) and protocolFees.claimed ({claims, x, y, erg}, exactly what that day’s claims took).
market=all, ERG figures only: day, start, swaps, volumeErg, lpFeesErg, protocolFeesEstimatedErg, protocolFeesClaimedErg, unpricedMarkets (the markets the sums leave out) and byMarket (the same figures per market).
The docs don’t name the key that holds the rows, and give no example answer. Read one live answer before relying on its shape.
Technical details
Sources: kadia-dex docs/interface/service-api/ (health-markets-stats.md, quote-build.md, orders-signing-submit.md, dashboard.md) at commit 908de0d (908de0db649a2904f3cc480fc9dbb0f92749a829); kadia-web packages/serve/src/routes.mjs (what a Kadia site forwards). Those files are the full reference. This page is a map of them.