Skip to Content
RestPools

Pools

Base: /api/v1

Request bodies that include userId use your external user id (see Users — Identity model).

Overview

EndpointPurpose
POST /getUserPoolsPools where this user has a deposit, with that user’s balance and position in each pool (amounts, USD value, locked vs available, strategies, swap rollups). Optional chainId filter.
POST /getTokenBalanceOne user’s pool token balance for a specific tokenAddress on a chain (raw amounts aligned with getUserPools deposit fields). Documented under Users.
POST /getClientPoolsIntegration-wide list of pools that have at least one pool deposit from any user under your API key. Optional chainId filter. Does not include per-user balance detail.
GET /pools/{poolId}Single pool record by id (pool metadata).

The same POST /getUserPools and POST /getTokenBalance flows are documented under Users for convenience when you are working in a user context.

Typical status codes

  • 200: success
  • 401: invalid or missing API key/secret
  • 404: user not found (getUserPools), or pool not found (GET /pools/{poolId})

POST /getUserPools

Body: userId (required, external user id), chainId (optional filter).

The integration layer resolves userId to an internal user, then loads pool positions via UserPoolsService.getUserPools (see integrations.service.ts).

Response (UserPoolsResponse)

Top-level fields:

FieldTypeDescription
poolsUserPoolItem[]One entry per pool where this user has a non-disabled deposit.
tokenOverallValuestringAggregated token USD value across those pools (formatted).
tokenOverallNativeValuestringSame roll-up expressed in native terms (formatted).
tokenOverallAvailableValuestringAggregated available balance USD value (unlocked position).

Each UserPoolItem combines Pool metadata, PoolVolumeTotals, per-user rollups (tokenValue, userBalance, totalBalanceAvailable, hasActiveStrategies), and deposits (PoolDeposit[] with balances, locks, values, optional nested strategies).

Example response (UserPoolsResponse)
{
  "pools": [
    {
      "id": 1,
      "name": "USDC",
      "symbol": "USDC",
      "decimals": 6,
      "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "chainId": 8453,
      "tokenPrice": "1.00",
      "deposits": [
        {
          "id": 101,
          "userBalance": "100000000",
          "lockedAmount": "0",
          "lockedNativeAmount": "0",
          "value": "100.00",
          "currentClaimableValue": "0.02"
        }
      ],
      "tokenValue": "100.00",
      "userBalance": "100.0",
      "totalBalanceAvailable": "100.0",
      "hasActiveStrategies": false,
      "totalBoughtFromStrategies": 0,
      "totalSoldFromStrategies": 0,
      "totalBoughtFromSwaps": 0,
      "totalSoldFromSwaps": 0,
      "totalBought": 0,
      "totalSold": 0
    }
  ],
  "tokenOverallValue": "100.00",
  "tokenOverallNativeValue": "0.03",
  "tokenOverallAvailableValue": "100.00"
}

POST /getUserPools — examples

curl -X POST "https://partners.sonar.trade/api/v1/getUserPools" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-API-Secret: <API_SECRET>" \
  -d '{"userId":"client-user-001","chainId":8453}'

POST /getClientPools

Body: optional chainId. Returns an array of Pool.

Example response (Pool[])
[
  {
    "id": 1,
    "name": "USDC",
    "symbol": "USDC",
    "chainId": 8453,
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "decimals": 6
  }
]

POST /getClientPools

curl -X POST "https://partners.sonar.trade/api/v1/getClientPools" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-API-Secret: <API_SECRET>" \
  -d '{"chainId":1399811149}'

GET /pools/{poolId}

Returns Pool.

Example response (Pool)
{
  "id": 1,
  "name": "USDC",
  "symbol": "USDC",
  "decimals": 6,
  "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "chainId": 8453,
  "tokenPrice": "1.00"
}

GET /pools/{poolId}

curl -X GET "https://partners.sonar.trade/api/v1/pools/123" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-API-Secret: <API_SECRET>"
OperationsStrategies