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

# Perpetuals

> Open positions and trade history for connected exchanges, including Hyperliquid.

Connect your exchange in CoinStats, then use `GET /v1/portfolio/list` or the MCP tool `get-portfolio-list` to find its `portfolioId`. Both endpoints accept an owned exchange or parent portfolio; omit `portfolioId` for all owned exchanges. Parent portfolios include their owned exchange descendants. Accounts created in the app or API are supported; watchlists and explorer portfolios are excluded.

| Endpoint | MCP tool | Returns |
| - | - | - |
| `GET /v1/portfolio/perpetual/positions` | `get-perpetual-positions` | Open positions, leverage, prices, unrealized P\&L and funding where available. |
| `GET /v1/portfolio/perpetual/trades` | `get-perpetual-trades` | Synced trade records with prices, realized P\&L and fees where available. |

Both are read-only and cost **10 credits per request**. Hyperliquid uses the same connected-portfolio flow as other exchanges.

```bash theme={null}
curl 'https://api.coinstats.app/v1/portfolio/perpetual/positions?portfolioId=example-portfolio' \
  -H 'X-API-KEY: <your-api-key>'

curl 'https://api.coinstats.app/v1/portfolio/perpetual/trades?portfolioId=example-portfolio&limit=20&skip=0' \
  -H 'X-API-KEY: <your-api-key>'
```

Positions use existing exchange connectors and CoinStats ticker-based P\&L. `currentPrice` is a reference ticker price; `unrealizedPnlUsd` excludes funding and fees. `returnOnEquity` is a ratio (`0.1` means 10%). `fundingSinceOpenUsd` is positive when received and negative when paid. Missing values and unavailable prices are `null`. Options are excluded. The top-level `updatedAt` is retrieval time in Unix milliseconds. Connector failures return an error instead of a successful empty result. Positions expose `coinId` when available; an unavailable symbol is `null`.

`realizedPnlUsd` follows the connector’s calculation: fees and funding may already be included. BingX includes both, so subtracting `tradingFeeUsd` again would double-count the fee. Trade `side` is `long`, `short`, or `null`.

Trade history reflects the last portfolio sync and existing connector coverage. Records may group executions into positions; an empty result does not establish that an account has never traded. `timestamp` and `closedAt` are opening and closing times in Unix milliseconds. Funding payment history is not included.

History is newest first by opening time. Use `limit` (1–100, default 20) and `skip` (0–10000, default 0), then `nextSkip` for another page. `null` means the end or the offset limit; a full page can be followed by an empty page. New trades can shift offsets between requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.