Documentation Index
Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
Use this file to discover all available pages before exploring further.
GET /v2/amplify/userPositions returns a user’s shareBalance, positionValueInBase, baseAssetAddress, and exchangeRateToBase per chain each vault is deployed on. Use it to render a user’s holdings in a portfolio or vault detail view without re-implementing the share-to-base math client-side.
positionValueInBase is computed as shareBalance * exchangeRateToBase at the accountant contract’s current rate, so the value reflects up-to-the-block on-chain state.
userAddress is required as a top-level query parameter. filter is a
single AIP-160-style query parameter and is optional. The flags inside the
filter are also optional: vaultAddress (hex) scopes to one vault,
chainId (number) scopes to one chain. With no filter, the user’s position
is returned for every live vault deployment.Some vaults are deployed as stand-in vaults on a chain where the canonical
base asset isn’t natively available (e.g. soohoUSDGt on Base). In that case
the endpoint reports
baseAssetAddress from the on-chain accountant.base()
call. The endpoint transparently falls back to accountant.base() whenever
the DB has no baseAssetAddress for that deployment.Each response includes a
tokenMetadata map keyed by lowercase address,
populated for the vaultAddress and baseAssetAddress returned in
userPositions[]. Use it to render token symbols/decimals without making a
separate metadata call.Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userAddress | string | Yes | User wallet address (hex). Top-level query parameter — not part of the filter. |
filter | string | No | AIP-160-style filter. Optional flags: vaultAddress (hex), chainId (number). Both support OR. With no filter, every live vault deployment is returned. Example: vaultAddress=0xbbbb...0001 AND chainId=84532. |
pageSize | number | No | Maximum items per page. Default: 25. Min: 1, max: 100. |
pageToken | string | No | Opaque cursor returned as nextPageToken on the previous response. Omit for the first page. |
Example
- curl
- Node.js
- Python
- Go
Response
| Field | Type | Description |
|---|---|---|
userPositions[].vaultAddress | string | BoringVault contract address (lowercased) |
userPositions[].chainId | number | EVM chain ID for this entry |
userPositions[].shareBalance | string (decimal) | User share-token balance, human-readable (scaled by share decimals) |
userPositions[].positionValueInBase | string (decimal) | Position value denominated in the vault base asset (shareBalance * exchangeRateToBase), human-readable |
userPositions[].baseAssetAddress | string | Vault base asset contract address (lowercased); falls back to accountant.base() for stand-in vaults |
userPositions[].exchangeRateToBase | string (decimal) | Exchange rate of one share to the base asset, at the accountant contract’s current precision |
nextPageToken | string | null | Cursor for the next page. null when there are no more results. |
tokenMetadata | object | Map keyed by lowercase address with { symbol, decimals, ... }. Missing metadata is represented as null. |
Error Responses
| Status | Meaning |
|---|---|
| 400 | Missing or invalid userAddress, invalid filter (invalid hex address, unknown flag, non-positive chainId, malformed segment), or pageSize outside 1–100 |
| 503 | Upstream RPC unavailable |