Transactions API

Every buy and sell against a token sale contract is indexed here. Filter by token to watch a market, by account to watch a trader, or by both.

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

Endpoints

These are Superhero trade records, not raw chain transactions. For arbitrary chain history (transfers, contract calls, name transactions), use the middleware; see Node & Middleware.

GET /api/transactions

Both filters compose:

# All recent trades, with the token inlined
curl -s "https://api.superhero.com/api/transactions?includes=token&limit=20&page=1"
 
# One account's trades on one token
curl -s "https://api.superhero.com/api/transactions?token_address=ct_YOUR_SALE_ADDRESS&account_address=ak_YOUR_ADDRESS&includes=token&limit=20"

Response is the standard items plus meta envelope.

Results are ordered by created_at descending, and that is the only order: there is no order_by, order_direction, from_date or to_date (unrecognised keys are ignored). To bound a date range, page from the top and stop when created_at passes your cutoff, or use GET /api/tokens/{address}/transactions, which takes start_date and end_date.

Without token_address the list is restricted to tokens from the current community factory. An unresolvable token_address returns an empty page, not a 404. account_address also adds token.name, token.symbol, token.address, token.sale_address and token.collection to each row even without includes=token.

Trade row

With includes=token, a token object carrying the full token row is added.

Units

Nothing on a trade row needs dividing by 1e18, even though the field names repeat those on TokenDto, which are scaled:

• volume, protocol_reward and total_supply are in whole tokens, not base units.
• amount, unit_price, buy_price and previous_buy_price are in AE.
• market_cap is in AE, whereas TokenDto.market_cap is in aettos. The two differ by 1e18.

tx_type

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

Nothing else (a DEX swap, an AE transfer, a governance vote) is indexed here, and reverted transactions are skipped, so every row is a trade that succeeded.

Treat create_community as a buy. PnL, volume and trending all use tx_type IN ('buy', 'create_community') on the acquisition side and tx_type = 'sell' on the disposal side; counting only buy understates every creator's position by their founding purchase.

For the DEX's separate tx_type vocabulary, see DEX API.

GET /api/transactions/by-hash

Takes the hash as a query parameter, not a path segment:

curl -s "https://api.superhero.com/api/transactions/by-hash?tx_hash=th_YOUR_TX_HASH"

Returns a single row; a malformed hash is a 400. On a miss, the handler fetches the transaction from the middleware and indexes it on the spot, so a trade the indexer has not caught up to can be pulled in by asking for it; only if that also fails is it a 404. The DEX equivalent takes the hash as a path segment: GET /api/dex/transactions/{txHash}.

GET /api/tokens/{address}/transactions

These are aggregated rather than row-level, and charts are built from them.

curl -s "https://api.superhero.com/api/tokens/SUPERHERO/transactions?interval=3600&mode=aggregated&convertTo=usd"

For OHLC candles, GET /api/tokens/{address}/history is the better endpoint. See Tokens.

Live trades

The API pushes every live-indexed trade over Socket.IO on the token-history channel, carrying the row that was just written plus the token it belongs to. Seed your list from this endpoint once, then update from the socket. See WebSocket.

Relating a record to the chain

tx_hash is the on-chain transaction hash:

While a trade is confirming, poll the middleware form and treat a 404 as "still pending".

GET /api/debug/failed-transactions

A diagnostics endpoint: the 500 most recent rows of the failed-transactions table, newest first, with no parameters and no pagination.

Use it when a trade of yours is missing from /api/transactions and you want to know whether the indexer failed on it.

Related

• API Conventions: the units table and the shared pagination envelope
• Tokens API: the TokenDto that includes=token inlines
• Accounts API: the aggregated PnL these trades roll up into
• WebSocket API: push instead of poll for the same records
• Node & Middleware: chain history beyond Superhero trades
• æScan (opens in a new tab): the block explorer for resolving a tx_hash