Get earnings¶

GET /v1/earnings

Return the total current value and total unrealized earnings across all of an address's positions, aggregated from live chain reads. Values are base-10 integer strings summed in each 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 earnings to aggregate (0x-prefixed hex).

Responses

Status	Description
`200`	The aggregate portfolio value and earnings.
`400`	Invalid userAddress (USER_003).
`500`	Storage failure (SYSTEM_001).

200 response

{
  "success": true,
  "data": {
    "userAddress": "0x7c3bd8a1f0a4d1a707f3b8f2eab6a95cbe8f1a3d",
    "totalValue": "25010500",
    "totalEarnings": "10500"
  },
  "timestamp": "2026-07-29T10:18:47.660Z"
}

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"
}