Transaction History

Every buy and sell against a bonding curve is an on-chain contract call, indexed by Superhero and served through one endpoint with two filters. Use it to check your own fills, research a token before you buy it, or watch a specific account.

From the command line

node scripts/superhero-transactions.mjs mine [limit] [page]
node scripts/superhero-transactions.mjs token ct_<sale_address> [limit] [page]
node scripts/superhero-transactions.mjs account ak_<address> [limit] [page]
node scripts/superhero-transactions.mjs all [limit] [page]
node scripts/superhero-transactions.mjs activity ct_<sale_address> ak_<address> [limit]

Default limit is 20 and default page is 1 everywhere. mine needs AE_PRIVATE_KEY set, because it derives your address from the key; the other four take an address as an argument and need no key.

The API

All five commands are the same endpoint with different query parameters:

GET /api/transactions
  ?token_address=ct_...      sale address of the token
  &account_address=ak_...    the trader
  &includes=token            embed the full token record in each row
  &limit=20
  &page=1

Both filters are optional and combine. Omitting both gives you the market-wide feed. The response is paginated with items and meta.

A single transaction can be fetched by hash:

GET /api/transactions/by-hash?tx_hash=th_...

Fields

Each row carries these fields:

Every "price object" has ae, usd, eur, aud, brl, cad, chf, gbp and xau keys, so you can read a trade in any of them without doing your own conversion. Read amount.ae, not amount.

token.* fields are present only when the request carries includes=token or an account_address filter; otherwise they are absent.

volume is a token count

volume is the number of tokens; amount is the AE. The indexer decodes them from different events:

amount on a buy is the fee-inclusive total. Buy's first argument is total_price, which already contains the 0.5% affiliation fee, and that is why it is the right basis for a PnL cost figure. The event's own total_supply is the supply before the trade, so the indexer adds volume on a buy and subtracts it on a sell to store the supply after.

create_community rows are buys

A token creation with an initial buy is stored as one row with tx_type: 'create_community', priced exactly like a buy. Anything counting purchases must include it; the backend's own PnL queries count tx_type IN ('buy', 'create_community'). A creation with no initial buy emits no PriceChange event and is stored with zeroes.

The unfiltered feed is scoped to the current factory: with no token_address, tokens from a superseded factory deployment do not appear.

What the CLI prints

The transactions script reduces each row to:

function formatTx(tx) {
  return {
    type: tx.tx_type,
    hash: tx.tx_hash,
    account: tx.address,
    token_name: tx.token?.name,
    token_symbol: tx.token?.symbol,
    sale_address: tx.sale_address || tx.token?.sale_address,
    amount_ae: tx.amount?.ae,
    unit_price_ae: tx.unit_price?.ae,
    buy_price_ae: tx.buy_price?.ae,
    sell_price_ae: tx.sell_price?.ae,
    timestamp: tx.created_at,
    block_height: tx.block_height,
  };
}

Pre-trade research

node scripts/superhero-transactions.mjs token ct_<sale_address> 30

Many small buyers suggests organic momentum; one large buyer suggests a pump with higher exit risk. On a bonding curve this distinction is sharper than on an order book: a single large buy permanently moves the price for everyone, because the supply genuinely increased. The elevated price sits there until someone sells, whether or not anyone else wanted the token at that level. A chart that has gapped up on one transaction is telling you about one person's position, not about demand.

Three things to count in the output:

1. Distinct accounts. Thirty trades from four addresses is four opinions, not thirty.
2. Buy-to-sell ratio. A wall of buys with no sells can mean conviction, or it can mean nobody has been able to exit yet.
3. Clustering in time. Trades evenly spread over days look different from trades in one minute, and the second pattern often has one account behind it.

Cross-check whatever you conclude against the holders tab. See Reading a Token Page.

Verifying a transaction on-chain

Every row carries a tx_hash. Superhero's indexer is convenient but it is not the chain; to verify a trade independently, open the hash in aeScan (opens in a new tab). What to check:

• The contract called is the sale address you expected.
• The caller is the account the indexer attributed it to.
• The amount attached matches the AE you think moved.
• The events (Buy or Sell on the sale contract, Mint or Burn on the token contract) carry the executed figures, which is what you want if a quote and a fill disagreed.

The same applies to a contract address: paste a sale_address into the explorer and you can read the deployed code and call its read-only entrypoints directly.

Diagnosing a failed trade

GET /api/debug/failed-transactions is a diagnostic endpoint with no UI behind it. It takes no parameters, is not scoped to an account, and returns at most 500 rows, newest first:

These are transactions the indexer failed to ingest, not transactions that failed on-chain. A reverted buy never reaches it. A retry job runs every 30 minutes and drops a row once it succeeds or once retries passes 10, so the table is a rolling backlog rather than a history. If your trade is on aeScan but missing from /api/transactions, this is where to look for it.

First steps when a trade did not go through:

See Buying & Selling for the allowance and slippage mechanics behind the first two rows.

Related

• Reading a Token Page: the holders and chart panels to weigh this data against
• Buying & Selling: what each of these transactions did on-chain
• Portfolio & PnL: your positions, which these fills add up to
• The Trending Score: the momentum signal that trade flow either confirms or contradicts
• Transactions API: the endpoint reference
• aeScan (opens in a new tab): the æternity explorer for verifying any hash or address