GET /api/v1/perps
Perp positions, orders and fills per venue, with when each venue was last read.
Example
Section titled “Example”The key is read from PORT_API_KEY, so the command never prints it.
Response
Section titled “Response”A 200 with 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 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
Section titled “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.
Refusals
Section titled “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 section has each body.