API reference · v5

Hyperliquid API

Hyperliquid traders by address: the leaderboard, performance, open positions, and the order and position history Hyperliquid itself does not keep, rebuilt from fills.

Base URL https://api.kopyon.com/v5/hyperliquid/ · send your key in the X-API-KEY header · trader id: A trader's wallet address (0x…).

Get a free API key · Interactive reference with Try it · Authentication, paging and errors

Traders

GET /v5/hyperliquid/traders

Every Hyperliquid account on its leaderboard, ranked by PnL, ROI or volume over a period.

Hyperliquid refreshes this Hyperliquid updates this leaderboard every few minutes; the API reads it again every 5 minutes..

Query parameters

Name	Type	Description
`period`required	enum	Period the numbers cover1D, 7D, 30D, ALL
`sortBy`	enumdefault pnl	What to rank bypnl, roi, volume
`order`	enumdefault DESC	DESC lists the highest first, ASC the lowestDESC, ASC
`minAccountValue`	stringdefault 0	Only accounts worth at least this, in USDC; ranking by ROI is noisy without it
`minVolume`	stringdefault 0	Only accounts that traded at least this over the period, in USDC. Hyperliquid's ROI is over the value at the start of the period, so a nearly empty account that later got a deposit can top an ROI ranking without trading much
`page`	intdefault 1	Page number
`rows`	intdefault 20	Rows per page1 to 100

Response fields, in `data`

Field	Type	Description
`traders[]`always	array
`traders[].traderId`always	string	The trader's id at the source; other operations take it as traderId
`traders[].name`always	string	Display name
`traders[].roi`	number
`traders[].pnl`	number
`traders[].pnlCurrency`	string
`traders[].sourceDetails.accountValue`	only Hyperliquid
`traders[].sourceDetails.volume`	only Hyperliquid
`hasMore`always	boolean	true when another page follows
`total`always	number	Accounts across all pages

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/traders?period=1D"

{
  "data": {
    "traders": [
      {
        "traderId": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "name": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "roi": 0.0831360019,
        "pnl": 13679732.626202,
        "pnlCurrency": "USDC",
        "sourceDetails": {
          "accountValue": 274728587.779127,
          "volume": 8093561.66
        }
      },
      {
        "traderId": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
        "name": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
        "roi": 0.08066848,
        "pnl": 12110690.494512001,
        "pnlCurrency": "USDC",
        "sourceDetails": {
          "accountValue": 264362767.01149598,
          "volume": 14537742.3
        }
      },
      {
        "traderId": "0x3a98be4692cae9eee26ecf73b4be7b8961ebf4b8",
        "name": "0x3a98be4692cae9eee26ecf73b4be7b8961ebf4b8",
        "roi": 102.6200458981,
        "pnl": 8988469.296206,
        "pnlCurrency": "USDC",
        "sourceDetails": {
          "accountValue": 9075058.096206,
          "volume": 71906.85
        }
      }
    ],
    "hasMore": true,
    "total": 47237
  }
}

Performance

GET /v5/hyperliquid/performance

The trader's PnL, volume and PnL drawdown over a period, spot included, and Hyperliquid's ROI when the account is on its leaderboard.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking
`period`required	enum	Period the numbers cover1D, 7D, 30D, ALL

Response fields, in `data`

Field	Type	Description
`period`always	string
`roi`	number
`pnl`	number
`sourceDetails.volume`	only Hyperliquid
`sourceDetails.maxPnlDrawdown`	only Hyperliquid

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/performance?traderId=0x5b5d51203a0f9079f8aeb098a6523a13f298c060&period=1D"

{
  "data": {
    "period": "1D",
    "pnl": 14600986.249797,
    "roi": 0.0831360019,
    "sourceDetails": {
      "volume": 9342607.49,
      "maxPnlDrawdown": 10549945.558469
    }
  }
}

Trader chart

GET /v5/hyperliquid/traderChart

The trader's PnL or account value over a period, spot included.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking
`period`required	enum	Period the numbers cover1D, 7D, 30D, ALL
`metric`	enumdefault PNL	PNL since the period began, or the account valuePNL, BALANCE

Response fields, in `data`

Field	Type	Description
`metric`always	string	What the points measure: ROI, PNL or BALANCE
`points[]`always	array
`points[].timestamp`always	number	Point time, in Unix milliseconds
`points[].value`always	number

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/traderChart?traderId=0x5b5d51203a0f9079f8aeb098a6523a13f298c060&period=1D"

{
  "data": {
    "metric": "PNL",
    "points": [
      {
        "timestamp": 1792250160088,
        "value": 0
      },
      {
        "timestamp": 1792258560068,
        "value": 6500215.090178
      },
      {
        "timestamp": 1792266960000,
        "value": 582037.065478
      }
    ]
  }
}

Open positions

GET /v5/hyperliquid/openPositions

The trader's perpetual positions on Hyperliquid's main exchange, which are public on-chain.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking

Response fields, in `data`

Field	Type	Description
`accountValue`always	number	Perpetuals account value, in USDC
`positions[]`always	array
`positions[].symbol`always	string
`positions[].side`always	LONG \| SHORT
`positions[].size`	number	Position size, always positive; side gives the direction
`positions[].entryPrice`always	number
`positions[].markPrice`	number	The exchange's mark price
`positions[].leverage`	number
`positions[].marginMode`	ISOLATED \| CROSS
`positions[].unrealizedPnl`	number	In pnlCurrency
`positions[].pnlCurrency`	string
`positions[].liquidationPrice`	number
`positions[].margin`	number	Margin the position uses, in pnlCurrency
`positions[].roi`	number	unrealizedPnl over margin, as a fraction. Where the exchange sends its own (KuCoin; BingX, over the opening margin), it is passed on and can differ from that ratio

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/openPositions?traderId=0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

{
  "data": {
    "accountValue": 148717903.968475,
    "positions": [
      {
        "symbol": "BTCUSD",
        "side": "SHORT",
        "size": 2758.97017,
        "entryPrice": 76204.7,
        "markPrice": 81098.6,
        "leverage": 5,
        "marginMode": "CROSS",
        "unrealizedPnl": -13502096.016888,
        "pnlCurrency": "USDC",
        "liquidationPrice": 153162.6348896415,
        "margin": 44749723.645752,
        "roi": -0.3211015306,
        "sourceDetails": {}
      },
      {
        "symbol": "ETHUSD",
        "side": "SHORT",
        "size": 106350.462,
        "entryPrice": 2322.65,
        "markPrice": 2371.2,
        "leverage": 5,
        "marginMode": "CROSS",
        "unrealizedPnl": -5163123.442337,
        "pnlCurrency": "USDC",
        "liquidationPrice": 4225.6265012231,
        "margin": 50435643.09888,
        "roi": -0.1045102831,
        "sourceDetails": {}
      },
      {
        "symbol": "SOLUSD",
        "side": "SHORT",
        "size": 724940.08,
        "entryPrice": 94.3199,
        "markPrice": 101.97,
        "leverage": 7,
        "marginMode": "CROSS",
        "unrealizedPnl": -5545836.421894,
        "pnlCurrency": "USDC",
        "liquidationPrice": 369.7006143769,
        "margin": 10560305.708228,
        "roi": -0.5677530511,
        "sourceDetails": {}
      }
    ]
  }
}

Order history

GET /v5/hyperliquid/orderHistory

The trader's executed perpetual orders, oldest first. Hyperliquid has no such history, so it is rebuilt from the account's perpetual fills: at most 2000 per call, the latest ones or the first ones from startTime on. From startTime, nextCursor reads on from the last fill; the latest fills cannot be paged back. Hyperliquid keeps each account's latest 10000 fills. An order cut at the edge of a call shows up in both, with the same orderId.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking
`startTime`	int	From this time on, in Unix milliseconds; without it, the latest fills
`endTime`	int	Up to this time, in Unix milliseconds; needs startTime
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page

Response fields, in `data`

Field	Type	Description
`orders[]`always	array
`orders[].symbol`always	string
`orders[].side`always	string
`orders[].positionSide`	string	BOTH in one-way mode; LONG or SHORT in hedge mode
`orders[].price`	number
`orders[].quantity`	number
`orders[].quoteQuantity`	number
`orders[].createdAt`	number	When the order was placed, in Unix milliseconds
`orders[].updatedAt`always	number	Last change, in Unix milliseconds
`orders[].sourceDetails.fills`	only Hyperliquid
`orders[].sourceDetails.feeToken`	only Hyperliquid
`orders[].realizedPnl`	number
`orders[].orderId`	string
`orders[].tradingFee`	number	Fees paid, in sourceDetails.feeToken; negative is a rebate
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/orderHistory?traderId=0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

{
  "data": {
    "orders": [
      {
        "symbol": "LINKUSD",
        "side": "BUY",
        "positionSide": "BOTH",
        "price": 11.877,
        "quantity": 69.5,
        "quoteQuantity": 825.4515,
        "createdAt": 1792331985560,
        "updatedAt": 1792331985560,
        "orderId": "578349271119",
        "realizedPnl": 120.334385,
        "tradingFee": 0.046225,
        "sourceDetails": {
          "fills": 1,
          "feeToken": "USDC"
        }
      },
      {
        "symbol": "LINKUSD",
        "side": "BUY",
        "positionSide": "BOTH",
        "price": 11.871,
        "quantity": 55.2,
        "quoteQuantity": 655.2792,
        "createdAt": 1792331988401,
        "updatedAt": 1792332002533,
        "orderId": "578349305592",
        "realizedPnl": 95.906136,
        "tradingFee": 0.036694,
        "sourceDetails": {
          "fills": 3,
          "feeToken": "USDC"
        }
      },
      {
        "symbol": "LINKUSD",
        "side": "BUY",
        "positionSide": "BOTH",
        "price": 11.884,
        "quantity": 29,
        "quoteQuantity": 344.636,
        "createdAt": 1792332028323,
        "updatedAt": 1792332066242,
        "orderId": "578349779228",
        "realizedPnl": 50.00847,
        "tradingFee": 0.021768,
        "sourceDetails": {
          "fills": 4,
          "feeToken": "USDC"
        }
      }
    ]
  }
}

Position history

GET /v5/hyperliquid/positionHistory

The trader's closed perpetual positions, oldest first; a flip closes one position and opens another. Hyperliquid has no such history, so it is rebuilt from the account's perpetual fills: at most 2000 per call, the latest ones or the first ones from startTime on. From startTime, nextCursor reads on from the last fill; the latest fills cannot be paged back. Hyperliquid keeps each account's latest 10000 fills. A position already open at the first fill read is left out, since its entry is unknown. netPnl is omitted when the funding is too long to read.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking
`startTime`	int	From this time on, in Unix milliseconds; without it, the latest fills
`endTime`	int	Up to this time, in Unix milliseconds; needs startTime
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page

Response fields, in `data`

Field	Type	Description
`positions[]`always	array
`positions[].positionId`	string
`positions[].symbol`always	string
`positions[].side`	LONG \| SHORT
`positions[].status`	string
`positions[].marginMode`	ISOLATED \| CROSS
`positions[].leverage`	number
`positions[].roi`	number
`positions[].entryPrice`	number
`positions[].closePrice`	number
`positions[].openedAt`always	number	When the position opened, in Unix milliseconds
`positions[].closedAt`	number	When the position closed, in Unix milliseconds
`positions[].updatedAt`always	number	Last change, in Unix milliseconds
`positions[].openedVolume`	number
`positions[].closedVolume`	number
`positions[].maxOpenInterest`	number
`positions[].grossPnl`	number
`positions[].fundingPnl`	number
`positions[].tradingFee`	number
`positions[].liquidationFee`	number
`positions[].netPnl`	number
`positions[].pnlCurrency`	string
`positions[].sourceDetails.fills`	only Hyperliquid
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/positionHistory?traderId=0xdd53c5297309130ab5fe5623dc905752e3342b13"

{
  "data": {
    "positions": []
  }
}

Transfer history

GET /v5/hyperliquid/transferHistory

Money into and out of the trader's account, oldest first: deposits, withdrawals, transfers between addresses and vault deposits and withdrawals. Moves inside the account, staking and liquidations are left out. Hyperliquid answers 2000 ledger entries a call.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking
`startTime`	int	From this time on, in Unix milliseconds; without it, from the account's first entry
`endTime`	int	Up to this time, in Unix milliseconds
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page

Response fields, in `data`

Field	Type	Description
`transfers[]`always	array
`transfers[].time`always	number	In Unix milliseconds
`transfers[].asset`	string
`transfers[].amount`always	number
`transfers[].type`always	deposit \| withdraw \| transfer \| vaultDeposit \| vaultWithdraw \| commission \| other	deposit and withdraw move the owner's money into or out of the account; transfer, to or from another address; vaultDeposit and vaultWithdraw, into or out of a vault; commission is a vault leader's share; other is a kind none of these fits, named in sourceDetails.type
`transfers[].sourceDetails.type`	only Hyperliquid
`transfers[].counterparty`	string
`transfers[].fee`	number
`transfers[].txHash`	string
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/transferHistory?traderId=0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

{
  "data": {
    "transfers": [
      {
        "time": 1740074470287,
        "type": "deposit",
        "sourceDetails": {
          "type": "deposit"
        },
        "txHash": "0x07d6e679957bbe4b5e1d9368a6188480b1a86b33fe24ce314435b7faa57eada7",
        "amount": 1000,
        "asset": "USDC"
      },
      {
        "time": 1746799270889,
        "type": "deposit",
        "sourceDetails": {
          "type": "deposit"
        },
        "txHash": "0xe9ef01b3fc0c9f20a3fce63ed44081577fc1200d9c7fa6f552058bc38a00c038",
        "amount": 9999999.69,
        "asset": "USDC"
      },
      {
        "time": 1746860271946,
        "type": "deposit",
        "sourceDetails": {
          "type": "deposit"
        },
        "txHash": "0x60124151eda706288a199d46e7f4a0d7afd7719fe23f9b8b516277f03783c023",
        "amount": 2999999.85,
        "asset": "USDC"
      }
    ]
  }
}

Search traders

GET /v5/hyperliquid/traderSearch

Accounts on the leaderboard whose name or address contains this, by all-time PnL, with all-time numbers.

Query parameters

Name	Type	Description
`name`required	string	Part of the account's name or address, in any case
`page`	intdefault 1	Page number
`rows`	intdefault 20	Rows per page1 to 100

Response fields, in `data`

Field	Type	Description
`traders[]`always	array
`traders[].traderId`always	string	The trader's id at the source; other operations take it as traderId
`traders[].name`always	string	Display name
`traders[].roi`	number
`traders[].pnl`	number
`traders[].pnlCurrency`	string
`traders[].sourceDetails.accountValue`	only Hyperliquid
`traders[].sourceDetails.volume`	only Hyperliquid
`hasMore`always	boolean	true when another page follows
`total`always	number	Accounts across all pages

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/traderSearch?name=0x5b"

{
  "data": {
    "traders": [
      {
        "traderId": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "name": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "roi": 0.5794972602,
        "pnl": 187373522.429408,
        "pnlCurrency": "USDC",
        "sourceDetails": {
          "accountValue": 274728587.779127,
          "volume": 5773646771.75
        }
      },
      {
        "traderId": "0x5b19d6fd96fcbfd34f7c14cc581a470144ff4ecc",
        "name": "0x5b19d6fd96fcbfd34f7c14cc581a470144ff4ecc",
        "roi": 48.0057382803,
        "pnl": 9815250.541171,
        "pnlCurrency": "USDC",
        "sourceDetails": {
          "accountValue": 7554.681171,
          "volume": 154185507.67000002
        }
      },
      {
        "traderId": "0x5b53358eca5790fa4c268ad6813386b3a86549c7",
        "name": "0x5b53358eca5790fa4c268ad6813386b3a86549c7",
        "roi": 0.2655044249,
        "pnl": 8688386.480901001,
        "pnlCurrency": "USDC",
        "sourceDetails": {
          "accountValue": 20507406.340901,
          "volume": 221994112.66
        }
      }
    ],
    "hasMore": true,
    "total": 183
  }
}

Trader profile

GET /v5/hyperliquid/traderProfile

What Hyperliquid shows about a trader: name, account value, the leaderboard's numbers per period, largest drawdown and days active. Hyperliquid has no avatar, bio or followers.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's address, from the ranking

Response fields, in `data`

Field	Type	Description
`traderId`always	string
`name`	string
`sourceDetails.accountValue`	only Hyperliquid
`sourceDetails.daysActive`	only Hyperliquid
`sourceDetails.maxPnlDrawdown`	only Hyperliquid

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/hyperliquid/traderProfile?traderId=0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

{
  "data": {
    "traderId": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
    "name": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
    "sourceDetails": {
      "accountValue": 274728587.779127,
      "daysActive": 604,
      "maxPnlDrawdown": 194004499.11261195
    }
  }
}

Stream and webhooks

Paid plans can follow a trader in real time over wss://api.kopyon.com/v5/streamor through signed webhooks. Topics for this source:

openPositions: Open positions, whenever they change
positionEvents: Opened, increased, decreased, closed
orderHistory: New and updated orders
positionHistory: Newly closed positions

Stream messages and webhook signatures

Hyperliquid API

Traders

Query parameters

Response fields, in data

Example

Performance

Query parameters

Response fields, in data

Example

Trader chart

Query parameters

Response fields, in data

Example

Open positions

Query parameters

Response fields, in data

Example

Order history

Query parameters

Response fields, in data

Example

Position history

Query parameters

Response fields, in data

Example

Transfer history

Query parameters

Response fields, in data

Example

Search traders

Query parameters

Response fields, in data

Example

Trader profile

Query parameters

Response fields, in data

Example

Stream and webhooks

Try the Hyperliquid API for free.

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`