> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Perp Leaderboard

Get PnL leaderboard for Hyperliquid perp traders from HyperTracker. Ranks by day/week/month/all-time PnL with full performance metrics and volume data. Ideal for: top trader discovery, performance benchmarking, copy trading research.

Catalog action Blockchain Data

Get PnL leaderboard for Hyperliquid perp traders from HyperTracker. Ranks by day/week/month/all-time PnL with full performance metrics and volume data. Ideal for: top trader discovery, performance benchmarking, copy trading research.


## At a Glance

| Field | Value |
| --- | --- |
| Action ID | `hypertracker-get-perp-leaderboard` |
| Category | Blockchain Data |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | `hypertracker`, `hyperliquid`, `leaderboard`, `pnl`, `traders`, `read` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apiKey` | `string` | No | HyperTracker API key \(falls back to HYPERTRACKER_API_KEY env var\) |
| `period` | `string` | No | Time period to rank by. Defaults to pnlAllTime. |
| `order` | `string` | No | Sort direction. Defaults to desc \(highest PnL first\). |
| `limit` | `number` | No | Number of traders to return. Allowed values: 25, 50, 100. Defaults to 25. |
| `offset` | `number` | No | Pagination offset \(number of records to skip\). |

## Result Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `totalCount` | `number` | Yes | Total number of traders in the leaderboard |
| `traders` | `array` | Yes | Ranked list of perp traders |

## Examples

**Workflow node**

```json
{
  "type": "hypertracker-get-perp-leaderboard",
  "payload": {
    "apiKey": "configured-in-b3os",
    "period": "pnlDay",
    "order": "desc",
    "limit": 25,
    "offset": 1
  },
  "children": []
}
```
  **Test with API**

```bash
curl -X POST "https://api.b3os.org/v1/actions/hypertracker-get-perp-leaderboard/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "apiKey": "configured-in-b3os",
    "period": "pnlDay",
    "order": "desc",
    "limit": 25,
    "offset": 1
  }
}'
```

**Use expressions for dynamic values**

Payload fields can use workflow expressions such as `{{$trigger.body.amount}}`, `{{$nodes.fetch.result.price}}`, and `{{$props.asset}}` when the value should come from a trigger, prior node, or reusable workflow prop.