Skip to main content
DEX Aggregator add-on. Route swaps across all indexed Cardano 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; you sign every transaction.
The build and submit endpoints require the Transaction Builder add-on. 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: nexus_…

​
Endpoints

MethodPathDescription
POST/api/aggregator/quoteBest-execution quote for an exact input amount
POST/api/aggregator/reverse-quoteExact-output quote — least input to obtain a desired output
POST/api/aggregator/build-txBuild the unsigned swap transaction (CBOR)
POST/api/aggregator/submitCo-sign and submit the signed swap transaction
GET/api/aggregator/status/{txHash}Order status
GET/api/aggregator/tokensTokens with at least one routable pool
GET/api/aggregator/supported-dexesDEXes available for routing and building

​
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 / discountApplied.
  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.
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.
Rate
Standard0.10%
GERO holders (≥ $10 of GERO at the sending address)0.05%
Pass senderAddress on the quote request to see your effective rate (appliedFeeRate, discountApplied). The rate is pinned when the transaction is built and re-checked at submit with a small grace band, so price movement between build and submit cannot invalidate an honest swap.
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.

​
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": … }:
errorCodeHTTPMeaning
FEE_OUTPUT_MISSING400No output to the aggregator fee address
FEE_TOO_LOW400Fee output below the minimum
COSIGNER_PKH_MISSING400Aggregator key absent from requiredSigners
UNKNOWN_BUILD400Transaction body was not produced by /build-tx
DISCOUNT_NO_LONGER_ELIGIBLE409GERO holdings dropped below the discount threshold since build — request a fresh quote
REGISTRY_UNAVAILABLE503The build registry was unavailable — retry the build
COSIGNER_DISABLED503Co-signing not configured on the server
SUBMIT_REJECTED502The node/network rejected the transaction (reason included)

​
Supported DEXes

The routable set is returned live by GET /api/aggregator/supported-dexes (the txBuilding list). At launch it spans the major Cardano spot venues — Minswap (V1/V2), SundaeSwap V3, WingRiders (V1/V2), MuesliSwap, TeddySwap, Splash, CSwap, and ShadowBook. VyFi is indexed but not yet routable.

​
Example

# 1. Quote an exact-in swap (50 ADA → MIN), with the GERO-holder discount check
curl -X POST "https://nexus.gerowallet.io/api/aggregator/quote" \
  -H "X-Api-Key: nexus_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenIn": "lovelace",
    "tokenOut": "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c6484d494e",
    "amountIn": "50000000",
    "slippageTolerance": 0.5,
    "senderAddress": "addr1q9..."
  }'
# → { "routes": [ { "dex": "MINSWAP_V2", "expectedOutput": "1234...", "appliedFeeRate": "0.0005", "discountApplied": true, ... } ], "bestRouteIndex": 0 }

# 2. Build the unsigned transaction (requires the Transaction Builder add-on)
curl -X POST "https://nexus.gerowallet.io/api/aggregator/build-tx" \
  -H "X-Api-Key: nexus_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "route": { ... }, "senderAddress": "addr1q9...", "utxos": [ ... ] }'
# → { "unsignedTxCbor": "84a4...", "txBodyHash": "ab12…", "aggregatorFeeLovelace": 1200000, "appliedFeeRate": "0.0005", "discountApplied": true }

# 3. Sign unsignedTxCbor client-side: CIP-30 signTx(cbor, true) → witness set

# 4. Co-sign + submit
curl -X POST "https://nexus.gerowallet.io/api/aggregator/submit" \
  -H "X-Api-Key: nexus_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "unsignedTxCbor": "84a4...", "userWitnessHex": "a100..." }'
# → { "txHash": "abc123...", "status": "SUBMITTED" }

# 5. Track
curl "https://nexus.gerowallet.io/api/aggregator/status/abc123..." \
  -H "X-Api-Key: nexus_your_api_key_here"
# → { "txHash": "abc123...", "status": "CONFIRMED" }
Full request/response schemas are in the API Reference.