# GET /api/v1/perps > Perp positions, orders and fills per venue, with when each venue was last read. Source: https://docs.getport.app/api/reference/perps/ ## Example The key is read from `PORT_API_KEY`, so the command never prints it. ```sh curl -s https://getport.app/api/v1/perps -H "Authorization: Bearer $PORT_API_KEY" ``` ## Response A 200 with the [envelope](https://docs.getport.app/api/#the-envelope) every endpoint answers, and this endpoint's answer in `data`. Amounts and USD figures are strings. What `data` looks like, with sample values: the shape is the schema's, checked when these pages are built, and the figures are made up, not anyone's port. ``` { "positions": [ { "id": "3f6c2a1e-8b7d-4e2f-9a1c-5d4b3e2f1a0c", "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "venue": "Hyperliquid", "market": "ETH-USD", "side": "long", "leverage": 5, "size": "2.5", "sizeAsset": "ETH", "entryUsd": "2390.10", "markUsd": "2476.50", "liquidationUsd": "1988.40", "fundingUsd": "-3.12", "unrealisedUsd": "216.00", "marginUsd": "1238.25", "notionalUsd": "6191.25", "marginMode": "cross", "roePct": 17.4, "maxLeverage": 25, "liqDistancePct": 19.7, "fundingHourlyPct": 0.0013, "fundingDailyUsd": "-1.93", "markChange24hPct": -0.8, "subAccount": null, "dex": "hyperliquid", "inVenueRows": false, "logoUrl": null, "quoteCurrency": "USDC" } ], "orders": [ { "id": "3f6c2a1e-8b7d-4e2f-9a1c-5d4b3e2f1a0c", "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "venue": "Hyperliquid", "market": "ETH-USD", "kind": "limit", "side": "buy", "size": "2.5", "sizeAsset": "ETH", "priceUsd": "2300.00", "status": "open", "reduceOnly": false, "triggerCondition": null } ], "fills": [ { "id": "3f6c2a1e-8b7d-4e2f-9a1c-5d4b3e2f1a0c", "at": "2026-10-06T05:42:10.000Z", "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "venue": "Hyperliquid", "market": "ETH-USD", "action": "Open long", "size": "2.5", "sizeAsset": "ETH", "priceUsd": "2390.10", "feeUsd": "2.15", "realisedUsd": "0.00" } ], "equityUsd": "2680.41", "marginUsedPct": 37, "funding7dUsd": "-13.51", "fees30dUsd": "18.40", "maintenanceMarginUsd": "309.56", "marginRatioPct": 11.5, "withdrawableUsd": "1442.16", "notionalUsd": "6191.25", "accountLeverage": 2.3, "fundingDailyUsd": "-1.93", "funding7dMeasured": false, "vaults": [ { "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "address": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "equityUsd": "2680.41", "lockedUntil": null } ], "subAccounts": [ { "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "name": "Scalps", "equityUsd": "2680.41" } ], "equityHistory": [ { "at": "2026-10-06T05:42:10.000Z", "equityUsd": "2680.41" } ], "pnlHistory": [ { "at": "2026-10-06T05:42:10.000Z", "pnlUsd": "216.00" } ], "netFlow7dUsd": "0.00", "volume7dUsd": "12382.50", "liquidations": [ { "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "at": "2026-10-06T05:42:10.000Z", "leverageType": "cross", "accountValueUsd": "940.00", "positions": [ { "market": "ETH-USD", "size": "2.5", "side": "long" } ] } ], "asOf": "2026-10-06T05:42:10.000Z", "venues": [ { "venue": "Hyperliquid", "equityUsd": "2680.41", "maintenanceMarginUsd": "309.56", "marginRatioPct": 11.5, "notionalUsd": "6191.25", "positions": 1, "unpriced": 3, "withheld": 1, "private": 1, "queuedUsd": "53.39", "asOf": "2026-10-06T05:42:10.000Z" } ], "accounts": [ { "walletAddress": "0x8f3c0e7b2a91d4c6f5e3b2a1908d7c6b5a4fc21a", "venue": "Hyperliquid", "subAccount": null, "equityUsd": "2680.41", "inVenueRows": false } ] } ``` | Field of `data` | Type | Always present | | ---------------------- | ----------------- | -------------- | | `positions` | `array of object` | yes | | `orders` | `array of object` | yes | | `fills` | `array of object` | yes | | `equityUsd` | `string` | yes | | `marginUsedPct` | `number` | yes | | `funding7dUsd` | `string` | yes | | `fees30dUsd` | `string` | yes | | `maintenanceMarginUsd` | `string` | no | | `marginRatioPct` | `number` | no | | `withdrawableUsd` | `string` | no | | `notionalUsd` | `string` | no | | `accountLeverage` | `number` | no | | `fundingDailyUsd` | `string` | no | | `funding7dMeasured` | `boolean` | no | | `vaults` | `array of object` | no | | `subAccounts` | `array of object` | no | | `equityHistory` | `array of object` | no | | `pnlHistory` | `array of object` | no | | `netFlow7dUsd` | `string or null` | no | | `volume7dUsd` | `string` | no | | `liquidations` | `array of object` | no | | `asOf` | `string or null` | no | | `venues` | `array of object` | no | | `accounts` | `array of object` | no | The whole schema of `data` As the OpenAPI document at [`https://getport.app/api/v1/openapi.json`](https://getport.app/api/v1/openapi.json) states it. Objects are left open, because a response only ever gains fields. ``` { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletAddress": { "type": "string" }, "venue": { "type": "string" }, "market": { "type": "string" }, "side": { "type": "string", "enum": [ "long", "short" ] }, "leverage": { "type": "number" }, "size": { "type": "string" }, "sizeAsset": { "type": "string" }, "entryUsd": { "type": "string" }, "markUsd": { "type": "string" }, "liquidationUsd": { "type": [ "string", "null" ] }, "fundingUsd": { "type": "string" }, "unrealisedUsd": { "type": "string" }, "marginUsd": { "type": "string" }, "notionalUsd": { "type": "string" }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ] }, "roePct": { "type": "number" }, "maxLeverage": { "type": "number" }, "liqDistancePct": { "type": [ "number", "null" ] }, "fundingHourlyPct": { "type": [ "number", "null" ] }, "fundingDailyUsd": { "type": [ "string", "null" ] }, "markChange24hPct": { "type": [ "number", "null" ] }, "subAccount": { "type": [ "string", "null" ] }, "dex": { "type": "string" }, "inVenueRows": { "type": "boolean" }, "logoUrl": { "type": [ "string", "null" ] }, "quoteCurrency": { "type": "string" } }, "required": [ "id", "walletAddress", "venue", "market", "side", "leverage", "size", "sizeAsset", "entryUsd", "markUsd", "liquidationUsd", "fundingUsd", "unrealisedUsd", "marginUsd" ] } }, "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletAddress": { "type": "string" }, "venue": { "type": "string" }, "market": { "type": "string" }, "kind": { "type": "string", "enum": [ "limit", "stop", "take_profit" ] }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "size": { "type": "string" }, "sizeAsset": { "type": "string" }, "priceUsd": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "trigger" ] }, "reduceOnly": { "type": "boolean" }, "triggerCondition": { "type": [ "string", "null" ] } }, "required": [ "id", "walletAddress", "venue", "market", "kind", "side", "size", "sizeAsset", "priceUsd", "status" ] } }, "fills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "walletAddress": { "type": "string" }, "venue": { "type": "string" }, "market": { "type": "string" }, "action": { "type": "string" }, "size": { "type": "string" }, "sizeAsset": { "type": "string" }, "priceUsd": { "type": "string" }, "feeUsd": { "type": "string" }, "realisedUsd": { "type": [ "string", "null" ] } }, "required": [ "id", "at", "walletAddress", "venue", "market", "action", "size", "sizeAsset", "priceUsd", "feeUsd", "realisedUsd" ] } }, "equityUsd": { "type": "string" }, "marginUsedPct": { "type": "number" }, "funding7dUsd": { "type": "string" }, "fees30dUsd": { "type": "string" }, "maintenanceMarginUsd": { "type": "string" }, "marginRatioPct": { "type": "number" }, "withdrawableUsd": { "type": "string" }, "notionalUsd": { "type": "string" }, "accountLeverage": { "type": "number" }, "fundingDailyUsd": { "type": "string" }, "funding7dMeasured": { "type": "boolean" }, "vaults": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "address": { "type": "string" }, "equityUsd": { "type": "string" }, "lockedUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "walletAddress", "address", "equityUsd", "lockedUntil" ] } }, "subAccounts": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "name": { "type": "string" }, "equityUsd": { "type": "string" } }, "required": [ "walletAddress", "name", "equityUsd" ] } }, "equityHistory": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "equityUsd": { "type": "string" } }, "required": [ "at", "equityUsd" ] } }, "pnlHistory": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "pnlUsd": { "type": "string" } }, "required": [ "at", "pnlUsd" ] } }, "netFlow7dUsd": { "type": [ "string", "null" ] }, "volume7dUsd": { "type": "string" }, "liquidations": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "leverageType": { "type": "string", "enum": [ "cross", "isolated" ] }, "accountValueUsd": { "type": "string" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": "string" }, "size": { "type": "string" }, "side": { "type": "string", "enum": [ "long", "short" ] } }, "required": [ "market", "size", "side" ] } } }, "required": [ "walletAddress", "at", "leverageType", "accountValueUsd", "positions" ] } }, "asOf": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "venues": { "type": "array", "items": { "type": "object", "properties": { "venue": { "type": "string" }, "equityUsd": { "type": "string" }, "maintenanceMarginUsd": { "type": "string" }, "marginRatioPct": { "type": "number" }, "notionalUsd": { "type": "string" }, "positions": { "type": "number" }, "unpriced": { "type": "number" }, "withheld": { "type": "number" }, "private": { "type": "number" }, "queuedUsd": { "type": "string" }, "asOf": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "venue", "equityUsd", "maintenanceMarginUsd", "marginRatioPct", "notionalUsd", "positions", "asOf" ] } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "venue": { "type": "string" }, "subAccount": { "type": [ "string", "null" ] }, "equityUsd": { "type": "string" }, "inVenueRows": { "type": "boolean" } }, "required": [ "walletAddress", "venue", "subAccount", "equityUsd", "inVenueRows" ] } } }, "required": [ "positions", "orders", "fills", "equityUsd", "marginUsedPct", "funding7dUsd", "fees30dUsd" ] } ``` ## From an agent The MCP tool `port_perps` answers the same question ("what perps do I have open") with the same figures, over the [MCP server](https://docs.getport.app/api/mcp/). ## Refusals Every endpoint shares three: `401` for a missing or dead key, `402` for an account whose plan has no API ("Agents, MCP and the API are on Pro+ and above."), and `429` past the minute or day limit. The [errors](https://docs.getport.app/api/#errors) section has each body.