userFillsByTime

Commonly used to fetch a user’s trade fills within a specific time window for P&L recaps, tax ledger reconstruction, or post-deploy backfill.

POST /info

userFillsByTime

cURL

curl --request POST \
  --url https://hypercore.goldrushdata.com/info \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "user": "<string>",
  "startTime": 123,
  "endTime": 123,
  "aggregateByTime": true
}
'

200

{
  "coin": "<string>",
  "px": "<string>",
  "sz": "<string>",
  "side": "<string>",
  "time": 123,
  "startPosition": "<string>",
  "dir": "<string>",
  "closedPnl": "<string>",
  "hash": "<string>",
  "oid": 123,
  "tid": 123,
  "crossed": true,
  "fee": "<string>",
  "feeToken": "<string>",
  "builderFee": "<string>",
  "twapId": {},
  "cloid": {}
}

Credit Cost

1 per call

Processing

Realtime

• Wire-equal to POST api.hyperliquid.xyz/info with {"type": "userFillsByTime", "user": "...", "startTime": ...}.
• Each response contains at most 2,000 fills; widen the window in chunks if you need more. Hyperliquid retains only the 10,000 most recent fills per wallet.
• For real-time push instead of windowed polling, subscribe to walletTxs and read HypercoreFillTransaction events.
• Use userFills (no Time suffix) when you only need the most recent N fills without specifying a window.

Returns a single user’s fills bounded by a [startTime, endTime) window in milliseconds. Use this when you want fills since a specific moment - daily P&L recaps, post-deploy backfills, or rebuilding a tax ledger - rather than the most recent N fills.

User-keyed. The upstream Hyperliquid API caps each response at 2,000 fills and only retains the 10,000 most recent fills per wallet; window queries that span more than that are truncated.

Endpoint

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

Request

type · string · default: "userFillsByTime" · required

Always "userFillsByTime".

user · string · required

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

startTime · int · required

Unix timestamp in milliseconds. Inclusive lower bound.

endTime · int

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

aggregateByTime · boolean

When true, partial fills sharing the same timestamp are consolidated into one row. Default false.

Example

cURL

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

Response

An array of fill objects ordered by time.

[
  {
    "coin": "BTC",
    "px": "43250.5",
    "sz": "0.1",
    "side": "B",
    "time": 1735689600000,
    "startPosition": "0",
    "dir": "Open Long",
    "closedPnl": "0",
    "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a",
    "oid": 95012345,
    "tid": 678900012345,
    "crossed": true,
    "fee": "2.16",
    "feeToken": "USDC"
  }
]

Field descriptions

All numeric fields (px, sz, startPosition, closedPnl, fee, builderFee) are returned as decimal strings, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type.

coin · string

Asset symbol - e.g. "BTC", "ETH" for perps; spot pairs use the @N form (e.g. "@107").

px · string

Fill execution price.

sz · string

Fill size.

side · string

"B" for buy/long, "A" for ask/short.

time · int

Unix timestamp in milliseconds when the fill executed.

startPosition · string

Signed position size on the same coin immediately before this fill.

dir · string

Human-readable direction label - e.g. "Open Long", "Close Short", "Buy", "Sell".

closedPnl · string

Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position).

hash · string

L1 transaction hash that included this fill.

oid · int

Parent order ID.

tid · int

Unique trade ID.

crossed · boolean

true when the fill came from the taker side of the order, false when it was the maker side.

fee · string

Trading fee paid for this fill, denominated in feeToken.

feeToken · string

Symbol the fee was paid in - typically "USDC".

builderFee · string

Optional. Builder fee paid for this fill if the order routed through a builder code.

twapId · int | null

Optional TWAP order ID if this fill is a slice of a TWAP order.

cloid · string | null

Optional client order ID if one was set at order placement.