> ## 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 Supply Caps

> Read up-to-the-block total deposits, supply cap, and percentage filled per chain

`GET /v2/amplify/supplyCaps` returns up-to-the-block `totalSupplyInBase`, `supplyCap`, and `percentageFilled` per chain each vault is deployed on. Use it to render deposit-cap utilization (e.g. a progress bar) on a deposit screen, or to soft-block deposits that would exceed the cap before sending them on-chain.

`totalSupplyInBase` and `supplyCap` are both denominated in the vault base asset, so they are directly comparable without any unit conversion in the UI.

<Info>
  `filter` is a single AIP-160-style query parameter and is optional. Both
  flags inside the filter are optional: `vaultAddress` (hex) scopes to one
  vault, `chainId` (number) scopes to one chain. With no filter, every live
  vault deployment is returned.
</Info>

<Info>
  Uncapped vaults return `supplyCap: null` and `percentageFilled: null`. A vault
  is uncapped when `supplyCapInBase()` on-chain returns `0` or `2^256 - 1`, or
  when the deployment predates the supply-cap upgrade (no deposit fee module
  configured). Render those as "uncapped" in the UI rather than treating `null`
  as an error.
</Info>

## Parameters

| Parameter   | Type     | Required | Description                                                                                                                                                                                                          |
| ----------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    # Every live deployment, no filter
    curl --get "https://api.paxoslabs.com/v2/amplify/supplyCaps" \
      -H "x-api-key: pxl_your_key"

    # Scoped to one vault and one chain
    curl --get "https://api.paxoslabs.com/v2/amplify/supplyCaps" \
      --data-urlencode "filter=vaultAddress=0xbbbb000000000000000000000000000000000001 AND chainId=84532" \
      -H "x-api-key: pxl_your_key"
    ```
  </Tab>

  <Tab title="Node.js">
    ```ts theme={null}
    const url = new URL("https://api.paxoslabs.com/v2/amplify/supplyCaps");
    // Optional: scope to one vault and chain.
    url.searchParams.set(
      "filter",
      "vaultAddress=0xbbbb000000000000000000000000000000000001 AND chainId=84532"
    );

    const resp = await fetch(url, {
      headers: { "x-api-key": process.env.AMPLIFY_API_KEY! },
    });
    const { supplyCaps } = await resp.json();
    for (const entry of supplyCaps) {
      const pct = entry.percentageFilled === null ? "uncapped" : `${entry.percentageFilled}%`;
      console.log(`${entry.chainId}: ${entry.totalSupplyInBase} / ${entry.supplyCap ?? "∞"} (${pct})`);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    resp = requests.get(
        "https://api.paxoslabs.com/v2/amplify/supplyCaps",
        headers={"x-api-key": "pxl_your_key"},
        # filter is optional — omit to return every live deployment.
        params={
            "filter": (
                "vaultAddress=0xbbbb000000000000000000000000000000000001 "
                "AND chainId=84532"
            ),
        },
    )
    for entry in resp.json()["supplyCaps"]:
        pct = f'{entry["percentageFilled"]}%' if entry["percentageFilled"] is not None else "uncapped"
        cap = entry["supplyCap"] or "∞"
        print(f"{entry['chainId']}: {entry['totalSupplyInBase']} / {cap} ({pct})")
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // filter is optional — omit to return every live deployment.
    params := url.Values{
        "filter": {"vaultAddress=0xbbbb000000000000000000000000000000000001 AND chainId=84532"},
    }
    req, _ := http.NewRequest("GET",
        "https://api.paxoslabs.com/v2/amplify/supplyCaps?"+params.Encode(),
        nil)
    req.Header.Set("x-api-key", os.Getenv("AMPLIFY_API_KEY"))
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    ```
  </Tab>
</Tabs>

## Response

```json theme={null}
{
  "supplyCaps": [
    {
      "vaultAddress": "0xbbbb000000000000000000000000000000000001",
      "chainId": 84532,
      "totalSupplyInBase": "1037.937273",
      "supplyCap": "5000.00",
      "percentageFilled": "20.7587"
    }
  ],
  "nextPageToken": null
}
```

| Field                            | Type                       | Description                                                                                                                                                        |
| -------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `supplyCaps[].vaultAddress`      | `string`                   | BoringVault contract address (lowercased)                                                                                                                          |
| `supplyCaps[].chainId`           | `number`                   | EVM chain ID for this entry                                                                                                                                        |
| `supplyCaps[].totalSupplyInBase` | `string` (decimal)         | Total deposited value denominated in the vault base asset (computed as `totalSupply * shareToBaseRate`); directly comparable to `supplyCap`                        |
| `supplyCaps[].supplyCap`         | `string \| null` (decimal) | Deposit supply cap denominated in the vault base asset, or `null` when the vault is uncapped                                                                       |
| `supplyCaps[].percentageFilled`  | `string \| null`           | Percentage of supply cap currently filled, formatted with four decimals (e.g. `"20.7587"`). Clamped to `"100.0000"` if over-cap. `null` when the vault is uncapped |
| `nextPageToken`                  | `string \| null`           | Cursor for the next page. `null` when there are no more results.                                                                                                   |

## Error Responses

| Status | Meaning                                                                                                                     |
| ------ | --------------------------------------------------------------------------------------------------------------------------- |
| 400    | Invalid `filter` (invalid hex address, unknown flag, non-positive `chainId`, malformed segment) or `pageSize` outside 1–100 |
| 503    | Upstream RPC unavailable                                                                                                    |