List positions¶

GET /v1/positions

Return every recorded vault position for an address. Share counts and current values are read live from the chain; unrealized earnings are the current value minus the recorded cost basis. All monetary values are base-10 integer strings in the asset's smallest unit.

Authentication

Send your API key in the api-key header.

Parameters

Name	In	Type	Required	Description
`userAddress`	query	string	yes	The EOA address whose positions to list (0x-prefixed hex).

Responses

Status	Description
`200`	The address's positions.
`400`	Invalid userAddress (USER_003).
`500`	Storage failure (SYSTEM_001).

200 response

{
  "success": true,
  "data": [
    {
      "chain": 84532,
      "venueId": "mockvault-84532",
      "vault": "0x9d4454b023096f34b160d6b654540c56a1f81688",
      "asset": "0x81ab7e0d570b01411fcefcbbcd7de70890a5dd15",
      "shares": "24998100",
      "currentValue": "25010500",
      "costBasis": "25000000",
      "unrealizedEarnings": "10500"
    }
  ],
  "timestamp": "2026-07-29T10:18:44.201Z"
}

400 response

{
  "success": false,
  "error": {
    "code": "USER_003",
    "message": "Invalid user address",
    "category": "USER",
    "traceId": "a1b2c3d4e5f60718"
  },
  "timestamp": "2026-07-29T10:15:32.123Z"
}

500 response

{
  "success": false,
  "error": {
    "code": "SYSTEM_001",
    "message": "Database operation failed",
    "category": "SYSTEM",
    "traceId": "a1b2c3d4e5f60718"
  },
  "timestamp": "2026-07-29T10:15:32.123Z"
}