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

# userCompletedTradesByTime | Hyperliquid Info API

> Hyperliquid userCompletedTradesByTime: fetch a wallet's fully-closed round-trip trades within a close-time window, oldest-first, with a keyset cursor for forward paging.

> [card] Credit Cost
>
> 10 per call

> [card] Processing
>
> Realtime

The Hyperliquid info endpoint with `type: "userCompletedTradesByTime"` is used to fetch a wallet's fully-closed round-trip trades within a close-time window, oldest-first, with a keyset cursor for forward paging.

> [!TIP]
>
> Estimate your monthly cost for this API using the [Pricing Calculator](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-completed-trades-by-time).

> [!NOTE]
>
> * GoldRush custom analytics product. **Not available on the public Hyperliquid node** - there is no `POST api.hyperliquid.xyz/info` equivalent. Served only from `POST hypercore.goldrushdata.com/info`.
> * Each record is one **fully-closed round-trip position** (opened, then brought fully flat), reconstructed from the wallet's fills, windowed on `close_time` and returned **oldest-first**.
> * Page forward with the keyset `cursor`: pass `"{close_time}_{tx_index}"` built from the **last row** of the previous page to fetch the next page. Repeat until fewer than `limit` records return.
> * `startTime` is required unless a `cursor` is supplied. Returns up to `limit` records per page (default `100`, max `500`).
> * For the latest N trades without a window, use [`userCompletedTrades`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-completed-trades). For one aggregate roll-up, use [`userPnlSummary`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-pnl-summary).

Returns a wallet's fully-closed round-trip trades whose `close_time` falls in a `[startTime, endTime]` window, ordered **oldest-first**. Each record has the same shape as [`userCompletedTrades`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-completed-trades) plus a `tx_index` ordinal. Use this to walk a wallet's full trade history forward in time - PnL recaps, tax-lot reconstruction, or backfills - paging with the keyset `cursor` rather than the latest N records.

User-keyed. GoldRush-native, so there is no upstream Hyperliquid `/info` equivalent.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
```

## Request

**type** `string` *required* (default: userCompletedTradesByTime)

Always `"userCompletedTradesByTime"`.

**user** `string` *required*

The wallet address (lowercase 0x-prefixed hex).

**startTime** `int` *required*

Unix timestamp in milliseconds. Inclusive lower bound on `close_time`. Required unless a `cursor` is supplied.

**endTime** `int`

Unix timestamp in milliseconds. Inclusive upper bound on `close_time`. Defaults to current server time when omitted.

**cursor** `string`

Pagination cursor in the form `"{close_time}_{tx_index}"`. When set, returns records strictly after this keyset (still oldest-first). Build it from the `close_time` and `tx_index` of the **last row** in the previous page.

**builder** `string`

Optional filter. When set, returns only trades whose closing fill was routed through this builder address (`0x`-prefixed 42-character hex).

**dex** `string`

Optional perp-DEX scope. `main_dex` for the canonical Hyperliquid perp DEX, or a HIP-3 DEX identifier. Omit to include trades across every DEX.

**limit** `int`

Maximum number of records per page. Default `100`, maximum `500`. Values above the maximum are clamped.

### Example

```bash cURL theme={null}
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userCompletedTradesByTime",
    "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "startTime": 1735689600000
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://hypercore.goldrushdata.com/info", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "userCompletedTradesByTime",
    user: "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    startTime: 1735689600000,
  }),
});

const trades = await response.json();

// Page forward: build the next cursor from the last row.
const last = trades[trades.length - 1];
const cursor = `${last.close_time}_${last.tx_index}`;
```

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

response = requests.post(
    "https://hypercore.goldrushdata.com/info",
    headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
    json={
        "type": "userCompletedTradesByTime",
        "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "startTime": 1735689600000,
    },
)

trades = response.json()

# Page forward: build the next cursor from the last row.
last = trades[-1]
cursor = f"{last['close_time']}_{last['tx_index']}"
```

## Response

An array of completed-trade objects, oldest-first by `(close_time, tx_index)`.

```json theme={null}
[
  {
    "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "coin": "BTC",
    "position_type": "Long",
    "gross_pnl": "505.25",
    "net_pnl": "498.11",
    "funding_pnl": "0.98",
    "entry_px": "63642.5",
    "exit_px": "64150.75",
    "position_closed_size": "1.0171",
    "fees": "8.12",
    "fills": 12,
    "open_time": 1735689600000,
    "close_time": 1735776000000,
    "duration_ms": 86400000,
    "max_position_size": "1.0171",
    "maker_fills": 4,
    "builder": null,
    "tx_index": 0
  }
]
```

### Field descriptions

> [!NOTE]
>
> The PnL, price, size, and fee fields (`gross_pnl`, `net_pnl`, `funding_pnl`, `entry_px`, `exit_px`, `position_closed_size`, `fees`, `max_position_size`) are returned as **decimal strings**, preserving full precision. Counts (`fills`, `maker_fills`, `tx_index`) and timestamps (`open_time`, `close_time`, `duration_ms`) are JSON numbers. Do not parse the decimal strings as floats - keep them as strings or use a fixed-precision decimal type.

**user** `string`

The wallet address the trades belong to (lowercase 0x-prefixed hex), echoing the request.

**coin** `string`

Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; HIP-3 markets use the `dex:SYM` form (e.g. `"xyz:GOLD"`).

**position\_type** `string`

Direction of the round-trip position - `"Long"` or `"Short"`.

**gross\_pnl** `string`

Realized trading PnL for the round-trip in USDC, before fees and funding.

**net\_pnl** `string`

Net realized PnL in USDC - `gross_pnl` minus `fees` plus `funding_pnl`.

**funding\_pnl** `string`

Funding component of the round-trip in USDC (negative = paid, positive = received).

**entry\_px** `string`

Volume-weighted average entry price across the opening fills (carried at 10 decimal places, then trimmed of trailing zeros).

**exit\_px** `string`

Volume-weighted average exit price across the closing fills (carried at 10 decimal places, then trimmed of trailing zeros).

**position\_closed\_size** `string`

Peak absolute position size reached during the round-trip - the same value as `max_position_size`.

**fees** `string`

Total trading fees paid across all fills in the round-trip, in USDC.

**fills** `int`

Total number of fills that make up the round-trip (opening and closing).

**open\_time** `int`

Unix timestamp in milliseconds of the first opening fill.

**close\_time** `int`

Unix timestamp in milliseconds of the closing fill that brought the position flat.

**duration\_ms** `int`

Round-trip duration in milliseconds - `close_time` minus `open_time`.

**max\_position\_size** `string`

Peak absolute position size reached during the round-trip.

**maker\_fills** `int`

Number of fills in the round-trip that were on the maker side.

**builder** `string | null`

Builder address routed through by the closing fill (`0x`-prefixed hex), or `null` when the closing fill carried no builder code.

**tx\_index** `int`

Per-`(user, close_time)` ordinal (0-based) that disambiguates trades sharing a `close_time`. Combine with `close_time` as `"{close_time}_{tx_index}"` to build the next-page `cursor`. This is a GoldRush paging ordinal, not Hyperliquid's block transaction index.

## Related endpoints

> [card] [userCompletedTrades](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-completed-trades.md)
>
> fetch a wallet's most recent fully-closed round-trip trades, newest-first, each with realized PnL, funding, fees, and volume-weighted entry/exit prices.

> [card] [userFillsByTime](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-fills-by-time.md)
>
> fetch a user’s trade fills within a time window for P\&L recaps and tax ledger reconstruction.

> [card] [userTwapSliceFillsByTime](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-twap-slice-fills-by-time.md)
>
> fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic orders.

> [card] [userAbstraction](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-abstraction.md)
>
> fetch a user's account-abstraction mode.

See all Hyperliquid endpoints: [Overview hub](https://goldrush.dev/docs/goldrush-hyperliquid/overview.md) · [Info API reference](https://goldrush.dev/docs/goldrush-hyperliquid/info-api/overview.md)

*Last reviewed: 2026-08-17*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.