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

curl "https://api.renesis.fi/delegation/portfolio-management/get-positions?exchange_account_id=gate-perp-001" \
  -H "X-API-Key: $API_KEY"

Response Example

{
  "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

curl "https://api.renesis.fi/portfolio-management/exchange-account/perps/summary?exchange_account_id=hl_daed" \
  -H "X-API-Key: $API_KEY"

Response Example

{
  "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

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

{
  "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

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

{
  "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

curl "https://api.renesis.fi/portfolio-management/exchange-account/perps/rebates?exchange_account_id=gate_vip&currency=USDT" \
  -H "X-API-Key: $API_KEY"

Response Example

{
  "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
      }
    ]
  }
}

​Perps Analytics Endpoints

​GET /delegation/portfolio-management/get-positions

​Query Parameters

​Request Example

​Response Example

​Risk Metrics

​GET /portfolio-management/exchange-account/perps/summary

​Query Parameters

​Request Example

​Response Example

​Symbol Performance Metrics

​GET /portfolio-management/exchange-account/perps/fills

​Query Parameters

​Request Example

​Response Example

​GET /portfolio-management/exchange-account/perps/twap-orders

​Query Parameters

​Request Example

​Response Example

​TWAP Execution Metrics

​GET /portfolio-management/exchange-account/perps/rebates

​Query Parameters

​Request Example

​Response Example

Perps Analytics Endpoints

GET /delegation/portfolio-management/get-positions

Query Parameters

Request Example

Response Example

Risk Metrics

GET /portfolio-management/exchange-account/perps/summary

Query Parameters

Request Example

Response Example

Symbol Performance Metrics

GET /portfolio-management/exchange-account/perps/fills

Query Parameters

Request Example

Response Example

GET /portfolio-management/exchange-account/perps/twap-orders

Query Parameters

Request Example

Response Example

TWAP Execution Metrics

GET /portfolio-management/exchange-account/perps/rebates

Query Parameters

Request Example

Response Example