> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renesis.fi/llms.txt
> Use this file to discover all available pages before exploring further.
# Perps Analytics API
> Analytics and reporting endpoints for perpetual futures trading performance
# Perps Analytics Endpoints
Analytics and reporting endpoints for perpetual futures trading performance.
***
## GET /delegation/portfolio-management/get-positions
Fetch open positions from exchange with enhanced risk metrics.
### Query Parameters
* **exchange\_account\_id** (string, required): The exchange account UUID
### Request Example
```bash theme={null}
curl "https://api.renesis.fi/delegation/portfolio-management/get-positions?exchange_account_id=gate-perp-001" \
-H "X-API-Key: $API_KEY"
```
### Response Example
```json theme={null}
{
"isError": false,
"message": "Success",
"statusCode": 200,
"data": [
{
"symbol": "BTC/USDT:USDT",
"side": "short",
"contracts": 37,
"entry_price": 105842.4,
"mark_price": 116801.79,
"liquidation_price": 240011.96,
"unrealized_pnl": -40.55,
"notional": 432.17,
"leverage": 5,
"collateral": 100,
"maintenance_margin": 1.73,
"margin_mode": "cross",
"exchange": "gateio",
"exchange_account_id": "gate-perp-001",
"liquidation_distance_pct": 105.4,
"margin_health_score": 85.0
}
],
"risk_summary": {
"total_notional": 432.17,
"total_unrealized_pnl": -40.55,
"avg_leverage": 5.0,
"positions_at_risk": 0,
"lowest_margin_health": 85.0,
"position_count": 1
}
}
```
### Risk Metrics
| Field | Description |
| -------------------------- | ---------------------------------------------------------------------------- |
| `liquidation_distance_pct` | Distance from mark price to liquidation price as percentage |
| `margin_health_score` | 0-100 scale based on collateral vs maintenance margin. Score `<30` = at risk |
| `positions_at_risk` | Count of positions with margin\_health\_score \< 30 |
| `lowest_margin_health` | Minimum health score across all positions |
***
## GET /portfolio-management/exchange-account/perps/summary
Get combined perp performance summary with symbol-level breakdown.
### Query Parameters
* **exchange\_account\_id** (string, required\*): The exchange account UUID
* **portfolio\_id** (string, required\*): Portfolio ID - aggregates all accounts
* **start\_ts** (number, optional): Start timestamp (epoch ms)
* **end\_ts** (number, optional): End timestamp (epoch ms)
Provide either `exchange_account_id` or `portfolio_id`, not both.
### Request Example
```bash theme={null}
curl "https://api.renesis.fi/portfolio-management/exchange-account/perps/summary?exchange_account_id=hl_daed" \
-H "X-API-Key: $API_KEY"
```
### Response Example
```json theme={null}
{
"isError": false,
"message": "Perps summary retrieved successfully",
"statusCode": 200,
"data": {
"exchange_account_id": "hl_daed",
"funding": {
"summary": {
"total_funding": 15234.50,
"total_received": 18500.00,
"total_paid": -3265.50,
"count": 1250,
"currency": "USDT"
},
"by_market": [
{
"market": "USOL/USD:USDC",
"total_funding": 12500.00,
"total_received": 14000.00,
"total_paid": -1500.00,
"count": 800
}
]
},
"pnl": {
"summary": {
"total_pnl": 55000.00,
"total_profit": 125000.00,
"total_loss": -70000.00,
"count": 4149,
"currency": "USDT"
},
"by_market": [
{
"market": "USOL/USD:USDC",
"total_pnl": 809375.39,
"total_profit": 1300171.25,
"total_loss": -490795.85,
"count": 4149
}
]
},
"by_symbol": {
"USOL/USD:USDC": {
"total_pnl": 809375.39,
"total_profit": 1300171.25,
"total_loss": -490795.85,
"trade_count": 4149,
"win_count": 2500,
"loss_count": 1649,
"win_rate": 0.602,
"avg_trade_pnl": 195.08,
"max_win": 15000.00,
"max_loss": -8000.00,
"total_funding": 12500.00,
"funding_received": 14000.00,
"funding_paid": -1500.00,
"total_fees": 12500.00,
"net_return": 809375.39
}
}
}
}
```
### Symbol Performance Metrics
| Field | Description |
| -------------------------- | ---------------------------------- |
| `total_pnl` | Net realized PnL for the symbol |
| `trade_count` | Total number of trades |
| `win_count` / `loss_count` | Number of winning/losing trades |
| `win_rate` | Percentage of winning trades (0-1) |
| `avg_trade_pnl` | Average PnL per trade |
| `max_win` / `max_loss` | Largest winning/losing trade |
| `total_fees` | Total trading fees paid |
| `net_return` | PnL + funding - fees |
***
## GET /portfolio-management/exchange-account/perps/fills
List individual trade fills for perpetual orders.
### Query Parameters
* **exchange\_account\_id** (string, required\*): The exchange account UUID
* **portfolio\_id** (string, required\*): Portfolio ID - aggregates all accounts
* **market** (string, optional): Filter by market (e.g., "BTC/USDT:USDT")
* **start\_ts** (number, optional): Start timestamp (epoch ms)
* **end\_ts** (number, optional): End timestamp (epoch ms)
* **page** (number, optional): Page number (default: 0)
* **size** (number, optional): Results per page (default: 100, max: 500)
### Request Example
```bash theme={null}
curl "https://api.renesis.fi/portfolio-management/exchange-account/perps/fills?exchange_account_id=hl_daed&market=UBTC/USD:USDC&size=50" \
-H "X-API-Key: $API_KEY"
```
### Response Example
```json theme={null}
{
"isError": false,
"message": "Fills listed successfully",
"statusCode": 200,
"data": {
"total_orders": 2707,
"page": 0,
"size": 50,
"fills": [
{
"order_id": "0x123abc",
"trade_id": "456def",
"market": "UBTC/USD:USDC",
"side": "buy",
"price": 98500.00,
"amount": 0.05,
"cost": 4925.00,
"fee": 1.97,
"fee_currency": "USDC",
"timestamp": 1706745600000,
"datetime": "2025-01-31T12:00:00Z",
"execution_date": "2025-01-31T12:00:00+00:00"
}
]
}
}
```
***
## GET /portfolio-management/exchange-account/perps/twap-orders
List Hyperliquid TWAP orders with execution metrics.
This endpoint is specific to Hyperliquid exchange accounts.
### Query Parameters
* **exchange\_account\_id** (string, required\*): The exchange account UUID
* **portfolio\_id** (string, required\*): Portfolio ID - aggregates all accounts
* **symbol** (string, optional): Filter by symbol
* **page** (number, optional): Page number (default: 0)
* **size** (number, optional): Results per page (default: 50, max: 200)
### Request Example
```bash theme={null}
curl "https://api.renesis.fi/portfolio-management/exchange-account/perps/twap-orders?exchange_account_id=hl_daed" \
-H "X-API-Key: $API_KEY"
```
### Response Example
```json theme={null}
{
"isError": false,
"message": "TWAP orders listed successfully",
"statusCode": 200,
"data": {
"total": 23,
"page": 0,
"size": 50,
"entries": [
{
"_id": "65abc123",
"exchange_account_id": "hl_daed",
"twap_id": "0x789xyz",
"symbol": "USOL/USD:USDC",
"side": "buy",
"total_size": 1000.0,
"total_filled": 1000.0,
"avg_fill_price": 185.25,
"fill_count": 12,
"fill_rate_per_hour": 4.5,
"price_range": 2.50,
"price_range_pct": 1.35,
"time_span_hours": 2.67,
"first_fill_ts": 1706740000000,
"last_fill_ts": 1706749600000,
"fills": [
{
"price": 184.50,
"amount": 83.33,
"cost": 15374.99,
"fee": 6.15,
"timestamp": 1706740000000
}
]
}
]
}
}
```
### TWAP Execution Metrics
| Field | Description |
| -------------------- | ------------------------------------------------ |
| `avg_fill_price` | Volume-weighted average fill price |
| `fill_count` | Number of individual fills |
| `fill_rate_per_hour` | Average fills per hour |
| `price_range` | Difference between highest and lowest fill price |
| `price_range_pct` | Price range as percentage of average price |
| `time_span_hours` | Duration from first to last fill |
***
## GET /portfolio-management/exchange-account/perps/rebates
List trading rebates/rewards for an exchange account.
Primarily used for Gate.io VIP rebate programs.
### Query Parameters
* **exchange\_account\_id** (string, required\*): The exchange account UUID
* **portfolio\_id** (string, required\*): Portfolio ID - aggregates all accounts
* **currency** (string, optional): Filter by currency (e.g., "USDT")
* **start\_ts** (number, optional): Start timestamp (epoch ms)
* **end\_ts** (number, optional): End timestamp (epoch ms)
* **page** (number, optional): Page number (default: 0)
* **size** (number, optional): Results per page (default: 50, max: 500)
### Request Example
```bash theme={null}
curl "https://api.renesis.fi/portfolio-management/exchange-account/perps/rebates?exchange_account_id=gate_vip¤cy=USDT" \
-H "X-API-Key: $API_KEY"
```
### Response Example
```json theme={null}
{
"isError": false,
"message": "Rebates listed successfully",
"statusCode": 200,
"data": {
"total": 1250,
"page": 0,
"size": 50,
"entries": [
{
"_id": "65def456",
"exchange_account_id": "gate_vip",
"currency": "USDT",
"amount": 12.50,
"source": "trading_rebate",
"timestamp": 1706745600000
}
],
"summary_by_currency": [
{
"currency": "USDT",
"total_amount": 15234.50,
"count": 1250
},
{
"currency": "GT",
"total_amount": 500.00,
"count": 100
}
]
}
}
```