userCompletedTradesByTime | Hyperliquid Info API
Info API
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.
POST
userCompletedTradesByTime | Hyperliquid Info API
Credit Cost
10 per call
Processing
Realtime
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.
- GoldRush custom analytics product. Not available on the public Hyperliquid node - there is no
POST api.hyperliquid.xyz/infoequivalent. Served only fromPOST 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_timeand 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 thanlimitrecords return. startTimeis required unless acursoris supplied. Returns up tolimitrecords per page (default100, max500).- For the latest N trades without a window, use
userCompletedTrades. For one aggregate roll-up, useuserPnlSummary.
close_time falls in a [startTime, endTime] window, ordered oldest-first. Each record has the same shape as userCompletedTrades 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
Request
string
default:"userCompletedTradesByTime"
required
Always
"userCompletedTradesByTime".string
required
The wallet address (lowercase 0x-prefixed hex).
int
required
Unix timestamp in milliseconds. Inclusive lower bound on
close_time. Required unless a cursor is supplied.int
Unix timestamp in milliseconds. Inclusive upper bound on
close_time. Defaults to current server time when omitted.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.string
Optional filter. When set, returns only trades whose closing fill was routed through this builder address (
0x-prefixed 42-character hex).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.int
Maximum number of records per page. Default
100, maximum 500. Values above the maximum are clamped.Example
Response
An array of completed-trade objects, oldest-first by(close_time, tx_index).
Field descriptions
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.string
The wallet address the trades belong to (lowercase 0x-prefixed hex), echoing the request.
string
Asset symbol - e.g.
"BTC", "ETH" for perps; HIP-3 markets use the dex:SYM form (e.g. "xyz:GOLD").string
Direction of the round-trip position -
"Long" or "Short".string
Realized trading PnL for the round-trip in USDC, before fees and funding.
string
Net realized PnL in USDC -
gross_pnl minus fees plus funding_pnl.string
Funding component of the round-trip in USDC (negative = paid, positive = received).
string
Volume-weighted average entry price across the opening fills (carried at 10 decimal places, then trimmed of trailing zeros).
string
Volume-weighted average exit price across the closing fills (carried at 10 decimal places, then trimmed of trailing zeros).
string
Peak absolute position size reached during the round-trip - the same value as
max_position_size.string
Total trading fees paid across all fills in the round-trip, in USDC.
int
Total number of fills that make up the round-trip (opening and closing).
int
Unix timestamp in milliseconds of the first opening fill.
int
Unix timestamp in milliseconds of the closing fill that brought the position flat.
int
Round-trip duration in milliseconds -
close_time minus open_time.string
Peak absolute position size reached during the round-trip.
int
Number of fills in the round-trip that were on the maker side.
string | null
Builder address routed through by the closing fill (
0x-prefixed hex), or null when the closing fill carried no builder code.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
userCompletedTrades
fetch a wallet’s most recent fully-closed round-trip trades, newest-first, with realized PnL, funding, and fees.
userPnlSummary
fetch one aggregate PnL summary for a wallet - realized PnL, win/loss rate, volume, fees, funding, and traded pairs.
userFills
fetch a user’s most recent trade fills without specifying a time window.
userFunding
fetch a user’s per-coin funding payment history within a time window for funding-only P&L attribution.