# GET /api/v1/positions > DeFi accounts: one protocol on one chain in one wallet, with what is inside it. Source: https://docs.getport.app/api/reference/positions/ ## Example The key is read from `PORT_API_KEY`, so the command never prints it. ```sh curl -s https://getport.app/api/v1/positions -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", "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`](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 The MCP tool `port_positions` answers the same question ("what do I have in DeFi") 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.