Perps - Wallet Trade Fills
curl --request POST \
--url https://public-api.birdeye.so/perps/v1/wallet/trade_fills \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"wallet": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
"sort_type": "desc",
"limit": 1,
"cursor": "MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3"
}
'import requests
url = "https://public-api.birdeye.so/perps/v1/wallet/trade_fills"
payload = {
"wallet": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
"sort_type": "desc",
"limit": 1,
"cursor": "MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
wallet: '0x5b5d51203a0f9079f8aeb098a6523a13f298c060',
sort_type: 'desc',
limit: 1,
cursor: 'MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3'
})
};
fetch('https://public-api.birdeye.so/perps/v1/wallet/trade_fills', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"data": [
{
"time": 1789343885,
"hash": "0x1ac3874b7d5799501c3d044458a8ad0205540031185ab822be8c329e3c5b733a",
"token": "PUMP",
"side": "Buy",
"direction": "Close Short",
"size": 2881240,
"volume_usd": 9997.9028,
"start_position": -3411528597,
"closed_pnl": 3275.96988,
"fee_value": 2.099559,
"price": 0.00347
}
],
"nextCursor": "MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3"
},
"success": true
}{
"success": false,
"message": "Bad request"
}{
"success": false,
"message": "Unauthorized"
}{
"success": false,
"message": "Access Denied"
}{
"success": false,
"message": "Too many requests"
}{
"success": false,
"message": "Internal Server Error"
}Perps Wallet
Perps Wallet Trade Fills
POST
/
perps
/
v1
/
wallet
/
trade_fills
Perps - Wallet Trade Fills
curl --request POST \
--url https://public-api.birdeye.so/perps/v1/wallet/trade_fills \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"wallet": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
"sort_type": "desc",
"limit": 1,
"cursor": "MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3"
}
'import requests
url = "https://public-api.birdeye.so/perps/v1/wallet/trade_fills"
payload = {
"wallet": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
"sort_type": "desc",
"limit": 1,
"cursor": "MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
wallet: '0x5b5d51203a0f9079f8aeb098a6523a13f298c060',
sort_type: 'desc',
limit: 1,
cursor: 'MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3'
})
};
fetch('https://public-api.birdeye.so/perps/v1/wallet/trade_fills', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"data": [
{
"time": 1789343885,
"hash": "0x1ac3874b7d5799501c3d044458a8ad0205540031185ab822be8c329e3c5b733a",
"token": "PUMP",
"side": "Buy",
"direction": "Close Short",
"size": 2881240,
"volume_usd": 9997.9028,
"start_position": -3411528597,
"closed_pnl": 3275.96988,
"fee_value": 2.099559,
"price": 0.00347
}
],
"nextCursor": "MHg1YjVkNTEyMDNhMGY5MDc5ZjhhZWIwOThhNjUyM2ExM2YyOThjMDYwLTE3ODkzNDM4NzcwMjgtMHhjOTYxNTY5MmM1YjQ0ZWJjY2FkYjA0NDQ1OGE4NDcwMjAyNDgwMDc4NjBiNzZkOGU2ZDJhMDFlNTg0YjgyOGE3"
},
"success": true
}{
"success": false,
"message": "Bad request"
}{
"success": false,
"message": "Unauthorized"
}{
"success": false,
"message": "Access Denied"
}{
"success": false,
"message": "Too many requests"
}{
"success": false,
"message": "Internal Server Error"
}- Usage Note
- Accessibility
- Chain Supported
- Returns historical perpetual trade fills for one Hyperliquid wallet.
- Use
sort_typeto read fills in ascending or descending time order. - Use the returned
nextCursorascursorin the next request. limitdefaults to10and supports up to20records per request.
- Lite
- Starter
- Premium
- Business
- Enterprise
Hyperliquid
Compute Unit ⚙️
Compute Unit ⚙️
- This endpoint consumes
5 CUper request.
Use Cases 💡
Use Cases 💡
- Build a wallet’s perpetual execution history.
- Analyze entry and exit activity, realized PnL, fees, and traded volume.
- Support trader attribution, performance review, and position lifecycle analysis.
How to Use 🛠️
How to Use 🛠️
- Pass a Hyperliquid wallet address in the request body.
- Start with an empty cursor and use
nextCursorto continue pagination. - Use
sort_type=descfor the newest fills first orsort_type=ascfor chronological processing.
Best Practices ✅
Best Practices ✅
- Persist the cursor when processing long histories.
- Deduplicate by transaction hash when combining pages or polling repeatedly.
- Combine fills with Wallet Open Positions to compare execution history with current exposure.
Authorizations
API key for authentication
Body
application/json
Was this page helpful?

