Skip to content
Reference

GET /api/v1/perps

Perp positions, orders and fills per venue, with when each venue was last read.

The key is read from PORT_API_KEY, so the command never prints it.

curl -s https://getport.app/api/v1/perps -H "Authorization: Bearer $PORT_API_KEY"

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 dataTypeAlways present
positionsarray of objectyes
ordersarray of objectyes
fillsarray of objectyes
equityUsdstringyes
marginUsedPctnumberyes
funding7dUsdstringyes
fees30dUsdstringyes
maintenanceMarginUsdstringno
marginRatioPctnumberno
withdrawableUsdstringno
notionalUsdstringno
accountLeveragenumberno
fundingDailyUsdstringno
funding7dMeasuredbooleanno
vaultsarray of objectno
subAccountsarray of objectno
equityHistoryarray of objectno
pnlHistoryarray of objectno
netFlow7dUsdstring or nullno
volume7dUsdstringno
liquidationsarray of objectno
asOfstring or nullno
venuesarray of objectno
accountsarray of objectno
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"
]
}

The MCP tool port_perps answers the same question ("what perps do I have open") with the same figures, over the MCP server.

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.