> For the complete documentation index, see [llms.txt](https://cabalspy.gitbook.io/cabalspy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cabalspy.gitbook.io/cabalspy-docs/trade-activity/transactions-by-time-range.md).

# Transactions by Time Range

All buys and sells from tracked smart money, KOL and whale wallets within a time window on Solana, BNB Chain, Base and Ethereum — each with the wallet profile and its balance (incl. all-time peaks) after the trade.

## Token Transactions by Time Range — Smart Money & KOL Buys and Sells

> Returns every transaction of tracked smart money, KOL and whale wallets within a time window for one chain and wallet type on Solana, BNB Chain, Base or Ethereum — newest first. Each transaction carries the full token detail, the wallet \`profile\` and \`holdings\_after\` (balance after the trade, including all-time peaks that survive a full sell-off). Add \`\&mint=\` to restrict to a single token; the response then also includes a top-level \`token\` block.\
> \
> \*\*Time window\*\* — set \`seconds\` and/or \`minutes\`; they add up. The window is capped at 60 minutes. If you request more, results are capped and a note is added to the \`warnings\` array (data is still returned). The applied window is echoed back as \`time\_window\_seconds\`.\
> \
> \*\*Data source\*\* — transactions come straight from the per-chain, per-type live trade index (sorted by timestamp). Per-trade \`holdings\_after\` is sourced from the token holder cache (chronological replay from the database), so all-time peaks are preserved even after a wallet sells out. Historical USD comes from each trade; a very old trade without a stored USD value falls back to the current native price.\
> \
> \*\*Parameters / settings\*\*\
> \- \`blockchain\` (required) — one of: \`solana\`, \`bnb\`, \`base\`, \`eth\`\
> \- \`type\` (required) — \`kol\`, \`smart\`, or \`whale\` (availability per chain:\
>   solana → kol/smart/whale; bnb → kol/smart; base → kol/smart; eth → kol)\
> \
> \- \`seconds\` / \`minutes\` (optional) — time window, capped at 60 minutes\
> \- \`mint\` (optional) — restrict to one token mint / contract address\
> \- \`limit\` (optional, default \`50\`) — maximum number of transactions returned\
> \- \`api\_key\` (optional if the Bearer header is used)<br>

```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Transactions by Time Range","version":"1.0.0"},"tags":[{"name":"Transactions by Time Range","description":"All buys and sells from tracked smart money, KOL and whale wallets within a time window on Solana, BNB Chain, Base and Ethereum — each with the wallet profile and its balance (incl. all-time peaks) after the trade.\n"}],"servers":[{"url":"https://api.cabalspy.xyz"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"}},"schemas":{"TimeRangeTransactionsEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"blockchain":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"},"currency":{"type":"string"},"time_window_seconds":{"type":"integer","description":"The applied time window in seconds."},"count":{"type":"integer","description":"Number of transactions in this response."},"token":{"type":"object","description":"Only present when filtered with mint."},"transactions":{"type":"array","description":"Newest first within the window. Each item has tx_signature, mint, token_name, token_supply, token_decimals, transaction_type (buy/sell), value, value_usd (historical, nullable), currency, token_amount, price_per_token, price_per_token_usd, created_at, the wallet profile and holdings_after (balance + all-time peaks).\n","items":{"type":"object"}},"warnings":{"type":"array","description":"Present when the time window or limit was capped.","items":{"type":"string"}}}},"meta":{"type":"object"},"pagination":{"type":"object"}}},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"docs":{"type":"string"}}}}}}},"paths":{"/v1/transactions/timerange":{"get":{"tags":["Transactions by Time Range"],"summary":"Token Transactions by Time Range — Smart Money & KOL Buys and Sells","operationId":"getTransactionsByTimeRange","description":"Returns every transaction of tracked smart money, KOL and whale wallets within a time window for one chain and wallet type on Solana, BNB Chain, Base or Ethereum — newest first. Each transaction carries the full token detail, the wallet `profile` and `holdings_after` (balance after the trade, including all-time peaks that survive a full sell-off). Add `&mint=` to restrict to a single token; the response then also includes a top-level `token` block.\n\n**Time window** — set `seconds` and/or `minutes`; they add up. The window is capped at 60 minutes. If you request more, results are capped and a note is added to the `warnings` array (data is still returned). The applied window is echoed back as `time_window_seconds`.\n\n**Data source** — transactions come straight from the per-chain, per-type live trade index (sorted by timestamp). Per-trade `holdings_after` is sourced from the token holder cache (chronological replay from the database), so all-time peaks are preserved even after a wallet sells out. Historical USD comes from each trade; a very old trade without a stored USD value falls back to the current native price.\n\n**Parameters / settings**\n- `blockchain` (required) — one of: `solana`, `bnb`, `base`, `eth`\n- `type` (required) — `kol`, `smart`, or `whale` (availability per chain:\n  solana → kol/smart/whale; bnb → kol/smart; base → kol/smart; eth → kol)\n\n- `seconds` / `minutes` (optional) — time window, capped at 60 minutes\n- `mint` (optional) — restrict to one token mint / contract address\n- `limit` (optional, default `50`) — maximum number of transactions returned\n- `api_key` (optional if the Bearer header is used)\n","parameters":[{"name":"blockchain","in":"query","required":true,"schema":{"type":"string","enum":["solana","bnb","base","eth"]}},{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["kol","smart","whale"]}},{"name":"minutes","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"seconds","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"mint","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns all transactions within the requested time window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRangeTransactionsEnvelope"}}}},"400":{"description":"Missing or invalid parameter (e.g. `type` or `blockchain`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Invalid or exhausted API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```