This method returns at most 2,000 fills per response and only the 10,000 most recent fills are available. For larger history, query the hyperliquid_trades table via SQL Explorer.

Parameters

type

string

REQUIRED

Request type identifier specifying 'userFillsByTime' as the info endpoint method to retrieve time-filtered trade execution history

user

string

REQUIRED

Ethereum-compatible wallet address in 42-character hexadecimal format (0x...) of the trader whose fills you want to query within a specific time range

startTime

integer

REQUIRED

Query start time as Unix timestamp in milliseconds (inclusive lower bound). Only fills at or after this time will be returned. Use Date.now() in JavaScript or time.time()*1000 in Python to generate timestamps

endTime

integer

Query end time as Unix timestamp in milliseconds (inclusive upper bound). Only fills at or before this time will be returned. Optional parameter that defaults to current server time if not specified, allowing open-ended queries

aggregateByTime

boolean

Optional aggregation flag to consolidate partial fills that occurred at the same timestamp. When true, combines multiple fill events from crossing orders that matched against multiple resting orders, providing cleaner execution summaries. Defaults to false for granular fill data.

Returns

array

array

Array of fill objects with trade execution details

coin

string

Trading pair identifier using standard symbols for perpetuals (e.g., 'BTC', 'ETH', 'SOL') or @index notation for spot markets (e.g., '@107'). Identifies which asset the fill executed on

px

string

Fill execution price at which the trade was executed. Returned as string to preserve full decimal precision for accurate PnL and accounting calculations (e.g., '43250.5' for BTC)

sz

string

Fill quantity representing the size of this specific execution. For partial fills, this is the portion filled in this transaction. Returned as string to maintain precision for fractional quantities

side

string

Order side indicator: 'A' for Ask (sell/short position) or 'B' for Bid (buy/long position). Represents the taker side of the trade execution

time

integer

Unix timestamp in milliseconds indicating when this fill executed. Use Date.now() in JavaScript or time.time()*1000 in Python for comparison with current time

oid

integer

Unique order identifier linking this fill to the parent order. Multiple fills can share the same oid when an order executes in partial fills

tid

integer

Unique trade identifier for this specific fill execution. Each individual fill has a distinct tid for transaction tracking and reconciliation

startPosition

string

Position size immediately before this fill executed, showing the account's exposure in this asset prior to the trade. Positive values indicate long positions, negative indicate short positions. Returned as string for precision

dir

string

Human-readable trade direction describing position impact: 'Open Long' (new long), 'Close Short' (reducing short), 'Add Long' (increasing long), 'Close Long' (reducing long), 'Open Short' (new short), 'Add Short' (increasing short). For spot: 'Buy' or 'Sell'

closedPnl

string

Realized profit and loss from this fill in USDC. Positive values indicate profit, negative indicate loss. Only applies when reducing or closing positions. Returned as string to preserve decimal precision for accounting accuracy

fee

string

Trading fee charged for this fill, typically calculated as a percentage of notional value. Negative values indicate rebates (maker fees), positive values are fees paid (taker fees). Amount denominated in feeToken currency

feeToken

string

Token denomination for the trading fee, typically 'USDC' on Hyperliquid. Indicates which asset the fee amount is denominated in

builderFee

string

Optional additional fee paid to order flow providers or builders when applicable. Only present in response if non-zero. Represents MEV or builder compensation in USDC

hash

string

Blockchain transaction hash in hexadecimal format for on-chain verification and block explorer lookups. Can be used to trace the fill on Hyperliquid's blockchain

crossed

boolean

Indicates whether this was a crossing (taker) order that immediately matched against resting liquidity (true) or a resting (maker) order that provided liquidity and was matched later (false). Affects fee rates and rebates

twapId

string | null

Optional TWAP identifier used for time-weighted average price execution. Null if not applicable

Request

1
curl https://docs-demo.hype-mainnet.quiknode.pro/evm \
2
  -X POST \
3
  -H "Content-Type: application/json" \
4
  --data '{"type":"userFillsByTime","user":"0x31ca8395cf837de08b24da3f660e77761dfb974b","startTime":1683849600000}'
5

1
curl https://docs-demo.hype-mainnet.quiknode.pro/evm \
2
  -X POST \
3
  -H "Content-Type: application/json" \
4
  --data '{"type":"userFillsByTime","user":"0x31ca8395cf837de08b24da3f660e77761dfb974b","startTime":1683849600000}'
5

1
var myHeaders = new Headers();
2
myHeaders.append("Content-Type", "application/json");
3

4
var raw = JSON.stringify({
5
  "type": "userFillsByTime",
6
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
7
  "startTime": 1683849600000
8
});
9

10
var requestOptions = {
11
  method: 'POST',
12
  headers: myHeaders,
13
  body: raw,
14
  redirect: 'follow'
15
};
16

17
fetch("https://docs-demo.hype-mainnet.quiknode.pro/evm", requestOptions)
18
  .then(response => response.text())
19
  .then(result => console.log(result))
20
  .catch(error => console.log('error', error));
21

1
var myHeaders = new Headers();
2
myHeaders.append("Content-Type", "application/json");
3

4
var raw = JSON.stringify({
5
  "type": "userFillsByTime",
6
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
7
  "startTime": 1683849600000
8
});
9

10
var requestOptions = {
11
  method: 'POST',
12
  headers: myHeaders,
13
  body: raw,
14
  redirect: 'follow'
15
};
16

17
fetch("https://docs-demo.hype-mainnet.quiknode.pro/evm", requestOptions)
18
  .then(response => response.text())
19
  .then(result => console.log(result))
20
  .catch(error => console.log('error', error));
21

1
import requests
2
import json
3

4
url = "https://docs-demo.hype-mainnet.quiknode.pro/evm"
5

6
payload = json.dumps({
7
  "type": "userFillsByTime",
8
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
9
  "startTime": 1683849600000
10
})
11
headers = {
12
  'Content-Type': 'application/json'
13
}
14

15
response = requests.request("POST", url, headers=headers, data=payload)
16

17
print(response.text)
18

1
import requests
2
import json
3

4
url = "https://docs-demo.hype-mainnet.quiknode.pro/evm"
5

6
payload = json.dumps({
7
  "type": "userFillsByTime",
8
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
9
  "startTime": 1683849600000
10
})
11
headers = {
12
  'Content-Type': 'application/json'
13
}
14

15
response = requests.request("POST", url, headers=headers, data=payload)
16

17
print(response.text)
18

1
require 'uri'
2
require 'net/http'
3
require 'json'
4

5
url = URI("https://docs-demo.hype-mainnet.quiknode.pro/evm")
6

7
http = Net::HTTP.new(url.host, url.port)
8
http.use_ssl = true
9

10
request = Net::HTTP::Post.new(url)
11
request["Content-Type"] = 'application/json'
12
request.body = JSON.dump({
13
  "type": "userFillsByTime",
14
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
15
  "startTime": 1683849600000
16
})
17

18
response = http.request(request)
19
puts response.read_body
20

1
require 'uri'
2
require 'net/http'
3
require 'json'
4

5
url = URI("https://docs-demo.hype-mainnet.quiknode.pro/evm")
6

7
http = Net::HTTP.new(url.host, url.port)
8
http.use_ssl = true
9

10
request = Net::HTTP::Post.new(url)
11
request["Content-Type"] = 'application/json'
12
request.body = JSON.dump({
13
  "type": "userFillsByTime",
14
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
15
  "startTime": 1683849600000
16
})
17

18
response = http.request(request)
19
puts response.read_body
20

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free