--- title: "Mint-scoped trade tape (cursor-paginated raw trades)" method: GET path: "/tokens/{mint}/trades" tags: ["Tokens"] --- # Mint-scoped trade tape (cursor-paginated raw trades) `GET /tokens/{mint}/trades` ## Request - Base URL: `https://madeonsol.com/api/v1` - URL: `https://madeonsol.com/api/v1/tokens/{mint}/trades` - Auth: HTTP bearer Every captured trade for one token, newest first — the backfill complement to the live firehose (seed history, then keep current via the stream). Per trade: tx_signature, wallet_address, action, sol_amount, token_amount, price_sol/price_usd, market_price_sol/market_price_usd, early_buyer_rank, slot, block_time. **Two different prices, on purpose.** `price_sol` is *this trade's executed price* — `sol_amount / token_amount`, so it reconciles exactly with the amounts on the same row and with the PnL endpoints. `sol_amount` is the wallet's net SOL movement, so that price is the trader's all-in effective rate: it includes the swap fee and any account rent paid in the same transaction, and it is not the pool mid. `market_price_sol` is our market-cap tracker's canonical pool price sampled near that trade's slot — one value per token per update, so every trade in the same slot shares it. Use `price_sol` for cost basis, fills and PnL; use `market_price_sol` when you want a per-token price series independent of trade size and direction. **Exact amounts** (`amounts`, not yet enabled — appears on every row once exact amounts are switched on): `sol_amount` and `token_amount` keep their meaning (gross SOL movement incl. fee/rent; 6-decimal rounded UI amount). `amounts` adds the exact base-unit values as strings — see the TradeRawAmounts schema. Rows stored before exact amounts existed report `raw_known: false` with every field null (unknown, never 0). *Changed 2026-08-16*: `price_sol`/`price_usd` previously carried the canonical value, which disagreed with the row's own amounts by a 7.9% median (and far more on fast-moving mints, where one slot can span a 60% price swing). The canonical number did not disappear — it moved to `market_price_*`. **Coverage honesty**: capture starts 2026-04-12 and is pump.fun-pipeline scoped — the `coverage` response object carries both markers. **Size floor**: Buys under 0.05 SOL (under $3.50 when paid in USDC/USDT) are not stored; sells that receive SOL are kept at any size. (`coverage.size_floor`). Default window is full history. PRO+. **Where the rows come from** (*added 2026-08-29*): closed months older than the newest three move from Postgres to a Parquet archive; pages are split at `history.postgres_from` (Unix seconds) — rows at/after it are served from Postgres, older rows from the archive reader — with the same ordering and cursor. `history.archive_used` says whether this page touched the archive (`archive_months` lists which), `history.archive_available` whether the archive could be reached (`null` = not configured), and `history.truncated: true` means older history was requested but the archive did not answer — retry later rather than treating `has_more:false` as the end of the tape. Response header `X-Read-Source`: `core`, `core+archive` or `archive`. ## Path parameters - `mint` string, required ## Query parameters - `limit` integer - `cursor` string - `action` 'buy' | 'sell' - `wallet` string - `since` integer - `until` integer ## Response `200` OK - object - `mint` string - `trades` object[] - `tx_signature` string - `wallet_address` string - `action` 'buy' | 'sell' - `sol_amount` number - `token_amount` number - `price_sol` number, nullable: This trade's executed price (sol_amount / token_amount) - `price_usd` number, nullable - `market_price_sol` number, nullable: mc-tracker's canonical pool price sampled near this trade's slot — not this trade's price - `market_price_usd` number, nullable - `early_buyer_rank` integer, nullable - `slot` integer, nullable - `block_time` integer: Unix seconds - `traded_at` string, date-time - `amounts` TradeRawAmounts: Exact on-chain amounts of this trade (#508). Present only once exact amounts are enabled server-side. Integers are decimal STRINGS (u64 base units exceed the JSON double range). `raw_known: false` = a row stored before exact amounts existed: every field is null = UNKNOWN, never 0. With `raw_known: true`: `token_raw` is the wallet's net change of the traded mint in base units (token_amount = token_raw / 10^token_decimals, exact — 1 base unit of a 9-decimal token is "1" here while token_amount rounds to 0); `sol_net_lamports` is the signed SOL settlement (negative = paid) with the tx fee and token-account rent EXCLUDED, null unless SOL is the proven settlement; `quote_*` is the one non-SOL token the wallet moved the other way (USDC, PUMP, an xStock …); both null = settlement unknown (never guessed). - `token_raw` string, nullable, required: abs net change of the traded mint, base units - `token_decimals` integer, nullable, required - `sol_net_lamports` string, nullable, required: signed lamports, fee + token-account rent excluded; null unless SOL is the proven settlement - `quote_mint` string, nullable, required - `quote_raw` string, nullable, required: abs net change of quote_mint, base units - `quote_decimals` integer, nullable, required - `raw_known` boolean, required: false = legacy row, every raw field null (unknown) - `event` TradeEventFacts: Event identity and attribution labels of this trade row (migration 493). Present on /tokens/{mint}/trades and /wallet/{address}/trades once event reads are enabled server-side (live since 2026-10-16). Every field null = a netted legacy row: one row per (transaction, wallet, mint), the pre-493 shape, and today every stored row (the event-row writer is not on). Values are open-ended labels: treat an unrecognised value as not proven, never as a normal trade. Never deduplicate on (tx_signature, wallet_address): N event rows of one transaction share tx_signature and differ in event_id. - `event_id` string, nullable, required: `signature:outer_ix[.inner_ix]` of the decoded swap instruction; null = netted row (one row for the wallet's whole net change of the mint in this transaction) - `trader_status` string, nullable, required: signer | non_signer | unproven (a non-signer whose swap is proven by its legs but whose ownership is not: shown on the token tape, excluded from every wallet-scoped read and count); null = legacy row. Later labels may appear; only null, signer and non_signer count as the wallet's own trade. - `price_status` string, nullable, required: null = priced as before | quote_unpriced (non-SOL quote leg without a price: sol_amount is the wallet's fee, not the consideration; price_sol / price_usd are null) | proceeds_unattributed (a sell whose proceeds went to another wallet or to nobody provable: token_amount counts, sol_amount is NOT the proceeds, price_sol / price_usd are null; not written until the attribution writer is enabled) - `block_time_source` string, nullable, required: chain | ingest_clock (the live stream carries no block time, so block_time is our ingest clock); null = legacy row (ingest clock on the live path) - `next_cursor` string, nullable - `has_more` boolean - `filters` object - `action` 'buy' | 'sell' | 'null', nullable - `wallet` string, nullable - `since` integer - `until` integer - `history` object: Postgres/archive split for this page (added 2026-08-29) - `postgres_from` integer: Unix seconds — rows at/after this come from Postgres, older from the archive - `archive_used` boolean - `archive_months` string[] - `archive_available` boolean, nullable: null = archive reader not configured - `truncated` boolean: true = older history was requested but the archive did not answer — do not treat has_more:false as the end of the tape - `note` string: Present when the archive could not be reached or is not configured - `coverage` TradeCoverage: Coverage disclosure for endpoints backed by our persisted trade capture (`token_trades` / early-buyer data). Capture starts 2026-04-12 and persistence is gated to the launchpad pipeline (pump.fun, LaunchLab/bonk, bags) — it is NOT a full Solana trade history. Three separate answers (2026-09-21): `data_observed`/`in_scope` = at least one persisted row (presence, not completeness — a brand-new in-scope mint with no trades yet also reads false), `eligibility` = whether the CURRENT gate admits the subject, `completeness` = always `not_verified`. When no rows exist, zero/empty values mean 'not captured' (see eligibility for why), never 'no activity'. - `history_start` integer: Epoch seconds of the first persisted trade (2026-04-12). - `scope` string - `in_scope` boolean, nullable: Kept for compatibility — same value as data_observed: true = we hold ≥1 persisted trade for this subject · false = none persisted (see eligibility for why — a brand-new in-scope mint also reads false) · null = probe unavailable - `data_observed` boolean, nullable - `eligibility` 'eligible' | 'lapsed' | 'excluded' | 'unknown' | 'admitted_previously' | 'not_applicable' | 'null', nullable: Resolved against the EFFECTIVE production capture settings (refreshed every few minutes; if they cannot be confirmed the answer narrows, never widens). eligible = admitted by the current gate · lapsed = launched via our pipeline, capture window closed under the current settings · excluded = blacklisted · unknown = no evidence the gate admits it (most likely outside the launchpad pipeline; basis capture_state_unavailable = settings could not be confirmed, no claim either way) · admitted_previously = persisted rows prove past admission, current status not established · not_applicable = wallet subjects · null = lookup failed - `eligibility_basis` string, nullable: Evidence behind eligibility (e.g. unresolved_launch, recently_bonded, revived_curve, pipeline_known, launchlab_pool, bags_vanity_mint, launchpad_proven, resolved_launch, bonded_over_7d, revival_expired, blacklisted, persisted_rows, capture_state_unavailable, lookup_failed) - `completeness` 'not_verified' - `size_floor` object: Persistence size floor of the same write path (added 2026-09-30). Buys under 0.05 SOL (under $3.50 when paid in USDC/USDT) are not stored; sells that receive SOL are kept at any size. Live streams, prices and candles are not subject to it. - `min_sol` number - `min_stable_usd` number - `applies_to` string - `note` string: How to read the values (always present since 2026-09-21: eligibility-specific when no rows exist, a completeness caveat when they do). ## Other responses - `400`: Invalid mint or params - `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`. - `403`: Forbidden. One of: the key's tier is below this endpoint's or parameter's gate (`tier_required` with an `upgrade` block); the public demo key used outside its allow-list (`demo_key_endpoint_not_allowed`); an invalid or revoked key; an origin-restricted key called from a disallowed origin (`code` `origin_not_allowed` / `origin_required`). `X-RateLimit-*` headers are present only on `tier_required`. - `429`: Too many requests. Every 429 carries `Retry-After`. A quota 429 (`rate_limit_exceeded`, with `X-RateLimit-*`), a heavy-query concurrency 429 (`error_kind` `concurrency`/`capacity`), or the per-IP authentication-failure block (30 failed auths/min; plain `error` + `retry_after_seconds`, no `X-RateLimit-*`). - `500`: Unexpected server error from the route (`Internal server error`, with `_rid`). Safe to retry with backoff. A failed API-key lookup is a 503 `auth_backend_unavailable`, never a 500. - `503`: Temporarily unavailable — a Postgres statement timeout while the dataset is under load or maintenance (`statement_timeout`, with `X-RateLimit-*` and `_rid`), or the API-key lookup itself unavailable (`auth_backend_unavailable`, authentication stage: no `X-RateLimit-*`, no `_rid`, not counted as a failed authentication). Always carries `Retry-After`; honour it. --- [API](https://skmtc.dev/madeonsol/apis/madeonsol-api.md) · [All operations](https://skmtc.dev/madeonsol/apis/madeonsol-api/llms.txt) · [OpenAPI document](https://skmtc.dev/madeonsol/apis/madeonsol-api/revisions/96ce84657f55?raw)