> For the complete documentation index, see [llms.txt](https://docs.veda.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veda.tech/api/vaults.md).

# Vaults

Endpoints for discovering the vaults that belong to your organization and inspecting state on a specific vault. The API uses a "tenant" to represent your organization. All endpoints are tenant-scoped — the tenant is resolved from your API key, and vaults outside your tenancy are not visible.

For authentication, base URL, request/response conventions, and the error envelope, see the [API Reference](https://docs.veda.tech/api/api-reference.md). Create an API key first via [Quick Start](https://docs.veda.tech/api/quick-start.md). Examples below assume the key is in `$VEDA_API_KEY`.

## Concepts

A **vault** is a set of smart contracts — built on Veda's BoringVault architecture — that abstracts DeFi complexity via a risk manager (also referred to as a curator), and adds enterprise compliance controls. A vault generates yield by allocating depositor funds, per the curator's instructions, to trusted DeFi protocols using predefined yield strategies. Depositors receive **vault receipt tokens** that prove ownership of their deposited funds, and only depositors can withdraw — not Veda, not the curator.

A vault can be deployed on one or more chains; the same `vault_address` appears on each chain it's been deployed to. Its Manager contract on each chain holds that chain's current **merkle root** — a single onchain commitment to the allowlist of actions the curator (or a delegated strategist) is permitted to execute there. For how the allowlist works and how the underlying tree is structured, see [Policy Manager & Merkle Trees](https://docs.veda.tech/api/policy-manager-and-merkle-trees.md).

{% hint style="info" %}
**Tenant denial returns 404, not 403.** Asking for a vault that isn't part of your tenant returns `404 vault_not_found` — the API does not distinguish "doesn't exist" from "exists but not yours."
{% endhint %}

***

## 1. List vaults

```
GET /v1/vaults
```

Returns the vaults that belong to the tenant on your API key, across every chain.

### Query parameters

| Name     | Type   | Required | Notes                                                                                 |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `cursor` | string | No       | Opaque cursor from a previous response's `page.next_cursor` — omit on the first call. |

### Example request

```bash
curl https://api.veda.tech/v1/vaults \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "vault_address": "0xFDea370fa75353e650Cd6b8055600B04a47F68c2",
      "name":          "Veda Demo Vault",
      "chains":        ["ethereum", "monad"],
      "tenant":        "veda-demo",
      "deployed_at":   "2026-06-03T07:16:26.467008Z",
      "status":        "active",
      "links": {
        "ethereum": {
          "self":  "/vaults/ethereum/0xFDea370fa75353e650Cd6b8055600B04a47F68c2",
          "roots": "/vaults/ethereum/0xFDea370fa75353e650Cd6b8055600B04a47F68c2/roots"
        },
        "monad": {
          "self":  "/vaults/monad/0xFDea370fa75353e650Cd6b8055600B04a47F68c2",
          "roots": "/vaults/monad/0xFDea370fa75353e650Cd6b8055600B04a47F68c2/roots"
        }
      }
    }
  ],
  "page": {
    "next_cursor": "AXsiYWZ0ZXIiOnsiZGVwbG95ZWRfYXQiOiIyMDI2…",
    "page_size":   20,
    "has_more":    true
  }
}
```

* `chains` is the set of chains the vault is deployed on.
* `links` is keyed by chain — each chain has its own `self` and `roots` resource. The link strings are returned unversioned (no `/v1/` prefix); they're resource paths relative to the API host. Prepend `/v1` (or the base URL) when calling them.

### Errors

| Status | Code              | Cause                                |
| ------ | ----------------- | ------------------------------------ |
| `401`  | `unauthenticated` | Missing, expired, or revoked API key |
| `429`  | `rate_limited`    | API key rate limit exceeded          |

See [API Reference → Errors](https://docs.veda.tech/api/api-reference.md#errors) for the envelope and the shape of authentication / rate-limit responses.

***

## 2. Get the latest metrics snapshot

```
GET /v1/vaults/{chain}/{vault_address}/metrics/snapshot/latest
```

Returns the most recent metrics snapshot for a vault on a given chain. Snapshots are produced daily by the share-price runner and capture share price, total assets, total supply, per-protocol position breakdown, and asset prices — all at a specific block.

### Path parameters

| Name            | Type   | Notes                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `chain`         | string | Lowercase chain slug — see [Chain Support](https://docs.veda.tech/resources/chain-support.md) |
| `vault_address` | string | The BoringVault contract address                                                              |

### Example request

```bash
curl https://api.veda.tech/v1/vaults/monad/0x1C8a336051D2024E318A229d01F9F6CF96efD316/metrics/snapshot/latest \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

### Example response

```json
{
  "data": {
    "chain":         "monad",
    "vault_address": "0x1C8a336051D2024E318A229d01F9F6CF96efD316",
    "block_number":  84732067,
    "as_of":         "2026-06-30T18:12:51Z",
    "snapshot_type": "yield_streaming",
    "share_price":   "1.001557",
    "total_assets":  "6749.023149",
    "total_supply":  "6737.890909",
    "positions": [
      { "protocol": "ERC20Position",          "asset": "USDC", "balance": "0.00861"     },
      { "protocol": "ERC20Position",          "asset": "mUSD", "balance": "337.201012"  },
      { "protocol": "SteakhouseCorePosition", "asset": "USDC", "balance": "1320.265712" },
      { "protocol": "SteakhouseCorePosition", "asset": "mUSD", "balance": "5091.547819" }
    ],
    "prices": {
      "monad": {
        "USDC": "1",
        "mUSD": "1"
      }
    },
    "base_asset": "mUSD",
    "yield_streaming": {
      "vested_amount":            "0.641343854687",
      "vesting_duration_seconds": 43200
    }
  }
}
```

* `as_of` is the ISO-8601 UTC timestamp of the snapshot's source block; `block_number` is that block.
* `snapshot_type` indicates the metric model used for this vault (e.g. `yield_streaming`). Type-specific fields (like the `yield_streaming` block below) only appear when the corresponding `snapshot_type` is active.
* `share_price`, `total_assets`, `total_supply`, position `balance`s, prices in `prices`, and `yield_streaming.vested_amount` are returned as **strings** to preserve full precision for assets whose values can fall outside safe float ranges.
* `positions` is the per-protocol breakdown of vault holdings as of `block_number`. Each entry is `{ protocol, asset, balance }`. To value a position in the vault's base asset, look up its price at `prices[chain][asset]` and multiply: `balance × price`.
* `prices` is a top-level chain → asset → string-price map. The base case is one chain (the vault's own); the structure leaves room for cross-chain holdings.
* `base_asset` is the asset that `share_price`, `total_assets`, and `total_supply` are denominated in. May come back as `"unknown"` for snapshots where the base asset hasn't been resolved yet.
* `yield_streaming` is present only when `snapshot_type` is `yield_streaming` — see [About yield streaming](#about-yield-streaming) below for what these fields represent and why the vault uses this model.

### About yield streaming

Yield-streaming vaults distribute earned yield linearly into the share price over a configurable vesting window, instead of applying it as a single rate jump. This defends against MEV and other value-extraction attacks on discrete rate updates — an attacker who front-runs a rate jump only captures the sliver of yield that has vested between their deposit and its execution, so the attack isn't profitable.

When `snapshot_type` is `yield_streaming`, the `yield_streaming` block on the response reports the current vesting tranche:

* **`vested_amount`** (string, denominated in `base_asset`) — the size of the yield tranche being streamed into the share price over the current window. This entire amount accrues into `share_price` linearly across the window.
* **`vesting_duration_seconds`** (int) — length of the vesting window in seconds. Production vaults typically use `43200` (12 hours).

### Errors

| Status | Code              | Cause                                                        |
| ------ | ----------------- | ------------------------------------------------------------ |
| `401`  | `unauthenticated` | Missing, expired, or revoked API key                         |
| `404`  | `vault_not_found` | Vault does not exist on this chain, or is not in your tenant |
| `429`  | `rate_limited`    | API key rate limit exceeded                                  |

***

## 3. List metrics snapshot history

```
GET /v1/vaults/{chain}/{vault_address}/metrics/snapshot
```

Returns the history of metrics snapshots for a vault on a given chain — newest first. Each entry has the same shape as [Get the latest metrics snapshot](#id-2.-get-the-latest-metrics-snapshot). Cursor-paginated.

### Path parameters

| Name            | Type   | Notes                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `chain`         | string | Lowercase chain slug — see [Chain Support](https://docs.veda.tech/resources/chain-support.md) |
| `vault_address` | string | The BoringVault contract address                                                              |

### Query parameters

| Name     | Type   | Required | Notes                                                                                 |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `cursor` | string | No       | Opaque cursor from a previous response's `page.next_cursor` — omit on the first call. |

### Example request

```bash
curl https://api.veda.tech/v1/vaults/monad/0x1C8a336051D2024E318A229d01F9F6CF96efD316/metrics/snapshot \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

### Example response (abbreviated)

```json
{
  "data": [
    {
      "chain":           "monad",
      "vault_address":   "0x1C8a336051D2024E318A229d01F9F6CF96efD316",
      "block_number":    84732067,
      "as_of":           "2026-06-30T18:12:51Z",
      "snapshot_type":   "yield_streaming",
      "share_price":     "1.001557",
      "total_assets":    "6749.023149",
      "total_supply":    "6737.890909",
      "positions":       [ /* … */ ],
      "prices":          { "monad": { "USDC": "1", "mUSD": "1" } },
      "base_asset":      "mUSD",
      "yield_streaming": { "vested_amount": "0.641343854687", "vesting_duration_seconds": 43200 }
    },
    {
      "chain":           "monad",
      "vault_address":   "0x1C8a336051D2024E318A229d01F9F6CF96efD316",
      "block_number":    84620800,
      "as_of":           "2026-06-30T05:51:27Z",
      "snapshot_type":   "yield_streaming",
      "share_price":     "1.001501",
      "total_assets":    "6642.001144",
      "total_supply":    "6631.681047",
      "positions":       [ /* … */ ],
      "prices":          { "monad": { "mUSD": "1", "USDC": "1" } },
      "base_asset":      "mUSD",
      "yield_streaming": { "vested_amount": "0.365943748453", "vesting_duration_seconds": 43200 }
    }
  ],
  "page": {
    "next_cursor": null,
    "page_size":   20,
    "has_more":    false
  }
}
```

### Errors

| Status | Code              | Cause                                                        |
| ------ | ----------------- | ------------------------------------------------------------ |
| `401`  | `unauthenticated` | Missing, expired, or revoked API key                         |
| `404`  | `vault_not_found` | Vault does not exist on this chain, or is not in your tenant |
| `429`  | `rate_limited`    | API key rate limit exceeded                                  |

***

## 4. List roots set on a vault

```
GET /v1/vaults/{chain}/{vault_address}/roots
```

Returns the roots that have been set on a vault on a given chain — both current and historical. Tenant-scoped: a vault outside your tenant (or a chain the vault isn't deployed on) returns `404 vault_not_found`. Cursor-paginated. Default sort: `active DESC` — active roots first, then inactive.

### Path parameters

| Name            | Type   | Notes                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `chain`         | string | Lowercase chain slug — see [Chain Support](https://docs.veda.tech/resources/chain-support.md) |
| `vault_address` | string | The BoringVault contract address                                                              |

### Query parameters

| Name     | Type   | Required | Notes                                                                                 |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `cursor` | string | No       | Opaque cursor from a previous response's `page.next_cursor` — omit on the first call. |

### Example request

```bash
curl https://api.veda.tech/v1/vaults/ethereum/0x6fDcB0654B4814c2eC1E7e9dbC4cEBf1a2038a84/roots \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "root_hash":   "0xb8b546c6ea05423782d5dcdf55f0153dbdbb7b9877c72b8d06ae689db9751a68",
      "strategist":  "0x3000D05DFb41171c1cE9fED802C6fC77cb8e0C69",
      "active":      true,
      "set_at":      null,
      "set_tx_hash": null,
      "leaf_count":  null,
      "links": { "tree": "/trees/0xb8b546c6ea05423782d5dcdf55f0153dbdbb7b9877c72b8d06ae689db9751a68" }
    }
  ],
  "page": {
    "next_cursor": null,
    "page_size":   20,
    "has_more":    false
  }
}
```

* One entry is returned per `(root_hash, strategist)` pair — a vault that authorizes multiple strategists under the same root appears multiple times, once per strategist.

### Errors

| Status | Code              | Cause                                                            |
| ------ | ----------------- | ---------------------------------------------------------------- |
| `401`  | `unauthenticated` | Missing, expired, or revoked API key                             |
| `404`  | `vault_not_found` | Vault does not exist on this chain, **or** is not in your tenant |
| `429`  | `rate_limited`    | API key rate limit exceeded                                      |

***

## 5. List daily data

```
GET /v1/vaults/{chain}/{vault_address}/dailyData
```

Returns the daily share-price, APY, TVL, and base-asset accounting series for a vault over a date range. Cursor-paginated; the requested range is echoed back on `meta` so the response is self-describing.

{% hint style="info" %}
This endpoint uses the camel-case path segment `dailyData` to match the upstream contract; the rest of the API uses snake\_case in paths.
{% endhint %}

### Path parameters

| Name            | Type   | Notes                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `chain`         | string | Lowercase chain slug — see [Chain Support](https://docs.veda.tech/resources/chain-support.md) |
| `vault_address` | string | The BoringVault contract address                                                              |

### Query parameters

| Name     | Type   | Required | Notes                                                                                                                        |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `from`   | string | No       | Start of the range, ISO-8601 UTC (e.g. `2026-05-01T00:00:00Z`). Omit to default to the earliest available day for the vault. |
| `to`     | string | No       | End of the range, ISO-8601 UTC (e.g. `2026-06-12T00:00:00Z`). Omit to default to the latest available day for the vault.     |
| `cursor` | string | No       | Opaque cursor from a previous response's `page.next_cursor` — omit on the first call.                                        |

Calling the endpoint without `from` / `to` returns the full series for the vault, paginated. The `meta` block on the response reflects the **effective** range applied by the server, so you can tell what window the data actually covers even when you omit one or both params.

### Example request

```bash
curl 'https://api.veda.tech/v1/vaults/ethereum/0x13Cc1b39cb259BA10cd174EAe42012e698ed7c51/dailyData?from=2026-05-01T00:00:00Z&to=2026-06-12T00:00:00Z' \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "vault_address": "0x13Cc1b39cb259BA10cd174EAe42012e698ed7c51",
      "chain":         "ethereum",
      "as_of":         "2026-06-12T00:00:00Z",
      "block_number":  22489231,
      "daily_apy":     0.015506100540390087,
      "price_usd":     "1.00",
      "share_price":   1.082341,
      "total_assets":  "4250000.000000",
      "tvl_usd":       "4250000.00"
    }
  ],
  "meta": {
    "from": "2026-05-01T00:00:00Z",
    "to":   "2026-06-12T00:00:00Z"
  },
  "page": {
    "next_cursor": null,
    "page_size":   90,
    "has_more":    false
  }
}
```

* One entry per day in the requested range, in chronological order.
* `share_price` and `daily_apy` are floats; `total_assets`, `tvl_usd`, and `price_usd` are returned as strings to preserve full precision for assets whose value can fall outside safe float ranges.
* `daily_apy` is fractional — `0.015506…` means `1.55%`, not `155%`.
* `meta.from` / `meta.to` report the **effective** range the server applied — either the values you supplied, or the defaults (earliest and latest available days) when omitted.

### Errors

| Status | Code                | Cause                                                        |
| ------ | ------------------- | ------------------------------------------------------------ |
| `401`  | `unauthenticated`   | Missing, expired, or revoked API key                         |
| `404`  | `vault_not_found`   | Vault does not exist on this chain, or is not in your tenant |
| `422`  | `validation_failed` | `from` / `to` malformed, or `to` ≤ `from`                    |
| `429`  | `rate_limited`      | API key rate limit exceeded                                  |

***

## 6. Get performance

```
GET /v1/vaults/{chain}/{vault_address}/performance
```

Returns the vault's yield performance — a top-level annualized APY plus a breakdown of where that yield comes from.

{% hint style="info" %}
All APY and fee values in the response are **expressed as decimals**. Multiply by `100` to get a percentage — `0.043` = `4.3%`.
{% endhint %}

For a longer walkthrough of each field, see the [Performance APY User Guide](https://help.veda.tech/article/veda-api-user-guide#performance-api).

### Path parameters

| Name            | Type   | Notes                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `chain`         | string | Lowercase chain slug — see [Chain Support](https://docs.veda.tech/resources/chain-support.md) |
| `vault_address` | string | The BoringVault contract address                                                              |

### Example request

```bash
curl https://api.veda.tech/v1/vaults/ethereum/0x13Cc1b39cb259BA10cd174EAe42012e698ed7c51/performance \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

### Example response

```json
{
  "data": {
    "vault_address":    "0x13cc1b39cb259ba10cd174eae42012e698ed7c51",
    "chain":            "ethereum",
    "as_of":            "2026-07-17T00:00:00Z",
    "window_days":      7,
    "apy":              0.008445101089285182,
    "fees":             0.0025,
    "performance_fees": 0.1,
    "global_apy_breakdown": {
      "fee":          0.003438344565476132,
      "maturity_apy": 0,
      "real_apy":     0.008445101089285182
    },
    "maturity_apy_breakdown": [],
    "real_apy_breakdown": [
      {
        "allocation": 0.9999999916128769,
        "apy":        0.012062023778707017,
        "apy_net":    0.010855821400836315,
        "chain":      "ethereum",
        "protocol":   "morpho"
      }
    ]
  }
}
```

### Top-level APY

The top-level `apy` field is the vault's annualized yield based on share-price changes over a **trailing 7-day window**. It's the source of truth for vault performance:

* **Share price is the foundation.** The vault's share price reflects total assets divided by total shares outstanding — as the vault earns yield, share price increases.
* **Daily-updated.** The share price on the API reflects the daily-updated share price.
* **7-day trailing average.** Rather than showing day-to-day volatility, the APY is smoothed over the past 7 days to give a more stable, representative number.
* **Net of fees.** The top-level APY is already net of fees.

### APY components

`global_apy_breakdown` decomposes the vault's return into three contributions:

* **`real_apy`** — variable-rate real yield
* **`maturity_apy`** — fixed-rate maturity products (e.g. dated lending)
* **`fee`** — total fees deducted, expressed as an APY drag

`real_apy_breakdown` lists per-protocol APY contributions with allocation weights. Each entry shows:

* **`allocation`** — a point-in-time snapshot of what share of vault assets is currently in that position. This is a **daily** snapshot.
* **`apy`** — the position's 7-day trailing APY, **gross** of position-level fees.
* **`apy_net`** — the same rate net of position-level fees. Only present when position-level fees apply.
* **`chain`**, **`protocol`** — where the position lives.

The time periods are intentionally different — allocation is today's snapshot, APY is a 7-day trailing average.

`maturity_apy_breakdown` lists fixed-rate maturity positions individually. Empty when the vault holds none.

### Fees

Three fee-related fields appear in the response:

* **`fees`** — platform fee, as an annual rate.
* **`performance_fees`** — performance fee, the rate applied to generated yield. **Nullable** — comes back as `null` for vaults with no performance fee configured.
* **`fee`** (inside `global_apy_breakdown`) — total fees deducted, expressed as an APY drag.

Fees are stored in **basis points** on-chain (1 bps = 0.01%) and converted to **decimals** in the API response.

### Other response fields

* `as_of` is the ISO-8601 UTC timestamp the summary is anchored to (start of the day it was computed for).
* `window_days` is fixed at `7 days`.
* `vault_address` may come back lowercased today rather than EIP-55 checksummed — compare case-insensitively.

### Errors

| Status | Code              | Cause                                                        |
| ------ | ----------------- | ------------------------------------------------------------ |
| `401`  | `unauthenticated` | Missing, expired, or revoked API key                         |
| `404`  | `vault_not_found` | Vault does not exist on this chain, or is not in your tenant |
| `429`  | `rate_limited`    | API key rate limit exceeded                                  |

***

## 7. Get withdrawal queue

Use this endpoint to read withdrawal requests for a vault. The response groups requests by status and includes cancellation or fulfillment events when available.

```
GET /v1/vaults/{chain}/{vault_address}/withdraw-queue
```

The endpoint requires a Bearer API key with access to the vault on the specified chain. See [Quick Start](https://docs.veda.tech/api/quick-start.md) to create a key. Examples below use `$VEDA_API_KEY`.

This endpoint reads queue data. To submit or cancel a withdrawal, use the contracts described in [Deposits & Withdrawals Overview](https://docs.veda.tech/integrations/deposits-and-withdrawals-overview.md#boringqueue-withdrawals).

### Parameters

#### Path parameters

| Name            | Type   | Notes                                                                                                                                                          |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chain`         | string | Lowercase chain slug. See [Chain Support](https://docs.veda.tech/resources/chain-support.md). The vault must have a configured withdrawal queue on this chain. |
| `vault_address` | string | BoringVault contract address, not the queue contract address.                                                                                                  |

#### Query parameters

| Name         | Type    | Required | Notes                                                                                                                                                |
| ------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`       | string  | No       | Filter requests by the depositor's wallet address. Use `0x` followed by 40 hexadecimal characters. Lowercase and checksummed addresses are accepted. |
| `from_block` | integer | No       | Include requests created at or after this block. Must be zero or greater.                                                                            |
| `to_block`   | integer | No       | Include requests created at or before this block. Must be zero or greater.                                                                           |

Both block bounds are inclusive. If you supply both, `from_block` must be less than or equal to `to_block`. You can supply either bound alone.

Block filters apply to the **request creation block** in every group. They do not filter cancellation or fulfillment blocks. For example, a request created at block `100` and fulfilled at block `200` can appear when `to_block=100`. A block range does not produce a historical snapshot of queue status.

The endpoint returns all four groups without pagination. It has no `cursor`, page-size, or status filter. It preserves the source order within each group; do not assume a chronological sort.

{% hint style="info" %}
Results use the queue's configured lookback window. A block filter narrows the available data; it does not extend that window. Do not use this endpoint as a complete archive of all withdrawals since vault deployment.
{% endhint %}

### Example requests

Read the queue for a vault:

```bash
curl 'https://api.veda.tech/v1/vaults/base/0x5401b8620E5FB570064CA9114fd1e135fd77D57c/withdraw-queue' \
  -H "Authorization: Bearer $VEDA_API_KEY"
```

Filter by wallet and request creation blocks:

```bash
curl --get 'https://api.veda.tech/v1/vaults/base/0x5401b8620E5FB570064CA9114fd1e135fd77D57c/withdraw-queue' \
  -H "Authorization: Bearer $VEDA_API_KEY" \
  --data-urlencode 'user=0x0F90793a54E809bf708bd0FbCC63d311E3bb1BE1' \
  --data-urlencode 'from_block=36000000' \
  --data-urlencode 'to_block=36100000'
```

Replace the vault, wallet, and block range with values for your integration. Your API key must have access to the example vault if you use its address.

### Response

The following abbreviated response shows open, cancelled, and fulfilled requests. An empty group is an empty array. The response has no `page` object.

```json
{
  "data": {
    "vault_address": "0x5401b8620E5FB570064CA9114fd1e135fd77D57c",
    "chain":         "base",
    "open_requests": [
      {
        "block_number":     53141206,
        "transaction_hash": "0x3de42d5709594424e16409217f17aff43cf9b8860836b2d996f97733097c0791",
        "user":             "0x1CcFc6C1C52758e0c02B5047CF90b298E3c8d5dd",
        "metadata": {
          "nonce":               12,
          "asset_out":           "0xecAc9C5F704e954931349Da37F60E39f515c11c1",
          "assets_amount":       "130076",
          "shares_amount":       "126733",
          "creation_time":       "2026-10-27T03:29:19Z",
          "seconds_to_maturity": 3600,
          "seconds_to_deadline": 1728000,
          "asset_out_amount":    "0.0013073941799672671",
          "asset_out_decimals":  8,
          "asset_out_symbol":    "LBTC"
        }
      }
    ],
    "cancelled_requests": [
      {
        "request": {
          "block_number":     52242866,
          "transaction_hash": "0x0e5ccdd2071e5c95519f95d7278b13396ee02cde2c74259d7130eaf53d4a0dfd",
          "user":             "0x0F90793a54E809bf708bd0FbCC63d311E3bb1BE1",
          "metadata": {
            "nonce":               1,
            "asset_out":           "0xecAc9C5F704e954931349Da37F60E39f515c11c1",
            "assets_amount":       "10253",
            "shares_amount":       "10001",
            "creation_time":       "2026-10-06T08:24:39Z",
            "seconds_to_maturity": 3600,
            "seconds_to_deadline": 1814400,
            "asset_out_decimals":  8,
            "asset_out_symbol":    "LBTC"
          }
        },
        "cancellation": {
          "block_number":     52244212,
          "timestamp":        "2026-10-06T09:09:31Z",
          "transaction_hash": "0xf7430aeb6d7bd219cafcf52ea559a52174412a015b41ad0f0716e79807afdc6c"
        }
      }
    ],
    "expired_requests": [],
    "fulfilled_requests": [
      {
        "request": {
          "block_number":     52244302,
          "transaction_hash": "0xd92893fc8a365bd6071e8b02bba42f727b6dc41b2f3d7d83fb3d594b602ea8c3",
          "user":             "0x0F90793a54E809bf708bd0FbCC63d311E3bb1BE1",
          "metadata": {
            "nonce":               2,
            "asset_out":           "0xecAc9C5F704e954931349Da37F60E39f515c11c1",
            "assets_amount":       "10253",
            "shares_amount":       "10001",
            "creation_time":       "2026-10-06T09:12:31Z",
            "seconds_to_maturity": 3600,
            "seconds_to_deadline": 1814400,
            "asset_out_decimals":  8,
            "asset_out_symbol":    "LBTC"
          }
        },
        "fulfillment": {
          "block_number":     52680417,
          "timestamp":        "2026-10-16T11:29:41Z",
          "transaction_hash": "0x0ed753c4a789b7432232acaaf8f6230206608eb8dbe194398c7dab46649b8b35"
        }
      }
    ]
  }
}
```

#### Request groups

| Field                | Contents                                                                                                                               |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `open_requests`      | Request objects for requests that have not expired, been cancelled, or been fulfilled. An open request may still be waiting to mature. |
| `cancelled_requests` | Objects with a `request` object and a `cancellation` event.                                                                            |
| `expired_requests`   | Request objects for requests past their deadline that have not been cancelled or fulfilled. Expiry alone does not return shares.       |
| `fulfilled_requests` | Objects with a `request` object and a `fulfillment` event.                                                                             |

For cancelled and fulfilled entries, `request` has the same fields as an entry in `open_requests`. The associated event has this shape:

```json
{
  "block_number": 36150000,
  "timestamp": "2026-10-07T09:13:20Z",
  "transaction_hash": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
```

For example, access a fulfilled request through `data.fulfilled_requests[0].request` and its event through `data.fulfilled_requests[0].fulfillment`.

#### Request fields

| Field                          | Type                      | Meaning                                                                              |
| ------------------------------ | ------------------------- | ------------------------------------------------------------------------------------ |
| `block_number`                 | integer                   | Block in which the request was created.                                              |
| `transaction_hash`             | string                    | Request transaction hash, with a `0x` prefix.                                        |
| `user`                         | string                    | Depositor wallet address.                                                            |
| `metadata.nonce`               | integer                   | Nonce recorded on the request.                                                       |
| `metadata.asset_out`           | string                    | Address of the asset requested by the depositor.                                     |
| `metadata.assets_amount`       | string                    | Raw asset amount recorded on the request, in the output token's smallest units.      |
| `metadata.shares_amount`       | string                    | Raw share amount recorded on the request, in the vault share token's smallest units. |
| `metadata.creation_time`       | string                    | Request creation time, in ISO-8601 UTC.                                              |
| `metadata.seconds_to_maturity` | integer                   | Delay from creation until the request matures, in seconds.                           |
| `metadata.seconds_to_deadline` | integer                   | Deadline window after maturity, in seconds.                                          |
| `metadata.asset_out_amount`    | string or null; optional  | Estimated output amount in display units. See the amount notes below.                |
| `metadata.asset_out_decimals`  | integer or null; optional | Output token decimals, when available.                                               |
| `metadata.asset_out_symbol`    | string or null; optional  | Output token symbol, when available.                                                 |

Addresses in the response are checksummed. Transaction hashes use lowercase hexadecimal characters. Request and event timestamps use ISO-8601 UTC.

#### Amounts and timing

Keep `assets_amount` and `shares_amount` as strings or parse them with an arbitrary-precision integer library. They can exceed JavaScript's safe integer range. Divide each raw amount by `10 ** token_decimals` only when you need a display value. Use the output token's decimals for assets and the vault share token's decimals for shares.

`asset_out_amount` is an estimate from the queue data source. It is already in display units. It is not proof of the amount paid at fulfillment. Cached requests can retain an earlier estimate after their status changes. Use the fulfillment transaction to verify the actual transfer.

The three optional output-token fields can be absent or explicitly `null`. Treat either case as unavailable data, not zero.

To calculate the maturity time, add `seconds_to_maturity` to `creation_time`. To calculate the deadline, add `seconds_to_deadline` to the maturity time. Maturity does not guarantee immediate fulfillment; a solver must fulfill the request.

### Errors

| Status | Code or response             | Cause                                                                                                          |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `401`  | `{"message":"Unauthorized"}` | Missing or malformed authorization header.                                                                     |
| `403`  | `{"message":"Forbidden"}`    | Invalid, expired, or revoked API key, or insufficient gateway permissions.                                     |
| `404`  | `vault_not_found`            | Vault or queue unavailable on this chain, unsupported chain, or vault outside your tenant.                     |
| `422`  | `validation_failed`          | Invalid wallet address or block bounds.                                                                        |
| `429`  | Rate-limit response          | API key rate limit exceeded.                                                                                   |
| `500`  | `internal_error`             | The service cannot complete the request because of an internal configuration or authorization-service failure. |
| `503`  | `service_unavailable`        | Queue data is temporarily unavailable or cannot be read in the required format. Retry with backoff.            |

Application errors use the [standard error envelope](https://docs.veda.tech/api/api-reference.md#errors). Authentication errors occur at the gateway and use the flat `message` response shown above.

A successful response with four empty arrays means no requests were returned for the available data and filters. An error response must not be treated as an empty queue.

### Migration from SevenSeas

Replace `GET /boringQueue/{network}/{vault}[/{user}]` with `GET /v1/vaults/{chain}/{vault_address}/withdraw-queue`. Supply a Bearer API key with access to the vault.

| Area                            | Legacy `/boringQueue`                      | `/withdraw-queue`                                                                                  |
| ------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Auth                            | None                                       | `Authorization: Bearer $VEDA_API_KEY`, vault must be in your tenant                                |
| User filter                     | `/{user}` path segment                     | `?user={user}` query parameter                                                                     |
| `to_block` without `from_block` | Requires `historical=true`                 | Applied                                                                                            |
| Wrapper                         | `{"Response": {...}}`                      | `{"data": {...}}`, adds `vault_address` and `chain`                                                |
| Field names                     | camelCase                                  | snake\_case (`amountOfAssets` → `assets_amount`, `secondsToDeadline` → `seconds_to_deadline`, ...) |
| Vault                           | `offerToken`                               | top-level `vault_address`                                                                          |
| Asset out                       | `wantToken`, `metadata.assetOut`           | `metadata.asset_out`                                                                               |
| Shares                          | `amount`, `metadata.amountOfShares`        | `metadata.shares_amount`                                                                           |
| Request time                    | `timestamp`, `metadata.creationTime`       | `metadata.creation_time`                                                                           |
| User                            | `user`, `metadata.user`                    | `user`                                                                                             |
| Request block                   | `blockNumber`                              | `block_number`                                                                                     |
| Estimate                        | `wantTokenAmount`                          | `metadata.asset_out_amount`                                                                        |
| Token info                      | `wantTokenDecimals`, `wantTokenSymbol`     | `metadata.asset_out_decimals`, `metadata.asset_out_symbol`                                         |
| Cancelled / fulfilled entries   | `Request` + `Cancellation` / `Fulfillment` | `request` + `cancellation` / `fulfillment`                                                         |
| Timestamps                      | Unix seconds                               | ISO-8601 UTC                                                                                       |
| Raw asset and share amounts     | Numbers or strings                         | Strings                                                                                            |
| Transaction hashes              | No `0x` prefix                             | `0x` prefix                                                                                        |

Where the legacy column lists two fields, the legacy response carried the same value twice; the new response has it once.

***

**Go on to next:** [Policy Manager & Merkle Trees](https://docs.veda.tech/api/policy-manager-and-merkle-trees.md) — how a vault's allowlist is encoded as a merkle tree and committed onchain.
