Tokens API

Community tokens are the centre of the API: the trending list, portfolios, charts and trade records all resolve to a token. Twelve endpoints return tokens and their derived data.

All paths are relative to https://api.superhero.com. Reads need no authentication and are not rate-limited.

Endpoints

{address} accepts a name

Every {address} path parameter accepts a ct_... sale address, a ct_... AEX-9 address or the plain token name:

# Resolve by name
curl -s "https://api.superhero.com/api/tokens/SUPERHERO"
 
# The same token, by its sale address — take sale_address from the response above
curl -s "https://api.superhero.com/api/tokens/ct_YOUR_SALE_ADDRESS"

TokenDto

List rows may also carry collection_rank, the token's position within its collection.

address versus sale_address

• sale_address is the bonding-curve sale contract you buy from and sell into. The rest of the API keys on it: token_address on /api/transactions, the WebSocket channels, the portfolio PnL map and the DAO routes all mean the sale address.
• address is the AEX-9 token contract that holds balances. It is what a wallet displays and what the middleware's /v3/aex9/{address} endpoint takes.

When in doubt, use sale_address.

PriceDto

Wherever a value has a price, the API returns all nine currencies at once:

{ "ae": 0.0421, "usd": 0.0013, "eur": 0.0011, "aud": 0.002,
  "brl": 0.0071, "cad": 0.0018, "chf": 0.001, "gbp": 0.00097, "xau": 0.0000004 }

Every key is on the same scale as ae: usd is ae * rate.usd, and likewise for the rest. On market_cap_data every key is in aettos, so market_cap_data.usd / 1e18 is the USD market cap. Rates refresh every ten minutes; when unavailable every key except ae is null.

CollectionInfoDto

Units

A worked check:

total_supply  = "1000000000000000000"   ->  1000000000000000000 / 1e18 = 1 token
price         = "0.0421"                ->  0.0421 AE per token
market_cap    = "42100000000000000"     ->  42100000000000000 / 1e18 = 0.0421 AE

Holder balances follow decimals rather than a hardcoded 18:

Decimal.from(holder.balance).div(10 ** (parseInt(token.decimals) || 18))

GET /api/tokens

order_direction is ASC or DESC. order_by=treasury&order_direction=DESC is "richest treasuries first".

• An unknown order_by falls back to market_cap and an unknown order_direction to DESC, without an error.
• order_by=market_cap sorts on rank (refreshed every five minutes) with the direction reversed. Rank 1 is the highest market cap; unranked tokens carry 2147483647 and sort last.
• order_by=trending_score returns only tokens with at least 5 holders, 2 all-time posts mentioning the symbol and 3 all-time trades; if no token clears the gate the query is re-run without it. Zero-score tokens fall back to newest-first. This sort is cached for 15 minutes, every other sort for 60 seconds.
• Tokens with unlisted = true are excluded.

# The ten highest-scoring trending tokens
curl -s "https://api.superhero.com/api/tokens?order_by=trending_score&order_direction=DESC&limit=10"

Response is the standard items + meta envelope described in Conventions.

GET /api/tokens/{address}/trending-eligibility

One token's standing against the gate:

{
  "sale_address": "ct_...", "symbol": "SUPERHERO",
  "holders_count": 42, "post_count": 9, "stored_post_count": 9,
  "content_post_count": 7, "trade_count": 151,
  "thresholds": { "min_holders": 5, "min_posts": 2, "min_trades": 3 },
  "passes": { "holders": true, "posts": true, "trades": true, "eligible": true }
}

GET /api/tokens/{address}/holders

Paginated holder rows, ordered by balance descending, filtered to balance > 0:

A holder's share of supply is balance / total_supply (both in base units, so the scaling cancels). Requesting holders for a token whose holder table is empty enqueues a background sync, so a second request a few seconds later often returns more.

curl -s "https://api.superhero.com/api/tokens/SUPERHERO/holders?limit=20&page=1"

GET /api/tokens/{address}/performance

Returns token_id, sale_address and four windows:

past_24h · past_7d · past_30d · all_time

Each window carries these eleven fields:

Prices are trade buy prices in AE, the same scale as TokenDto.price; volume is already in whole tokens. The data is rebuilt every five minutes, so a brand-new trade is not reflected immediately, and a token with no indexed transactions returns 404. The same structure is inlined on TokenDto.performance.

curl -s "https://api.superhero.com/api/tokens/SUPERHERO/performance"

GET /api/tokens/{address}/performance-raw returns the identical payload.

GET /api/tokens/{address}/history

OHLC candles for charting. Returns a bare JSON array, not an items envelope; you have reached the end when a page comes back empty.

Each element carries timeOpen, timeClose, timeHigh, timeLow and a quote:

{
  "timeOpen": "2026-09-12T13:00:00.000Z",
  "timeClose": "2026-09-12T13:59:59.999Z",
  "timeHigh": "2026-09-12T13:41:02.000Z",
  "timeLow": "2026-09-12T13:06:55.000Z",
  "quote": {
    "convertedTo": "ae",
    "open": 0.0413, "close": 0.0421,
    "high": 0.0433, "low": 0.0409,
    "volume": 12.84,
    "total_supply": 305.5,
    "market_cap": 12.86,
    "timestamp": "2026-09-12T13:59:59.999Z",
    "symbol": "SUPERHERO"
  }
}

Candle units differ from TokenDto units. volume and total_supply are in whole tokens, and market_cap is in AE, not aettos and not base units. open, high, low and close are buy prices in the convertTo currency. open is set to the previous candle's close so the series is continuous.

GET /api/tokens/{address}/transactions covers the same ground with start_date / end_date bounds instead of paging. Defaults are interval=3600, mode=aggregated and start_date two days ago, so an unparameterised call returns 48 hourly candles; mode=normal returns the underlying rows. /history is cached for 5 seconds, /transactions for 60.

GET /api/tokens/{address}/rankings

The tokens adjacent to this one in the global ranking, as full token rows with performance and collection_info in an items plus meta envelope. limit defaults to 5; the window is centred on the target token, and an edge-of-board token still returns limit rows.

An unknown, unranked, other-factory or unlisted token returns an empty page, not a 404. meta.totalItems is the number of neighbours returned and totalPages is always 1.

GET /api/tokens/preview/{address}

A compact payload for cards and link previews. interval takes a keyword rather than seconds: 1d, 7d, 30d, 90d, 180d or all-time.

GET /api/tokens/preview/{address}/sparkline.svg returns a rendered SVG with the same interval plus background, height and width.

GET /api/tokens/{address}/score

Recomputes the trending score, persists trending_score and trending_score_update_at on the token, and returns { metrics, token }. Use it to inspect a score, not in a polling loop.

{
  "window_hours": 24,
  "last_activity_at": "2026-09-14T09:12:44.000Z",
  "last_trade_at": "2026-09-14T09:12:44.000Z",
  "last_social_activity_at": "2026-09-14T07:55:01.000Z",
  "age_hours_since_last_activity": 1.4213,
  "decay_multiplier": 0.575394,
  "trading_signals": {
    "active_wallets": { "raw": 7, "cap": 25, "normalized": 0.637 },
    "buy_count":      { "raw": 12, "cap": 40, "normalized": 0.691 },
    "sell_count":     { "raw": 3, "cap": 40, "normalized": 0.374 },
    "volume_ae":      { "raw": 430.5, "cap": 5000, "normalized": 0.713 }
  },
  "social_signals": {
    "mention_posts":    { "raw": 4, "cap": 15, "normalized": 0.58 },
    "mention_comments": { "raw": 11, "cap": 50, "normalized": 0.635 },
    "unique_authors":   { "raw": 6, "cap": 20, "normalized": 0.639 },
    "tips_count":       { "raw": 0, "cap": 15, "normalized": 0 },
    "tips_amount_ae":   { "raw": 0, "cap": 250, "normalized": 0 },
    "reads":            { "raw": 88, "cap": 200, "normalized": 0.845 }
  },
  "component_scores": { "trading": 0.661, "social": 0.588, "pre_decay": 0.614 },
  "trending_score": {
    "formula": "((trading_weight * trading_score) + (social_weight * social_score)) * freshness_decay",
    "result": 0.353294,
    "pre_decay": 0.614
  }
}

Values are illustrative. Caps, weights and decay constants are shared by every token, so trending_score is comparable across tokens. The full formula is on Trending & Topics.

Related

• API Conventions: pagination, the limit cap and the full unit table
• Transactions API: the trade records behind tx_count and the price series
• Accounts API: the same tokens from the holder's side, with portfolio value and PnL
• WebSocket API: push updates for TokenDto instead of polling
• Trending & Topics: the trending-score formula behind trending_score
• Bonding curve: why buy price and sell price differ