> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Timerange

> Transactions of tracked wallets within a recent time window, up to 60 minutes back, newest first, each with trader profile and position.

The same trade feed as Latest, but bounded to a recent time window instead of a count. Specify how far back to look with seconds and minutes, and get every tracked transaction in that window, newest first.

Use it to fetch all trades in the last N minutes for polling style updates, for example every 30 seconds pull the last 30 seconds of activity.

<Tip>
  The window is built from seconds and minutes, summed. The maximum window is 60 minutes, larger requests are capped and a warning is added. Optionally filter by mint to bound the window to a single token.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain. One of solana, bnb, base, eth.
</ParamField>

<ParamField query="type" type="string" required>
  Wallet category kol, smart or whale.
</ParamField>

<ParamField query="seconds" type="integer">
  Seconds to look back. Combined with minutes.
</ParamField>

<ParamField query="minutes" type="integer">
  Minutes to look back. Combined with seconds. Maximum total window is 60 minutes.
</ParamField>

<ParamField query="mint" type="string">
  Optional token mint to filter the window to a single token. Adds a token block.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of transactions to return.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key. Alternatively pass it as an Authorization Bearer header.
</ParamField>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cabalspy.xyz/v1/transactions/timerange?blockchain=solana&type=kol&minutes=5&api_key=YOUR_KEY"
  ```

  ```python Python theme={null}
  import requests

  params = {"blockchain": "solana", "type": "kol", "minutes": 5, "api_key": "YOUR_KEY"}
  r = requests.get("https://api.cabalspy.xyz/v1/transactions/timerange", params=params)
  d = r.json()["data"]

  print("window seconds", d["time_window_seconds"], "count", d["count"])
  for tx in d["transactions"]:
      print(tx["created_at"], tx["transaction_type"], tx["value"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana", type: "kol", minutes: "5", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/transactions/timerange?${p}`);
  const { data } = await res.json();
  console.log("window", data.time_window_seconds, "count", data.count);
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="blockchain" type="string">
      Requested chain.
    </ResponseField>

    <ResponseField name="type" type="string">
      Requested wallet type.
    </ResponseField>

    <ResponseField name="mode" type="string">
      timerange.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Native currency.
    </ResponseField>

    <ResponseField name="time_window_seconds" type="integer">
      The effective window in seconds, after capping.
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of transactions in the window.
    </ResponseField>

    <ResponseField name="token" type="object">
      Only present when mint is passed. Token block with mint, token\_name, blockchain, currency, token\_supply, token\_decimals.
    </ResponseField>

    <ResponseField name="transactions" type="array">
      Same transaction shape as the Latest endpoint (tx\_signature, mint, token\_name, transaction\_type, value, value\_usd, token\_amount, price\_per\_token, created\_at, profile, holdings\_after).
    </ResponseField>

    <ResponseField name="warnings" type="array">
      Present only if the requested window exceeded the 60 minute maximum and was capped.
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Standard pagination object.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "blockchain": "solana",
      "type": "kol",
      "mode": "timerange",
      "currency": "SOL",
      "time_window_seconds": 300,
      "count": 1,
      "transactions": [
        {
          "tx_signature": "5xr8abc...",
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "token_supply": 1000000000,
          "token_decimals": 6,
          "transaction_type": "buy",
          "value": 1.66,
          "value_usd": 137.44,
          "currency": "SOL",
          "token_amount": 22113972.03,
          "price_per_token": 7.5e-8,
          "price_per_token_usd": 6.2e-6,
          "created_at": "2026-07-04 16:25:34",
          "profile": {
            "name": "Maze",
            "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
            "twitter": "https://x.com/MazeCCC",
            "telegram": "",
            "blockchain": "solana",
            "currency": "SOL",
            "type": "kol"
          },
          "holdings_after": {
            "token_amount": 22113972.03,
            "token_amount_peak": 22113972.03,
            "supply_pct": 2.211397,
            "supply_pct_peak": 2.211397,
            "bag_pct": 100.0,
            "still_holding": true
          }
        }
      ]
    },
    "pagination": {
      "limit": 50,
      "total": 1,
      "has_more": false,
      "next_cursor": null
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code               | Meaning                                |
| ------ | ------------------ | -------------------------------------- |
| 400    | invalid\_parameter | blockchain or type missing or invalid. |
| 401    | unauthorized       | API key missing.                       |
| 403    | forbidden          | API key invalid or credits exhausted.  |
| 429    | rate\_limited      | Rate limit exceeded.                   |