> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/historical-data/tradesbytime.md).

# tradesByTime

Market trades of the last 24 hours, in the WebSocket trades shape, by time, optionally filtered by coin.

Market trades of the last 24 hours. Each trade is exactly what the [trades](/readme/websocket/trades-data/trades.md) WebSocket channel sent for it, so a client can backfill a gap in its stream and get identical objects.

## POST Request

<table><thead><tr><th width="180">Field</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Required. <code>"tradesByTime"</code></td></tr><tr><td><code>startTime</code></td><td>number</td><td>Required unless <code>cursor</code> is given. Inclusive, milliseconds. A value older than 24 hours is moved forward to 24 hours ago.</td></tr><tr><td><code>endTime</code></td><td>number</td><td>Optional. Inclusive, milliseconds. Default: now.</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Optional. The <code>cursor</code> from the previous response. Pass it back unchanged. A cursor older than 24 hours resumes at 24 hours ago.</td></tr><tr><td><code>coin</code></td><td>string</td><td>Optional. Only trades on this coin, e.g. <code>"BTC"</code>, <code>"xyz:GOLD"</code>, <code>"@107"</code>, <code>"#40080"</code>.</td></tr><tr><td><code>dex</code></td><td>string</td><td>Optional. <code>"main_dex"</code> or a HIP-3 dex such as <code>"xyz"</code>.</td></tr><tr><td><code>limit</code></td><td>number</td><td>Optional. Default and maximum 2000.</td></tr></tbody></table>

Trades are returned oldest-first, in the order the WebSocket sent them. A range that lies entirely before the last 24 hours returns no trades.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "tradesByTime",
    "coin": "BTC",
    "startTime": 1786000000000,
    "limit": 100
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

resp = requests.post(
    "https://api.hydromancer.xyz/info",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "tradesByTime",
        "coin": "BTC",
        "startTime": 1786000000000,
        "limit": 100,
    },
)
page = resp.json()
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const resp = await fetch("https://api.hydromancer.xyz/info", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": "YOUR_API_KEY" },
  body: JSON.stringify({
    type: "tradesByTime",
    coin: "BTC",
    startTime: 1786000000000,
    limit: 100,
  }),
});
const page = await resp.json();
```

{% endtab %}
{% endtabs %}

***

## Pagination

While `hasMore` is `true`, repeat the request with the response's `cursor` instead of `startTime`. On the last page `hasMore` is `false` and `cursor` is absent.

The cursor is opaque. Trades carry no field it could be built from, because a mirrored outcome trade and the trade it mirrors share every field the WebSocket sends.

## Response Fields

| Field     | Type    | Description                                       |
| --------- | ------- | ------------------------------------------------- |
| `trades`  | array   | Trades, each in the WebSocket `trades` shape      |
| `hasMore` | boolean | `true` when another page follows                  |
| `cursor`  | string  | Pass to the next request. Absent on the last page |

Each trade:

| Field   | Type   | Description                                |
| ------- | ------ | ------------------------------------------ |
| `coin`  | string | Coin                                       |
| `side`  | string | The taker's side: `"B"` bought, `"A"` sold |
| `px`    | string | Price                                      |
| `sz`    | string | Size                                       |
| `hash`  | string | Transaction hash                           |
| `time`  | number | Block time, milliseconds                   |
| `tid`   | number | Trade id                                   |
| `users` | array  | `[buyer, seller]`                          |

On outcome markets a trade on one side also appears on the other side's coin, at `1 − px` with the side and the users swapped, as on the WebSocket.

<details>

<summary>Response</summary>

```json
{
  "trades": [
    {
      "coin": "BTC",
      "side": "B",
      "px": "64000.0",
      "sz": "0.1",
      "hash": "0x...",
      "time": 1786000001000,
      "tid": 20001,
      "users": [
        "0x0000000000000000000000000000000000000001",
        "0x0000000000000000000000000000000000000002"
      ]
    }
  ],
  "hasMore": true,
  "cursor": "1786000001000_812345678_0"
}
```

</details>