> For the complete documentation index, see [llms.txt](https://docs.pangolin.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pangolin.exchange/pangoperps/public-info-api/platform-data.md).

# Platform data

## Platform data

### Platform positions

Returns a platform-wide snapshot of open positions, useful for aggregate exposure and liquidation-risk visualizations. This query scans open positions and has weight 20; use it sparingly.

```json
{
  "type": "platformPositions",
  "symbol": "PERP_BTC_USDC",
  "broker_id": "pangoperps",
  "min_notional": "10000",
  "limit": 500
}
```

| Field         | Type    | Required | Default / limits | Description                           |
| ------------- | ------- | -------- | ---------------- | ------------------------------------- |
| symbol        | string  | No       | —                | Optional market filter.               |
| broker\_id    | string  | No       | —                | Optional broker filter.               |
| min\_notional | decimal | No       | 0                | Minimum position notional to include. |
| limit         | int     | No       | 500; 1–5000      | Maximum rows.                         |
| cursor        | string  | No       | —                | Opaque pagination cursor.             |

data contains total\_long\_notional, total\_short\_notional, total\_positions, rows\[], and next\_cursor. The aggregate totals and count apply to the complete filtered snapshot, not only the current page. Position rows include address, account\_id, broker\_id, symbol, side, position\_qty, notional, average\_open\_price, mark\_price, est\_liq\_price, unrealized\_pnl, unsettled\_pnl, leverage, margin\_mode, and opened\_at. est\_liq\_price, unrealized\_pnl, unsettled\_pnl, leverage, and margin\_mode can be null if position calculation fails. margin\_mode is otherwise CROSS or ISOLATED; opened\_at is a millisecond epoch. Results are cached for 5 seconds and sorted by position ID descending. For a liquidation heatmap, group est\_liq\_price into price buckets in your application.

### Top addresses

Returns a leaderboard of addresses ranked by notional, volume, PnL, or trade count. Each row includes statistics over multiple time windows. Weight: 10.

```json
{
  "type": "topAddresses",
  "symbol": "PERP_BTC_USDC",
  "sort_by": "pnl_7d",
  "limit": 50
}
```

| Field         | Type    | Required | Default / limits              | Description                                                                                               |
| ------------- | ------- | -------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| symbol        | string  | No       | Omitted or empty: all markets | Optional market filter.                                                                                   |
| sort\_by      | string  | No       | notional                      | One of notional, volume\_24h, volume\_7d, volume\_30d, pnl\_24h, pnl\_7d, pnl\_30d, or trade\_count\_24h. |
| min\_notional | decimal | No       | 0                             | Minimum total notional to include.                                                                        |
| limit         | int     | No       | 50; 1–200                     | Maximum rows.                                                                                             |
| cursor        | string  | No       | —                             | Opaque cursor.                                                                                            |

Each row includes address, broker\_id, total\_notional, pnl\_24h, pnl\_7d, pnl\_30d, volume\_24h, volume\_7d, volume\_30d, trade\_count\_24h, win\_rate\_24h, win\_rate\_7d, win\_rate\_30d, avg\_trade\_size, and position\_count. Monetary values are decimal strings; trade counts are integers and win rates are numeric values. The 24-hour figures use a rolling window. The 7-day and 30-day figures use UTC-day-aligned windows, combining today's live values with the preceding days. avg\_trade\_size is 24-hour volume divided by 24-hour trade count, or null when there are no trades. Historical win rates can be null if that data source is unavailable.

data.last\_updated\_time indicates when the cached snapshot was assembled. Results are cached for 30 minutes by symbol, sort field, and minimum notional; use last\_updated\_time to assess age. Historical-data outages do not prevent the response from being returned, but 7-day and 30-day win rates may be null. Use data.next\_cursor to continue through results.

***
