GET /api/v1/positions
DeFi accounts: one protocol on one chain in one wallet, with what is inside it.
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", "chainId": "ethereum", "protocol": "aave-v3", "category": "lending", "detail": "Supplied on Aave v3", "valueUsd": "10401.30", "counted": true, "meta": "Ethereum", "direction": "up", "claimableUsd": "12.40", "healthFactor": 1.84, "lltvPct": 82.5, "progressPct": 4.2, "unlocksAt": null, "gradual": false, "yield30dUsd": "17.90", "url": null, "source": "interpreted", "liability": false, "venue": false, "kind": "supplied", "amount": "4.2", "symbol": "ETH", "logoUrl": null, "asOf": "2026-10-06T05:42:10.000Z", "supplyApy": 2.1, "borrowApy": 4.6, "maxLtvPct": 80, "ratesAsOf": "2026-10-06T05:42:10.000Z", "change24hPct": "-0.8", "positionKey": null, "heldToken": null, "backs": null, "range": { "lower": 2100, "upper": 2900, "current": 2476.5, "inRange": true, "base": "ETH", "quote": "USDC", "band": { "start": 2300, "end": 2650 }, "at": 2476.5, "beyond": false }, "maturesAt": null, "spam": false, "spamReason": null, "hiddenByYou": false } ]}Field of data | Type | Always present |
|---|---|---|
positions | array of object | yes |
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" }, "chainId": { "type": "string" }, "protocol": { "type": "string" }, "category": { "type": "string", "enum": [ "staking", "lending", "liquidity", "perps", "vault", "other" ] }, "detail": { "type": "string" }, "valueUsd": { "type": "string" }, "counted": { "type": "boolean" }, "meta": { "type": "string" }, "direction": { "type": "string", "enum": [ "up", "down", "neutral" ] }, "claimableUsd": { "type": [ "string", "null" ] }, "healthFactor": { "type": [ "number", "null" ] }, "lltvPct": { "type": [ "number", "null" ] }, "progressPct": { "type": [ "number", "null" ] }, "unlocksAt": { "type": [ "string", "null" ] }, "gradual": { "type": "boolean" }, "yield30dUsd": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "interpreted", "bought", "unrecognised" ] }, "liability": { "type": "boolean" }, "venue": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "supplied", "borrowed", "collateral", "staked", "locked", "reward", "liquidity", "vault", "spot", "other" ] }, "amount": { "type": [ "string", "null" ] }, "symbol": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "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" } ] }, "supplyApy": { "type": [ "number", "null" ] }, "borrowApy": { "type": [ "number", "null" ] }, "maxLtvPct": { "type": [ "number", "null" ] }, "ratesAsOf": { "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" } ] }, "change24hPct": { "type": [ "string", "null" ] }, "positionKey": { "type": [ "string", "null" ] }, "heldToken": { "type": [ "string", "null" ] }, "backs": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "range": { "anyOf": [ { "type": "object", "properties": { "lower": { "type": [ "number", "null" ] }, "upper": { "type": [ "number", "null" ] }, "current": { "type": "number" }, "inRange": { "type": "boolean" }, "base": { "type": "string" }, "quote": { "type": "string" }, "band": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" } }, "required": [ "start", "end" ] }, "at": { "type": "number" }, "beyond": { "type": "boolean" } }, "required": [ "lower", "upper", "current", "inRange", "base", "quote", "band", "at", "beyond" ] }, { "type": "null" } ] }, "maturesAt": { "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" } ] }, "spam": { "type": "boolean" }, "spamReason": { "type": [ "string", "null" ] }, "hiddenByYou": { "type": "boolean" } }, "required": [ "id", "walletAddress", "chainId", "protocol", "category", "detail", "valueUsd", "meta", "direction" ] } } }, "required": [ "positions" ]}From an agent
Section titled “From an agent”The MCP tool port_positions answers the same question ("what do I have in DeFi") 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.