API Endpoints

Perps - Token Open Positions

get
https://public-api.birdeye.so/perps/v1/token/open_positions
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
  • Returns currently open perp positions for one market, sorted by the requested metric.
  • size is signed: positive typically means long exposure, negative means short exposure.
  • entry_price, mark_price, and margin_used are the key fields for current exposure and unrealized risk.
  • Data availability begins on May 25, 2026 at 15:00 UTC.
Use Cases 💡
  • Inspect who is positioned in a market and how large the open risk is.
  • Identify concentrated longs or shorts before funding, squeezes, or liquidation cascades.
  • Build whale-position views for individual perp markets.
  • Power risk dashboards that surface the largest and most levered open positions.
How to Use 🛠️
  • Set x-perp, pass the market symbol in token, then choose sort_by, offset, and limit.
  • Use wallet, size, margin_used, position_value, and unrealized_pnl as your core row fields.
  • Read leverage_type and max_leverage to distinguish margin mode and leverage ceiling.
Best Practices ✅
  • Sort by position value or margin when screening for risk concentration.
  • Use wallet open positions together with token open positions to move between market-centric and wallet-centric views.
  • Compare entry_price to mark_price before interpreting unrealized PnL in isolation.
Limitations ⚠️
  • Hyperliquid only.

Query Params
string
required

The symbol of a coin/token (e.g: BTC, SOL, ETH).

string
enum
Defaults to open_time
Allowed:
string
enum
Defaults to desc

Specify the sort order.

Allowed:
integer
Defaults to 0

Specify the offset for pagination. Filter for records with offset greater than the specified offset value, including those with offset equal to the specified offset.

integer
1 to 50
Defaults to 10

Number of items per page.

Headers
string
enum
Defaults to hyperliquid

Specify the perpetuals exchange. Currently supports hyperliquid.

Allowed:
Responses

Updated 9 days ago

Did this page help you?
Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 9 days ago

Did this page help you?