> ## 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 deposit-cap utilization
> Returns up-to-the-block totalSupplyInBase, supplyCap, and percentageFilled per chain each vault is deployed on. totalSupplyInBase and supplyCap are both denominated in the vault base asset, so they are directly comparable. The filter parameter is optional; narrow with the vaultAddress and/or chainId flags, or omit it to return every live vault deployment. Defaults: pageSize=25 (max 100); omit pageToken for the first page.
## OpenAPI
````yaml /v1.0.0/api-reference/openapi.yml get /v2/amplify/supplyCaps
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/supplyCaps:
get:
tags:
- Vaults
summary: List vault deposit-cap utilization
description: >-
Returns up-to-the-block totalSupplyInBase, supplyCap, and
percentageFilled per chain each vault is deployed on. totalSupplyInBase
and supplyCap are both denominated in the vault base asset, so they are
directly comparable. The filter parameter is optional; narrow with the
vaultAddress and/or chainId flags, or omit it to return every live vault
deployment. Defaults: pageSize=25 (max 100); omit pageToken for the
first page.
operationId: getSupplyCaps
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:
type: string
- name: filter
required: false
in: query
description: >-
Filter string. Optional flags: vaultAddress (hex), chainId (number).
Example: vaultAddress=0xbbbb000000000000000000000000000000000001 AND
chainId=84532
schema:
example: >-
vaultAddress=0xbbbb000000000000000000000000000000000001 AND
chainId=84532
type: string
responses:
'200':
description: List of supply-cap entries
content:
application/json:
schema:
$ref: '#/components/schemas/SupplyCapsResponseDto'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'503':
description: RPC unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
security:
- api-key: []
components:
schemas:
SupplyCapsResponseDto:
type: object
properties:
supplyCaps:
description: One entry per chain deployment.
type: array
items:
$ref: '#/components/schemas/SupplyCapEntryDto'
nextPageToken:
type: string
description: >-
Token for the next page. null when there are no more results. Always
present.
example: eyJvZmZzZXQiOjI1fQ==
nullable: true
required:
- supplyCaps
- nextPageToken
ErrorResponseDto:
type: object
properties:
error:
description: Error object containing details
allOf:
- $ref: '#/components/schemas/ErrorObjectDto'
required:
- error
SupplyCapEntryDto:
type: object
properties:
vaultAddress:
type: string
description: BoringVault contract address (lowercased).
example: '0xbbbb000000000000000000000000000000000001'
chainId:
type: number
description: EVM chain ID.
example: 84532
totalSupplyInBase:
type: string
description: >-
Total deposited value denominated in the vault base asset (computed
as totalSupply * shareToBaseRate). Comparable to `supplyCap`.
example: '1037.937273'
supplyCap:
type: string
description: >-
Deposit supply cap denominated in the vault base asset, or null when
the vault is uncapped.
example: '5000000.00'
nullable: true
percentageFilled:
type: string
description: >-
Percentage of supply cap currently filled, formatted with four
decimals (e.g. "20.7587"). Null when the vault is uncapped.
example: '20.3893'
nullable: true
required:
- vaultAddress
- chainId
- totalSupplyInBase
- supplyCap
- percentageFilled
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
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'
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__'
````