> 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)
```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"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://cabalspy.gitbook.io/cabalspy-docs/trade-activity/transactions-by-time-range.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.