Skip to content

Developers: DEX service API

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

  • 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 current context. A stale one is 409 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_LIMITED with Retry-After.
  • Common errors: INVALID_SCHEMA 400, INVALID_BODY 400, INVALID_CONTEXT 400, NOT_FOUND 404, STALE_CONTEXT 409, NODE_TIP_MOVED 409, RATE_LIMITED 429, INTERNAL_ERROR 500, ADAPTER_UNAVAILABLE 503.
  • Market refusals on quote and build (409): UNSAFE_MARKET, DORMANT_MARKET, UNOFFICIAL_MARKET, MARKET_WOUND_DOWN, GOVERNANCE_UNKNOWN, DEPOSITS_PAUSED.

Every route below is forwarded by a Kadia site, unless it’s listed under not forwarded.

  • 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)

  • /health includes capabilities, ledger, signing, assurance and tradingBlockedBy.

  • Candles:

    • interval is 5m, 15m, 1h, 4h or 1d, or blocks b1 to b21600;
    • basis is pool or orders;
    • from and to are in ms;
    • limit is 1 to 1000.
  • /liquidity: the service takes up to 8 owners; a Kadia site forwards one.

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, after upcomingHeight and 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.

Returns the unsigned transaction.

  • operation is one of:
    • create, from a quoteId;
    • cancel or refund, from an orderId.
  • It answers:
    • chainId and context;
    • transactionId, the blake2b-256 of signingMessageHex;
    • signingMessageHex and unsignedTransaction;
    • requiredProofs;
    • ergoPay, when asked.
  • Name the boxId when 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_MOVED and NOT_EXPIRED.
  • Always check a build before a wallet signs it. dex-sdk’s verifyBuild does this.
  • POST /wallet/boxes: A compressed publicKey’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

  • /submit takes signedBytesHex and signingMessageHex, and answers transactionId, wireSha256 and status: "pending".

  • /orders: a Kadia site also forwards status=active, limit (1 to 500) and after.

  • /pool/check always answers HTTP 200, with ok and reasons.

  • /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/reduce takes context, messageHex (at most 96 KiB), inputBoxesHex (1 to 50) and dataInputBoxesHex (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.

  • GET /dashboard/markets: A row per market: reserves, value locked, 24-hour and 7-day windows, protocol fee
  • GET /dashboard/treasury: The treasury’s boxes, balance and custody
  • GET /dashboard/governance: The governance box at the tip: mode, pause, announcement, keys
  • GET /dashboard/series: Daily series (below)
  • GET /dashboard/treasury/series: The treasury balance per day
  • GET /dashboard/activity: Governance and treasury events, newest first. limit is 1 to 200, with a before cursor and a comma list of kinds

Keys appear only as fingerprints: the first 8 bytes of the compressed key’s blake2b-256, as 16 hex characters.

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

One row per UTC day by block time (the block header’s timestamp, never the wall clock), oldest first.

  • market: a market’s id, or all (the default). Dormant markets keep their history; an unknown id is 404.

  • from, to: days, YYYY-MM-DD, inclusive. from after to is 400 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 the limit days ending at to. Rows are dense (an empty day is a zero row), and next is the next page’s from, or null.

  • 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 null when 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.