GET /api/v1/positions/pnl

Per-position P&L decomposition

Per-position P&L decomposition.

operationId: fetchPositionsPnlV1

Declared server differs from the callable one. This path declares its own servers base of https://exchange.nexus.xyz, without the /api/exchange mount the document default carries. Measured 2026-09-02, the override is not routed — https://exchange.nexus.xyz/api/v1/positions/pnl returns 404 while the gateway form in the sample below is routed. A client generated from this contract will aim at the override; pin the gateway base until the per-network hosts are live. See Networks.

Not reachable through CCXT. Unrealised PnL breakdown. CCXT carries PnL inside the position shape, so this has no separate method.

Authentication: hmacAuth.

Each open position's P&L split into price, funding and fee components. One entry per open position; an account with none gets an empty array.

Read the sign note on PositionPnl.funding_pnl before using it alongside /positions. The two operations report the same funding cash flow with opposite signs, deliberately.

Served from indexer-local projections, so it does not touch the engine and is safe to poll independently of /positions.

The /api/v1 spelling of the same operation, served by the direct indexer mount. account_position_routes() mounts this route at both the legacy root path and this prefix, so the two are the same handler and the same cost.

Responses

Status	Body	Meaning
200	array of PositionPnl	The account's open positions, with P&L decomposed.
401	— (no schema declared)	—
429	— (no schema declared)	—

Example

cURL

curl -X GET 'https://exchange.nexus.xyz/api/exchange/api/v1/positions/pnl' \
  -H 'X-API-Key: nx_7f3a1b...' \
  -H 'X-Timestamp: 1776033911836' \
  -H 'X-Signature: <hmac-sha256>'

Python

import requests

headers = {
    "X-API-Key": "nx_7f3a1b...",
    "X-Timestamp": "1776033911836",
    "X-Signature": "<hmac-sha256>"
}

response = requests.get("https://exchange.nexus.xyz/api/exchange/api/v1/positions/pnl", headers=headers)
response.raise_for_status()
print(response.json())

TypeScript

const response = await fetch("https://exchange.nexus.xyz/api/exchange/api/v1/positions/pnl", {
  method: "GET",
  headers: {
    "X-API-Key": "nx_7f3a1b...",
    "X-Timestamp": "1776033911836",
    "X-Signature": "<hmac-sha256>"
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

X-Signature is a placeholder: it is derived from this specific request. See Authentication for the canonical string and the HMAC rule.

---

_{Generated from eng/apps/exchange/api/openapi.json (spec 0.9.36). Do not edit by hand — regenerate with python3 product/docs/tools/api-reference/generate.py. Hand-authored context lives in the Guides pages.}