Accounts API

Everything the API knows about an ak_... address: its profile fields and links, the tokens it holds, its portfolio value over time, its realized and unrealized PnL, and its place on the trading leaderboard.

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

Endpoints

The portfolio endpoints and the leaderboard use camelCase startDate / endDate, unlike the snake_case start_date / end_date under /api/analytics.

GET /api/accounts/{address}

curl -s "https://api.superhero.com/api/accounts/ak_2ruXgsLy9jMwEqsgyQgEsxw8chYDfv2QyBfCsR6qtpQYkektWB"

links holds the current, verified identity:

links, profile and the top-level fields are three generations of the same data; read links.x, then profile.x_username, then x_username, and strip a leading @.

GET /api/accounts

curl -s "https://api.superhero.com/api/accounts?order_by=total_volume&order_direction=DESC&limit=10"

Searching by an ak_... the table has not seen hydrates it from the transactions table first, so a brand-new trader can be found by exact address.

Name resolution helpers

• GET /api/accounts/chain-names?addresses=ak_a,ak_b returns a map of address to .chain name or null. Every valid address you send is present in the result; invalid ones are dropped and at most 25 are resolved per call.
• GET /api/accounts/search?q=alice&limit=8 is typeahead. limit is clamped to 1–20, default 8; q is capped at 100 characters, and a q shorter than the minimum returns []. Items carry address and chain_name.
• GET /api/accounts/by-nostr?pubkeys=... takes comma-separated npub or 64-character hex keys, at most 200, and returns the matching accounts.

GET /api/accounts/{address}/tokens

Each item is a holder row with a token object attached, carrying a freshly computed rank:

{
  "id": "...", "aex9_address": "ct_...", "address": "ak_...",
  "balance": "1500000000000000000000", "block_number": 1104233,
  "last_tx_hash": "th_...", "created_at": "2026-05-02T11:04:19.000Z",
  "token": { "rank": 17 }
}

balance is in token base units. Divide by 10 raised to the token's decimals. Because limit is capped at 100, an unfiltered fetch returns the top 100 holdings by balance; use search to narrow.

creator_address and owner_address change the query

Pass either and the endpoint lists tokens the path address created or owns, regardless of balance, with whatever balance exists (or the string "0"). The value acts only as a flag (the filter is on the path address), so pass the same address as the path.

# Tokens the account holds
curl -s "https://api.superhero.com/api/accounts/ak_YOUR_ADDRESS/tokens?order_by=balance&order_direction=DESC&limit=50"
 
# Tokens the account created, including any it has sold out of
curl -s "https://api.superhero.com/api/accounts/ak_YOUR_ADDRESS/tokens?creator_address=ak_YOUR_ADDRESS&limit=50"

GET /api/accounts/{address}/portfolio/history

Returns a bare JSON array of snapshots.

Snapshots are reconstructed at request time: the range is walked in interval-second steps (future timestamps dropped, at most 100,000 points), each timestamp is resolved to a block height, and the AE balance, token holdings and PnL are computed at that height. Every point costs work, so this is the slowest endpoint in the API. Bound it with startDate and endDate. History reaches back to the factory's deployment height.

These are plain numbers already in AE and USD, so there is no 1e18 division.

TotalPnlDto:

PnlAmountDto is an ae and a usd number.

Cost basis and the two PnL modes

Cost basis is the weighted average purchase price across the account's entire history with a token; create_community counts as a buy alongside buy. include selects the definition:

Cumulative PnL includes unrealised gains on open positions; range PnL is realised only. The average cost used to price a range sale is the all-time average. percentage is gain_ae / cost_basis_ae * 100, and 0 when the cost basis is 0. Holdings at a block height count trades with block_height strictly less than the snapshot height.

curl -s "https://api.superhero.com/api/accounts/ak_YOUR_ADDRESS/portfolio/history?interval=86400&convertTo=ae&include=pnl"

For a live ticker use GET /api/accounts/{address}/portfolio/value, which returns { value, timestamp } and takes convertTo of ae or usd.

GET /api/accounts/{address}/portfolio/stats

Realized trading quality over a date range. startDate defaults to 30 days ago (inclusive), endDate to now (exclusive).

GET /api/accounts/{address}/pnl?blockHeight=N gives point-in-time PnL: block_height, total_pnl and a tokens_pnl map keyed by sale address. blockHeight defaults to the current height.

GET /api/accounts/leaderboard

• Precomputed window. Pass window of 7d, 30d or all.
• Custom period. Pass startDate and endDate together. Leaders are ranked by performance in that range among accounts that traded in it, with metrics and buy/sell counts scoped to it. tradingOnly=true bases period PnL and ROI on realized token-trading PnL only, excluding transfer-driven portfolio changes.

curl -s "https://api.superhero.com/api/accounts/leaderboard?window=30d&sortBy=roi&sortDir=DESC&limit=18&page=1"

Items carry address, chain_name, aum_usd, pnl_usd, roi_pct, mdd_pct, buy_count, sell_count, volume_usd, created_tokens_count, owned_trends_count and portfolio_value_usd_sparkline (an array of [timestamp, value] pairs).

mdd_pct is maximum drawdown as a positive percentage: the largest (peak - value) / peak along the sparkline, times 100. 0 means the portfolio never fell from a peak; larger is worse, which is why sortDir defaults to ASC for it.

meta is not the standard envelope: page (not currentPage), limit, totalItems, totalPages, window, sortBy, sortDir and a timeFilter of value, unit, start and end. Snapshot windows are rebuilt every ten minutes; responses are cached for up to 60 seconds, and meta.timeFilter.start / end reflect when the cache entry was filled.

Related

• API Conventions: the date-parameter casing split and the leaderboard's meta
• Tokens API: the TokenDto nested inside each holding
• Transactions API: the individual trades these aggregates are built from
• Profile API: writing to the links block
• Portfolio: what these numbers mean for a trader