API reference · v5

Hyperliquid Vaults API

Hyperliquid vaults: the vault list with each period's PnL, every vault's details and followers, and the positions and history of the account behind it.

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

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

Traders

GET /v5/hyperliquid-vaults/traders

Hyperliquid's vaults: accounts a leader trades with what depositors put in, ranked by assets, PnL or APR.

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

Query parameters

Name	Type	Description
`period`required	enum	Period the PnL covers1D, 7D, 30D, ALL
`sortBy`	enumdefault aum	What to rank by: assets in the vault, PnL over the period, or Hyperliquid's APRaum, pnl, apr
`order`	enumdefault DESC	DESC lists the highest first, ASC the lowestDESC, ASC
`closed`	bool	true lists closed vaults too
`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[].pnl`	number
`traders[].pnlCurrency`	string
`traders[].sourceDetails.apr`	only Hyperliquid
`traders[].sourceDetails.leader`	only Hyperliquid
`traders[].sourceDetails.createdAt`	only Hyperliquid
`traders[].sourceDetails.closed`	only Hyperliquid
`traders[].aum`	number
`hasMore`always	boolean	true when another page follows
`total`always	number	Vaults across all pages

Example

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

{
  "data": {
    "traders": [
      {
        "traderId": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
        "name": "Hyperliquidity Provider (HLP)",
        "pnl": 19029.020807,
        "pnlCurrency": "USDC",
        "aum": 177560509.512217,
        "sourceDetails": {
          "apr": 0.035133799449039355,
          "leader": "0x677d831aef5328190852e24f13c46cac05f984e7",
          "createdAt": 1683243596849
        }
      },
      {
        "traderId": "0x1e37a337ed460039d1b15bd3bc489de789768d5e",
        "name": "Growi HF",
        "pnl": -54387.796149,
        "pnlCurrency": "USDC",
        "aum": 13570947.235188,
        "sourceDetails": {
          "apr": 0.16079809864087216,
          "leader": "0x7789450871fb1315fa982ccb8039cb34e8f2f60d",
          "createdAt": 1720440504732
        }
      },
      {
        "traderId": "0x07fd993f0fa3a185f7207adccd29f7a87404689d",
        "name": "[ Systemic Strategies ] L/S Grids",
        "pnl": 478543.113045,
        "pnlCurrency": "USDC",
        "aum": 9748391.694926,
        "sourceDetails": {
          "apr": -0.1713193906780998,
          "leader": "0x2b804617c6f63c040377e95bb276811747006f4b",
          "createdAt": 1737611331869
        }
      }
    ],
    "hasMore": true,
    "total": 3076
  }
}

Performance

GET /v5/hyperliquid-vaults/performance

The vault'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 vault'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-vaults/performance?traderId=0xdfc24b077bc1425ad1dea75bcb6f8158e10df303&period=1D"

{
  "data": {
    "period": "1D",
    "pnl": 18530.270576,
    "roi": 0.0001098621,
    "sourceDetails": {
      "volume": 0,
      "maxPnlDrawdown": 1525.172914
    }
  }
}

Trader chart

GET /v5/hyperliquid-vaults/traderChart

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

Query parameters

Name	Type	Description
`traderId`required	string	The vault'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-vaults/traderChart?traderId=0xdfc24b077bc1425ad1dea75bcb6f8158e10df303&period=1D"

{
  "data": {
    "metric": "PNL",
    "points": [
      {
        "timestamp": 1792253082983,
        "value": 0
      },
      {
        "timestamp": 1792255370229,
        "value": 267.139398
      },
      {
        "timestamp": 1792256268488,
        "value": 812.21981
      }
    ]
  }
}

Open positions

GET /v5/hyperliquid-vaults/openPositions

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

Query parameters

Name	Type	Description
`traderId`required	string	The vault'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-vaults/openPositions?traderId=0x1e37a337ed460039d1b15bd3bc489de789768d5e"

{
  "data": {
    "accountValue": 13566718.002708,
    "positions": [
      {
        "symbol": "BTCUSD",
        "side": "LONG",
        "size": 1.07158,
        "entryPrice": 86807.4,
        "markPrice": 81104,
        "leverage": 40,
        "marginMode": "CROSS",
        "unrealizedPnl": -6111.725379,
        "pnlCurrency": "USDC",
        "margin": 2172.735608,
        "roi": -2.6281014151,
        "sourceDetails": {}
      },
      {
        "symbol": "ETHUSD",
        "side": "LONG",
        "size": 33.4584,
        "entryPrice": 2756.68,
        "markPrice": 2371.6,
        "leverage": 25,
        "marginMode": "CROSS",
        "unrealizedPnl": -12884.453906,
        "pnlCurrency": "USDC",
        "margin": 3173.997657,
        "roi": -3.4923126719,
        "sourceDetails": {}
      },
      {
        "symbol": "SOLUSD",
        "side": "LONG",
        "size": 754.17,
        "entryPrice": 122.4951,
        "markPrice": 102,
        "leverage": 20,
        "marginMode": "CROSS",
        "unrealizedPnl": -15456.828937,
        "pnlCurrency": "USDC",
        "margin": 3846.267,
        "roi": -3.3462797236,
        "sourceDetails": {}
      }
    ]
  }
}

Order history

GET /v5/hyperliquid-vaults/orderHistory

The vault'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 vault'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-vaults/orderHistory?traderId=0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"

{
  "data": {
    "orders": []
  }
}

Position history

GET /v5/hyperliquid-vaults/positionHistory

The vault'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 vault'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-vaults/positionHistory?traderId=0xc179e03922afe8fa9533d3f896338b9fb87ce0c8"

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

Transfer history

GET /v5/hyperliquid-vaults/transferHistory

Money into and out of the vault'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 vault'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-vaults/transferHistory?traderId=0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"

{
  "data": {
    "transfers": [
      {
        "time": 1683243596849,
        "type": "vaultDeposit",
        "sourceDetails": {
          "type": "vaultCreate"
        },
        "txHash": "0x5a2180355bcdcf8596010401752f55010400ab364d2b6cc7732b23ab8b97a38d",
        "amount": 200,
        "asset": "USDC"
      },
      {
        "time": 1683243598416,
        "type": "vaultDeposit",
        "sourceDetails": {
          "type": "vaultCreate"
        },
        "txHash": "0x1a25b29ddbfeb850b2630401752f5f000070d7e69595f2422fb3c9b8bf6f834e",
        "amount": -100,
        "asset": "USDC",
        "counterparty": "0x010461c14e146ac35fe42271bdc1134ee31c703a"
      },
      {
        "time": 1683243600725,
        "type": "vaultDeposit",
        "sourceDetails": {
          "type": "vaultCreate"
        },
        "txHash": "0xe2856a02ac3818cb01db0401752f6900004c1bcf143a6c0851946941575d892c",
        "amount": -100,
        "asset": "USDC",
        "counterparty": "0x31ca8395cf837de08b24da3f660e77761dfb974b"
      }
    ],
    "nextCursor": "NjcwOTMzNDkxNDMzNDFkYy4xNjg1NjMxNTkwMDEw"
  }
}

Search traders

GET /v5/hyperliquid-vaults/traderSearch

Vaults, closed ones included, whose name or address contains this, by all-time PnL.

Query parameters

Name	Type	Description
`name`required	string	Part of the vault'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[].pnl`	number
`traders[].pnlCurrency`	string
`traders[].sourceDetails.apr`	only Hyperliquid
`traders[].sourceDetails.leader`	only Hyperliquid
`traders[].sourceDetails.createdAt`	only Hyperliquid
`traders[].sourceDetails.closed`	only Hyperliquid
`traders[].aum`	number
`hasMore`always	boolean	true when another page follows
`total`always	number	Vaults across all pages

Example

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

{
  "data": {
    "traders": [
      {
        "traderId": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
        "name": "Hyperliquidity Provider (HLP)",
        "pnl": 138748183.094406,
        "pnlCurrency": "USDC",
        "aum": 177560509.512217,
        "sourceDetails": {
          "apr": 0.035133799449039355,
          "leader": "0x677d831aef5328190852e24f13c46cac05f984e7",
          "createdAt": 1683243596849
        }
      },
      {
        "traderId": "0xd6e56265890b76413d1d527eb9b75e334c0c5b42",
        "name": "[ Systemic Strategies ] ♾️ HyperGrowth ♾️",
        "pnl": 5601892.880534,
        "pnlCurrency": "USDC",
        "aum": 5863594.960534,
        "sourceDetails": {
          "apr": -0.11812709743185433,
          "leader": "0x2b804617c6f63c040377e95bb276811747006f4b",
          "createdAt": 1756505842629
        }
      },
      {
        "traderId": "0xac26cf5f3c46b5e102048c65b977d2551b72a9c7",
        "name": "Long HYPE & BTC | Short Garbage",
        "pnl": 2251902.636814,
        "pnlCurrency": "USDC",
        "aum": 2476974.706814,
        "sourceDetails": {
          "apr": -0.08688307123111841,
          "leader": "0xa380444a9299df2a15bddf949dd493bb6d30d939",
          "createdAt": 1744227338023
        }
      }
    ],
    "hasMore": true,
    "total": 384
  }
}

Trader profile

GET /v5/hyperliquid-vaults/traderProfile

The vault's leader, description, assets, APR and the share of profit the leader takes.

Query parameters

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

Response fields, in `data`

Field	Type	Description
`traderId`always	string
`name`	string
`bio`	string
`sourceDetails.leader`	only Hyperliquid
`sourceDetails.apr`	only Hyperliquid
`sourceDetails.leaderShare`	only Hyperliquid
`sourceDetails.acceptsDeposits`	only Hyperliquid
`sourceDetails.closed`	only Hyperliquid
`sourceDetails.createdAt`	only Hyperliquid
`sourceDetails.childVaults`	only Hyperliquid
`aum`	number
`profitShare`	number

Example

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

{
  "data": {
    "traderId": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
    "name": "Hyperliquidity Provider (HLP)",
    "bio": "This community-owned vault provides liquidity to Hyperliquid through multiple market making strategies, performs liquidations, and accrues platform fees.",
    "aum": 177560509.512217,
    "profitShare": 0,
    "sourceDetails": {
      "leader": "0x677d831aef5328190852e24f13c46cac05f984e7",
      "apr": 0.03526082054797103,
      "leaderShare": 0.002040394601331908,
      "acceptsDeposits": true,
      "closed": false,
      "createdAt": 1683243596849,
      "childVaults": [
        "0x010461c14e146ac35fe42271bdc1134ee31c703a",
        "0x2e3d94f0562703b25c83308a05046ddaf9a8dd14",
        "0x2ed5c4484ea3ff8b57d5f2fb152a40d9f2b68308"
      ]
    }
  }
}

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 Vaults 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 Vaults 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`