DEX API

The DEX endpoints cover the constant-product AMM behind Superhero's swap UI: listed tokens and prices, liquidity pairs and reserves, swap routes, and every swap and liquidity event. The bonding-curve counterpart is Tokens.

All paths are relative to https://api.superhero.com. Reads need no authentication.

Endpoints

Tokens

Pairs

Transactions and routing

DexTokenDto

decimals is a number here and a string on the bonding-curve TokenDto; price is a PriceDto object here and a decimal string there. Do not share a parser between the two.

order_by accepts pairs_count, name, symbol, created_at, price, tvl, 24hchange, 24hvolume, 7dchange, 7dvolume, 30dchange, 30dvolume. Pass listed=true to restrict to curated tokens, listed=false for the rest, and omit it for everything.

curl -s "https://api.superhero.com/api/dex/tokens?listed=true&order_by=tvl&order_direction=DESC&limit=20"

DexTokenSummaryDto carries address, total_volume (a PriceDto) and change, a map keyed by period, or null.

PairDto

Reserves and LP supply are big-integer strings in base units. Divide each by 10 raised to its own token's decimals, which may differ between the two sides.

curl -s "https://api.superhero.com/api/dex/pairs?order_by=transactions_count&order_direction=DESC&limit=20"

PairSummaryDto adds volume and price change over 24h, 7d and 30d:

Pass ?token=ct_... to choose the denominating side; without it the endpoint defaults to WAE when one side of the pair is WAE.

PairTransactionDto

One row per swap or liquidity event.

LiquidityInfoDto is type (PairMint or PairBurn) plus amount0 and amount1.

tx_type

tx_type is the name of the router entrypoint that was called. The complete set:

swap_exact_tokens_for_tokens     add_liquidity
swap_tokens_for_exact_tokens     add_liquidity_ae
swap_exact_tokens_for_ae         remove_liquidity
swap_tokens_for_exact_ae         remove_liquidity_ae
swap_exact_ae_for_tokens
swap_ae_for_exact_tokens

The tx_type filter is exact-match, so ?tx_type=swap matches nothing; to select all swaps, make six requests or filter client-side on the swap_ prefix. PairMint and PairBurn are the pair contract's event names and appear only inside pair_mint_info.type: add_liquidity* carries a PairMint, remove_liquidity* a PairBurn.

Date filters on this endpoint are from_date and to_date, both ISO 8601, both bounds inclusive. order_by accepts created_at (the default) or tx_type; anything else is a 400.

# Every "exact tokens in" swap, newest first
curl -s "https://api.superhero.com/api/dex/transactions?tx_type=swap_exact_tokens_for_tokens&limit=20&order_direction=DESC"

Fetch a single transaction by hash as a path segment (GET /api/dex/transactions/{txHash}), unlike the bonding-curve equivalent, which takes a tx_hash query parameter.

GET /api/dex/swap-routes/{from_token}/{to_token}

Returns an array of routes, each an ordered array of pairs, covering direct and single-hop paths. An empty array means no route exists.

A route containing an unsynchronized pair is not quotable, so check synchronized on every hop.

curl -s "https://api.superhero.com/api/dex/swap-routes/ct_FROM_TOKEN/ct_TO_TOKEN"

GET /api/dex/pairs/from/{from_token}/to/{to_token}/providers is the broader form, returning all possible paths including multi-hop.

GET /api/dex/tokens/{address}/history

OHLCV for a single token. The series is derived from the deepest pool pairing that token against WAE, so the price is expressed in AE; if no WAE pool exists, the deepest available pool is used.

Requesting a fiat convertTo for a token without a WAE-quoted pool returns 400.

GET /api/dex/pairs/{address}/history is the pair-level equivalent and adds from_token, which takes token0 or token1 to choose the quoting direction.

GET /api/dex/tokens/{address}/price

{ "price": "0.0431", "token": {} }

token is the full DexTokenDto; price is the best price found, quoted in WAE, as a decimal string. It is null when the token has no liquid path to WAE. The value comes from the deepest-liquidity path, not the median. A 404 means the token is unknown to the DEX index.

GET /api/dex/tokens/{address}/price/analysis

The same computation with its working shown:

base_token defaults to WAE; debug=true widens the per-path breakdown. Asking for the base token's price against itself returns "1". A token with no path at all is a 404 (No price paths found for token ...).

A wide spread between price, medianPrice and liquidityWeightedPrice means the quote rests on one shallow pool.

PATCH /api/dex/tokens/{address}/listed

Sets the listed flag. Body is { "listed": true } or { "listed": false }; returns the updated DexTokenDto, or 404 for an unknown token.

Requires the API key, sent as x-api-key: YOUR_KEY or Authorization: Bearer YOUR_KEY. A missing or wrong key is a 401. Every other write in the API uses a wallet signature. See Conventions.

Pagination on /api/dex/*

limit defaults to 100 and is capped at 100. Unlike the rest of the API, exceeding the cap does not error: limit=500 is silently clamped to 100, page=0 to 1, and a non-numeric limit falls back to 100. Read meta.itemsPerPage rather than assuming your limit was honoured, and never infer "no more results" from getting fewer rows than you asked for.

Related

• API Conventions: pagination, the limit cap and the date-parameter spellings
• Tokens API: the bonding-curve tokens and their TokenDto
• Transactions API: bonding-curve trades
• Swap: the feature these endpoints back
• Pools: what a pair is and what providing liquidity means
• Wrapped AE: why WAE is the pricing base for every history series