Skip to main content
DEX Aggregator add-on. Route swaps across the Cardano DEXes currently marked buildable by GET /api/aggregator/supported-dexes for best execution. You request a quote, Nexus returns the best route and an unsigned transaction CBOR, you sign it with your wallet, and Nexus co-signs and submits it. The aggregator is non-custodial: Nexus never holds your funds or keys, and you sign every transaction.
The build and submit endpoints require the Transaction Builder add-on, on its own or through the Build + AI or Complete bundle. Without it they return HTTP 402 with "addon": "transactionBuilder". The read endpoints (quote, reverse-quote, tokens, supported-dexes, status) need only a market-data-eligible tier.
Base URL: https://nexus.gerowallet.io · Auth: X-Api-Key: nxs_…

Which key to use

There are two kinds of key on this surface and they are not interchangeable. A public partner key is for browser embeds only, the <gero-swap> widget and the Nexus market kit: it is public by design, it works only from the browser origins registered on it, and it reaches only the swap endpoints and the read-only market data the embeds need. From a registered origin it can call /api/aggregator/** (read and write) and, read-only, /api/config/swap, /api/market/**, /api/dex/orders/owner/**, /api/prices/**, /api/dex/swaps/**, /api/dex/pools/token/**, /api/dex/orderbook/**, /api/dex/tokens/{policyId}/{assetName}/top-traders, /api/sync/status and /api/partner/swaps/summary. A partner key is created on Cardano mainnet or Cardano preprod and stays on that network. The gateway sends every /api/aggregator/** call made with it to the engine of that network, and a preprod key is for testing only (see Testing on preprod). A public partner key needs no Nexus plan: an account without one can create it (up to two keys), embed the widget and earn its partner fee on every mainnet swap. The market data reads among them still need the Market Data add-on, which does need a plan. Anything you call from your own server needs an ordinary nxs_ API key on a plan with the Transaction Builder add-on instead; the partner key will not work there, and the ordinary key will not pay you a partner fee. Everything below assumes the ordinary key.
The widget supports two embed topologies, both using the same partner key and the same origin rule. In mode="dapp" (browser-direct) the key sits in your page and the browser sets Origin for you. In mode="native" (server-proxied) your backend holds the key, and your proxy must forward the browser’s Origin header unchanged (Origin: https://your-registered-site) with that origin registered on the key. There is no separate server-side credential: the origin binding is what stops a leaked key being replayed from any site, so one rule covers both modes. Full details in the widget README.

Build a whole page

The <gero-swap> widget is one panel. If you want a full Cardano market page around it, with a token screener, charts, trades, an order book and a live swaps feed, use the hosted market kit: one script tag and one element on your own site, configured in the Nexus console or by hand, and authenticated with the same public partner key and the same registered origins. The market reads it makes need the Market Data add-on on your plan. See Market page.

Diagnosing a partner key

GET /api/aggregator/partner/self-check answers with everything wrong with the key you presented and the request you made, instead of refusing. It runs ahead of the gates that would refuse it, so it works when nothing else does:
An empty problems array means nothing is wrong. Each entry carries a code, a severity, a message about your own setup and the fix: key.network in the response is the network the key is on (CARDANO_MAINNET or CARDANO_PREPROD), and the payout-address entries name that network and the prefix its addresses start with. Call it through the same path your integration uses. If you proxy Nexus through your own backend, call it through that proxy: that is what shows whether your proxy forwards Origin. The response is never cached, reports how many origins are registered but never which, and reports whether a payout address is set and payable but never the address, because in a browser-direct embed anyone can read the key out of your page source. From the Nexus dashboard the same diagnosis is at GET /api/keys/{keyId}/partner/self-check over a browser session, which additionally returns the full origins list and the payout address.

Your swaps as a feed

GET /api/partner/swaps lists every swap built through your keys, newest first, with its status, the pair, the input amount and which key built it. It is what a “someone just swapped” alert or a recent-swaps list on your own site reads. Call it with an ordinary nxs_ key from your server, or from the Nexus dashboard over your session. It does not answer to the public partner key, because a key that lives in a web page must not be able to enumerate your swaps. There is never a fee, share or revenue figure on it; your earnings are GET /api/partner/earnings. The feed and the earnings cover mainnet only: swaps made with a preprod key never appear in either.
A swap’s status is BUILT (the wallet was handed an unsigned transaction), SUBMITTED, CONFIRMED, FAILED or EXPIRED. swapId is the transaction hash and is null while the swap is only BUILT, because no transaction has been submitted yet. amountIn is an integer string in tokenIn’s base units (lovelace for ADA). ticker and name come from the token registry and are null for a token it does not know; unit is always present. Live alerts. Poll every 15 seconds (the response is cacheable for that long) with updatedSince set to the newest updatedAt you have already seen. You get back only the swaps that changed since then, in every status. Keep the latest row per swapId and react to the ones whose status became CONFIRMED, or SUBMITTED if you want to announce a little earlier. Recovering after downtime. Call with updatedSince set to the last updatedAt you stored before the outage and page through nextCursor until it is null. The filter is inclusive, so the boundary row comes back once more; it is the same upsert by swapId as above. A swap that changed status while you were down carries the later updatedAt and is returned, so nothing is lost. Browsing history. Omit updatedSince and page with cursor. Pages are newest first and nextCursor walks towards older swaps. If the swap engine cannot be reached the response is 503 with errorCode: AGGREGATOR_METRICS_UNAVAILABLE. Retry it; never treat it as an empty list.

A swap counter for your page

GET /api/partner/swaps/summary is the counts: swaps built, submitted and confirmed through the key that authenticates the call, over the last 24 hours, 7 days and 30 days, with the ADA volume that moved. It is counts and totals only, so it is the one /api/partner endpoint that also answers to the public partner key from a registered origin. A “swaps today” counter can therefore run directly in your page with the same key the widget uses, and no server of yours in between. It counts mainnet swaps only; swaps made with a preprod key are not counted.
Called with an API key, public or ordinary, the figures are that key’s alone. Called from the Nexus dashboard over your session, they cover all of your keys. The 24-hour window is rolling; the 7-day and 30-day windows are whole UTC calendar days ending today, so 7d spans between six and seven days. Every count is bucketed by the time the swap was built, submitted means a transaction hash exists whatever happened afterwards, and volumeOrders below confirmed means the ADA volume covers only that fraction of the swaps, because the engine did not record an ADA notional on the rest. Poll it every 15 seconds at most: the response is cacheable for that long and the server answers from the same reading inside it. A 503 here means the engine could not be reached; show the last figure you had, never a zero. The same origin rule as the widget applies: from a browser the key works only from the origins registered on it, and a server-side proxy must forward the browser’s Origin header unchanged.

Recognising a payout on chain

Every revenue-share payout we send carries a CIP-20 message in the transaction’s metadata, under label 674. One transaction can pay several payouts (to different partners, or to you more than once), so the message has one line per payout, ids ascending:
Look for the line with your payout’s id, not for the first line (msg[0]), which may belong to another payout. Several of your payout ids can also share one txHash. The number is the payout’s id on GET /api/partner/earnings, whose payouts list carries each payout’s id, status, netLovelace, txHash, submittedAt and confirmedAt. Match on the message rather than on the sending address: the address can change, the tag does not. Any explorer that shows transaction metadata renders it, and GET /api/transactions/{txHash}/metadata returns it as ["674"].msg. Payouts sent before the tag existed have no message; match those on txHash. Payouts are made on mainnet only; a preprod key never receives one.

Endpoints

Network. A call made with an API key goes to the engine of the key’s network: mainnet for a mainnet key, preprod for a preprod key. You do not have to say which. Every endpoint above except partner/self-check, which Nexus answers itself, also accepts an optional network query parameter, mainnet or preprod. When you send it, it must be the key’s own network, so it can confirm the routing but never change it. A mainnet key that sends network=mainnet behaves exactly as one that sends nothing. Two refusals come from the gateway, before the engine is reached: These two bodies carry error, not errorCode, and no message, because they come from the gateway and not from the engine. Branch on the HTTP status and error, and quote requestId (also sent as the X-Request-Id header) when you contact support. The widget sends network for you; see Testing on preprod.

The flow

  1. Quote — POST /api/aggregator/quote (exact-in) or /api/aggregator/reverse-quote (exact-out). You get the best route: expected output, price impact, the fee breakdown, and appliedFeeRate. On a busy Minswap V2 pool the quote already allows for the orders queued ahead of yours; see Quotes on busy pools.
  2. Build — POST the chosen route to /api/aggregator/build-tx. You receive unsignedTxCbor and txBodyHash. The transaction already contains the DEX order, the aggregator fee output, and the aggregator’s key in requiredSigners.
  3. Sign — sign the CBOR client-side with CIP-30 signTx(unsignedTxCbor, true). Nexus never sees your keys. This produces your witness set.
  4. Submit — POST { unsignedTxCbor, userWitnessHex } to /api/aggregator/submit. Nexus validates the fee output, co-signs with the aggregator key, merges witnesses, and submits. You get a txHash.
  5. Track — poll /api/aggregator/status/{txHash}: PENDING | SUBMITTED | CONFIRMED | FAILED | EXPIRED. CONFIRMED means the order transaction is on chain. The DEX executes the order after that, usually within a few blocks, and it can still come back unfilled; see When a swap does not execute.
Submission is co-signed: /build-tx puts the aggregator’s key in requiredSigners, so the transaction is only valid once Nexus adds its signature at /submit. This is what enforces the aggregator fee — a transaction Nexus did not build (or whose fee output was altered) is rejected with UNKNOWN_BUILD.

Fees

The aggregator fee is a separate output on the swap transaction, taken on the ADA side, at 0.10% for every sender. Quotes and builds report it as appliedFeeRate.
Because the fee is a standalone ADA output it is subject to Cardano’s minimum-UTxO rule, so the effective minimum fee is ~1.2 ADA even though the percentage floor is 0.5 ADA. This only affects swaps whose proportional fee would otherwise fall below ~1.2 ADA (roughly, ADA notionals under ~1,200); above that the percentage dominates.
The aggregator fee, and the partner fee on a partner swap, are paid in the order transaction itself, when the order is placed. If the swap then does not execute, see Fee refunds.

Quotes on busy pools

A swap is an order that the DEX’s batcher executes a few blocks later, after any orders already waiting on the same pool. Each of those that executes first moves the price. On a Minswap V2 pool the quote takes them into account: expectedOutput, minimumOutput and priceImpact are worked out on the pool as it will be once the queued orders that can execute have done so, and the route’s queuedOrdersAhead says how many it assumed. It is null when nothing was queued, and on every other DEX. Orders placed after your quote can still move the price before yours runs. On a token that is moving fast, a wider slippageTolerance makes it less likely that the order comes back unfilled. Automatic slippage. Send "autoSlippage": true with slippageTolerance on /api/aggregator/quote or /api/aggregator/quote/routes, and on a Minswap V2 route the tolerance is widened, up to 5%, when large orders have just run on the pool. A quiet pool keeps the tolerance you sent. Every route reports appliedSlippagePercent, the tolerance its minimumOutput was worked out with, and autoSlippage, which is true only on a route where the automatic rule was applied, whether or not it widened. On such a route recentBatchImpactPercent is the price impact the largest recent batch on the pool would have on your order; it is null on every other route. Without autoSlippage your slippageTolerance is used as sent. The <gero-swap> widget uses automatic slippage with a 2% base unless the page sets a fixed slippage.

When a swap does not execute

Every swap order carries a minimum output, the quote’s minimumOutput: the expected output less your slippage tolerance. If the DEX cannot deliver at least that much when it reaches the order:
  • Minswap V2 returns a market order unfilled. The batcher sends the order’s ADA or tokens back to the wallet, less its batcher fee (up to 2 ADA).
  • Every other DEX, and Minswap V2 limit, stop-loss and OCO orders, leave the order open until it can execute or its owner cancels it.
Seeing the outcome. GET /api/dex/orders/owner/{pkh} (and GET /api/dex/orders/{txHash}/{outputIndex} for one order) reports OPEN, FILLED or CANCELLED. An order that was cancelled by its owner or returned unfilled by the DEX is CANCELLED, and it never appears as a trade in swap history, candles or volume. A CANCELLED order’s closedBy says which: DEX when the DEX returned it unfilled, OWNER when it was taken back without executing, and null for orders cancelled before 4 November 2026. The <gero-swap> widget uses it to explain a cancelled swap. Until 3 November 2026 a Minswap V2 order that was returned unfilled was reported as FILLED and counted as a trade, and some earlier records may still show that.

Fee refunds

When a Minswap V2 market order built by Nexus or the <gero-swap> widget is returned unfilled, Gero refunds:
  • the aggregator fee,
  • the partner fee, if the swap was made through a partner, and
  • the batcher fee the DEX kept.
The refund goes to the address the DEX returned the order to, and Gero pays the refund transaction’s own network fee, so that address receives the full amount. You do not need to ask for it. A refund of up to 25 ADA is usually paid automatically within a few minutes of the order being returned; a larger one is paid after a review. The network fees of the original transactions are not refunded. A market order on another DEX that stayed open without executing and that its owner then cancelled is reviewed case by case. Swaps that executed, limit, stop-loss and OCO orders that their owner cancelled, and a market order cancelled soon after it was placed are not refunded. If you think a swap should have been refunded, email support@gerowallet.io with the order’s transaction hash.

Recognising a refund on chain

A refund transaction carries a CIP-20 message under label 674: a tag, then the transaction hash of each order it refunds.
GET /api/transactions/{txHash}/metadata returns it as ["674"].msg, and any explorer that shows transaction metadata renders it.

Partner keys

When Gero refunds a swap built with your partner key, your share of its partner fee is taken back: the swap counts as zero in your earnings for its day, and the amount is deducted from your next payout.

Exact-output quotes

/api/aggregator/reverse-quote returns the least input required to net a desired output. For token → ADA swaps, the response’s minimumOutput is the gross pool floor (amountOut + the DEX batcher fee), so it can be larger than expectedOutput — this is intentional: it guarantees you net the amount you asked for after the batcher takes its fee. The required input is reported in the route’s amountIn; maximumInput carries the slippage ceiling.

Submit error codes

/api/aggregator/submit returns structured errors as { "errorCode": …, "message": … }: Through Nexus, COSIGNER_DISABLED and SUBMIT_REJECTED arrive as engine errors (below), with the reason in message.

Engine errors

When the swap engine fails with a 5xx that has no code of its own, every /api/aggregator/* route (quote, build-tx, submit, cancel) answers 502 with:
upstreamStatus is the engine’s own status and message its reason, cut to 300 characters. A 502, 503 or 504 with no errorCode means Nexus could not reach the engine at all (timeout or connection failure). Either way, quote requestId (also sent as the X-Request-Id header) when you contact support. The engine’s own 4xx answers pass through unchanged, as { "errorCode": …, "message": … }. One of them tells you a wallet and a key are on different networks:

Supported DEXes

The routable set is returned live by GET /api/aggregator/supported-dexes (the txBuilding list), and that response is the authority: it changes as venues are verified. Swap building is currently routable on Minswap (V1 and V2), WingRiders (V1 and V2), Splash, and SaturnSwap. Other venues are indexed for market data and quoting but are not in the default build path. Always read supported-dexes at runtime rather than hardcoding a venue list. That list is for mainnet. A preprod key is routed on Minswap V2 and SundaeSwap V3 only in this first phase, so preprod routes are thinner than mainnet ones. Call supported-dexes with the key you will use: it is answered by the engine of the key’s network.

Testing on preprod

A partner key can be created on Cardano preprod, so you can test the whole swap flow with preprod wallets and test ADA before going live on mainnet. Preview and every other network are still refused for partner keys.
  1. Create the key. In the Nexus dashboard, open Swaps, then Widget and fees, choose Create partner key and set the network to Cardano preprod. (The API keys page works too: with your personal workspace selected, set the network to Cardano preprod and switch on the partner toggle.) Register the origins of your test site, as for any partner key. The dashboard labels the key “Test network”, and its live widget preview renders on preprod.
  2. Match the payout address to the network. A payout address on a key must be on the key’s own network: addr_test1… on a preprod key, addr1… on a mainnet key. Nexus refuses an address from the other network. Nothing is paid out on preprod, whatever address you set.
  3. Embed the widget with the matching network.
  4. Connect a preprod wallet holding test ADA.
The widget’s network attribute is mainnet or preprod and must be the network of the key. It sends the value as the network query parameter on every gateway call. A key and an attribute that disagree are refused with 403 network_scope, and the widget shows This key is not for the preprod network. When network is set, the widget also checks the connected wallet on connect. It reads CIP-30 getNetworkId() (1 on mainnet, 0 on every testnet, so it cannot tell preprod from preview) and, when the wallet does not match, shows Switch your wallet to Preprod (or Switch your wallet to Mainnet) and keeps quoting and swapping disabled until it does. A wallet without getNetworkId() is let through, and the engine’s WRONG_NETWORK answer at build time is shown instead. In mode="native", the host’s Signer can implement an optional getNetworkId(): Promise<number> to get the same check. The widget’s swap-error event carries code: "WRONG_NETWORK" or "network_scope" for these two cases.
Set network explicitly. With the attribute unset, the widget sends no network parameter and checks no wallet, the gateway routes by the key alone, and explorer links default to mainnet.
What differs on preprod:

Example

Full request/response schemas are in the API Reference.