> ## 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.
# List vault compositions
> Returns current asset composition for vaults, including component weights and values. Defaults: pageSize=25 (max 100); omit pageToken for the first page.
## OpenAPI
````yaml /v0.5.2/api-reference/openapi.yml get /v2/amplify/vaultCompositions
openapi: 3.0.0
info:
title: Paxos Labs API
description: >
Paxos Labs API V2.
---
# API overview
This document describes shared behavior and conventions for the Paxos Labs
API (REST and GraphQL).
Health check
A **health** endpoint is available for orchestrators (GitHub Actions, etc).
| Item |
Details
|
| ------------ |
---------------------------------------------------------------------------------------
|
| **Path** | `GET /health` (no version prefix; no API key or rate limit
applied). |
| **Response** | `200` with Terminus-style JSON when healthy; `503` when
unhealthy (e.g. database down). |
**Docker / healthcheck:** If your healthcheck uses `curl` (e.g. `curl -f
http://localhost:3000/health`), ensure your image has curl installed. Base
images like `node:bullseye-slim` or `node:alpine` do not—install it (e.g.
`RUN apk add --no-cache curl` for Alpine).
GraphQL endpoint
A **GraphQL** API is available in addition to REST. Use it to query address
book and vault data with a single request and flexible field selection.
| Item |
Details |
| ---------------------------- |
-------------------------------------------------------------------- |
| **Altair (interactive IDE)** |
[https://api.paxoslabs.com/altair](https://api.paxoslabs.com/altair) |
| **GraphQL endpoint** | Same base URL with path `/graphql` for
POST. |
| **Authentication** | Same as REST: send `x-api-key`
header. |
Open the Altair link in a browser to explore the schema and run queries.
Filter query parameter syntax
List endpoints that support a `filter` query parameter use a single string
with **keys**, **operators**, and **combinators**. This keeps the number of
query params small (AIP-160 style) while allowing flexible filtering.
Operators
| Operator | Meaning | Example |
| -------- | ---------- | ------------------ |
| `=` | Equals | `chainId=1` |
| `!=` | Not equals | `status!=REFUNDED` |
Combinators
| Combinator | Meaning |
Example |
| ---------- | -------------------------------------------- |
------------------------------- |
| `AND` | All conditions must match (case-insensitive) | `chainId=1 AND
name="Treasury"` |
| `OR` | Any condition may match (case-insensitive) | `chainId=1 OR
chainId=137` |
Value formatting
| Type | Use case |
Example |
| -------- | ----------------------------------------- |
------------------------- |
| Unquoted | Numbers, booleans, single-token values | `chainId=1`,
`valid=true` |
| Quoted | Strings with spaces or special characters | `name="Treasury
Wallet"` |
| Escape | Literal quote inside a quoted string |
`\"` |
Allowed **keys** and **value types** (number, hex address, string, etc.) are
defined per endpoint in the API docs and validated by the server.
Possible combinations (examples)
| Category |
Example |
| --------------------- |
--------------------------------------------------- |
| Single condition |
`chainId=1` |
| Single condition |
`status!=REFUNDED` |
| AND | `chainId=1 AND
name="Treasury"` |
| AND | `vaultAddress=0x123... AND
chainId=1` |
| OR | `chainId=1 OR
chainId=137` |
| OR | `status=PENDING OR
status=COMPLETE` |
| Mixed AND and OR | `chainId=1 AND (status=PENDING OR
status=COMPLETE)` |
| Equals and not-equals | `chainId=1 AND
status!=REFUNDED` |
| Equals and not-equals |
`name!=""` |
Mixed AND and OR: AND has higher precedence; use parentheses for grouping.
Without grouping, evaluation is left-to-right per implementation.
Implementation note
| Item |
Details |
| --------- |
------------------------------------------------------------------------- |
| Location |
`src/common/utils/filter.util.ts` |
| Supported | `=`, `!=`, `AND`,
`OR` |
| Errors | Invalid keys or value types return `400` with the standard
error envelope |
version: '2.0'
contact: {}
servers:
- url: https://api.paxoslabs.com
description: Production
security: []
tags: []
paths:
/v2/amplify/vaultCompositions:
get:
tags:
- Amplify
summary: List vault compositions
description: >-
Returns current asset composition for vaults, including component
weights and values. Defaults: pageSize=25 (max 100); omit pageToken for
the first page.
operationId: AmplifyController_getVaultCompositions_v2
parameters:
- name: pageSize
required: false
in: query
description: 'Maximum items per page. Default: 25. Min: 1, max: 100.'
schema:
minimum: 1
maximum: 100
default: 25
example: 25
type: number
- name: pageToken
required: false
in: query
description: Opaque token for the next page. Omit for the first page.
schema:
example: eyJvZmZzZXQiOjI1fQ==
type: string
- name: filter
required: false
in: query
description: 'Filter string. Flags: chainId, vaultAddress. Optional.'
schema:
example: >-
chainId=1 AND
vaultAddress=0x1234567890abcdef1234567890abcdef12345678
type: string
responses:
'200':
description: List of vault compositions
content:
application/json:
schema:
$ref: '#/components/schemas/VaultCompositionsResponseDto'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'403':
description: >-
Invalid, inactive, or expired API key; IP not allowed; insufficient
scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
security:
- api-key: []
components:
schemas:
VaultCompositionsResponseDto:
type: object
properties:
vaultCompositions:
description: List of vault compositions
type: array
items:
$ref: '#/components/schemas/VaultCompositionDto'
nextPageToken:
type: string
description: >-
Token for the next page. null when there are no more results. Always
present.
example: eyJvZmZzZXQiOjI1fQ==
nullable: true
tokenMetadata:
type: object
description: Token metadata keyed by 'chainId:address'.
nullable: true
additionalProperties:
$ref: '#/components/schemas/TokenMetadataEntryDto'
required:
- vaultCompositions
- nextPageToken
ErrorResponseDto:
type: object
properties:
error:
description: Error object containing details
allOf:
- $ref: '#/components/schemas/ErrorObjectDto'
required:
- error
VaultCompositionDto:
type: object
properties:
vaultAddress:
type: string
description: Vault contract address
example: '0x1234567890abcdef1234567890abcdef12345678'
chainId:
type: number
description: Chain ID where the vault exists
example: 1
timestamp:
type: string
description: Timestamp for this snapshot (RFC 3339 UTC)
example: '2026-01-21T15:04:05Z'
components:
description: Components that make up the vault
type: array
items:
$ref: '#/components/schemas/VaultCompositionComponentDto'
required:
- vaultAddress
- chainId
- timestamp
- components
TokenMetadataEntryDto:
type: object
properties:
chain_id:
type: number
description: Chain ID
example: 1
address:
type: string
description: Token contract address
example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
name:
type: string
description: Token name
example: USD Coin
nullable: true
symbol:
type: string
description: Token symbol
example: USDC
nullable: true
decimals:
type: number
description: Token decimals
example: 6
nullable: true
token_standard:
type: string
description: Token standard (e.g., ERC20)
example: ERC20
nullable: true
coin_gecko_id:
type: string
description: CoinGecko token identifier
example: usd-coin
nullable: true
source:
type: string
description: Source of the metadata
nullable: true
first_seen_at:
type: string
description: Timestamp when the token was first seen
example: '2026-01-01T00:00:00Z'
metadata_refreshed_at:
type: string
description: Timestamp when metadata was last refreshed
example: '2026-03-01T00:00:00Z'
nullable: true
required:
- chain_id
- address
- first_seen_at
ErrorObjectDto:
type: object
properties:
code:
type: number
description: HTTP status code
example: 400
message:
type: string
description: Human-readable error message
example: Invalid filter syntax.
status:
type: string
description: Error status enum value
enum:
- UNKNOWN
- INVALID_ARGUMENT
- NOT_FOUND
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- INTERNAL
- METHOD_NOT_ALLOWED
example: INVALID_ARGUMENT
details:
description: Additional error details
type: array
items:
$ref: '#/components/schemas/ErrorDetailDto'
required:
- code
- message
- status
VaultCompositionComponentDto:
type: object
properties:
assetAddress:
type: string
description: Asset contract address
example: '0xabcdef1234567890abcdef1234567890abcdef12'
amount:
type: string
description: Amount of the asset as decimal string
example: '950.0'
value:
type: string
description: Value of the asset as decimal string
example: '1000.0'
valueAsset:
type: string
description: Asset denomination for value
example: USD
weight:
type: string
description: Weight of this component in the vault (0-1 decimal)
example: '0.25'
positionKind:
type: string
description: Stable machine-readable exposure/leg type for the position
enum:
- SPOT
- SUPPLY
- COLLATERAL
- DEBT
- STAKED
- PENDING
example: DEBT
instrumentType:
type: string
description: Stable machine-readable instrument type. Mirrors positionRef.type.
enum:
- ERC20
- NATIVE
- ERC4626_VAULT
- ERC721
- ERC1155
- UNI_V2_PAIR
- UNI_V3_POSITION
- CURVE_POOL
- BALANCER_POOL
- AAVE_V3_RESERVE
- COMPOUND_V2_CTOKEN
- COMPOUND_V3_MARKET
- MORPHO_V1_MARKET
- MORPHO_V1_VAULT
- MORPHO_V2_MARKET
- MORPHO_V2_VAULT
example: MORPHO_V1_VAULT
positionRef:
description: Stable instrument reference for this component
allOf:
- $ref: '#/components/schemas/VaultCompositionPositionRefDto'
required:
- assetAddress
- amount
- value
- valueAsset
- weight
- positionKind
- instrumentType
- positionRef
ErrorDetailDto:
type: object
properties:
'@type':
type: string
description: Type URL identifying the error detail schema
example: type.paxoslabs.dev/errors/BadRequest
fieldViolations:
description: Field-level violations for validation errors
type: array
items:
$ref: '#/components/schemas/FieldViolationDto'
required:
- '@type'
VaultCompositionPositionRefDto:
type: object
properties:
type:
type: string
description: Instrument type identity for the position reference
enum:
- ERC20
- NATIVE
- ERC4626_VAULT
- ERC721
- ERC1155
- UNI_V2_PAIR
- UNI_V3_POSITION
- CURVE_POOL
- BALANCER_POOL
- AAVE_V3_RESERVE
- COMPOUND_V2_CTOKEN
- COMPOUND_V3_MARKET
- MORPHO_V1_MARKET
- MORPHO_V1_VAULT
- MORPHO_V2_MARKET
- MORPHO_V2_VAULT
example: MORPHO_V1_VAULT
id:
type: string
description: >-
Instrument identifier (e.g., token address, market ID, pool ID,
token ID)
example: '0x123'
required:
- type
- id
FieldViolationDto:
type: object
properties:
field:
type: string
description: The field that caused the violation
example: filter
description:
type: string
description: Description of the violation
example: vaultAddress 0x0x is an invalid hex address.
required:
- field
- description
securitySchemes:
api-key:
type: apiKey
in: header
name: x-api-key
description: 'API key in format: pxl__'
````