> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Vault

> Full vault record plus live chain state and an optional holder position

Returns the complete vault record with two enrichment blocks: `onChain`, the vault's live state read from the chain in one aggregate, and `holder`, the position of the wallet named in `address`. Without an `address`, `holder` is `null`.

## Path Parameters

<ParamField path="vaultId" type="string" required>Vault ID from [List Vaults](/endpoints/vaults/list-vaults).</ParamField>

## Query Parameters

<ParamField query="address" type="string">
  Wallet to read a position for. When present, `holder` carries that wallet's shares and their current value.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="onChain" type="object">
      <Expandable>
        <ResponseField name="readFailed" type="boolean">True when the chain could not be read. Every other field in this block is then absent. Keep your last verified values instead of rendering zeros.</ResponseField>
        <ResponseField name="totalAssets" type="string">Everything the vault is worth: idle funds plus its value across allocated markets. Formatted at the vault's asset decimals.</ResponseField>
        <ResponseField name="totalShares" type="string">Shares in issue.</ResponseField>
        <ResponseField name="sharePrice" type="string">Value of one share in the settlement asset, as an 18-decimal string. `"1.0"` is par. It rises as the funded markets pay interest.</ResponseField>
        <ResponseField name="idleAssets" type="string">Funds not allocated to any market. This is what a redemption can pay immediately.</ResponseField>
        <ResponseField name="allocatedAssets" type="string">Total assets minus idle assets: funds working in the operator's lending markets.</ResponseField>
        <ResponseField name="depositsPaused" type="boolean">True while the operator has paused deposits. Redemptions cannot be paused.</ResponseField>
        <ResponseField name="performanceFeeBps" type="integer">Live fee. The contract only accepts decreases.</ResponseField>
        <ResponseField name="allocations" type="array">Per-market legs: `marketAddress`, `marketName`, `marketSymbol`, `lpValue`, `lpValueRaw`, `lpShares`, `deposited`, `marketAvailable`, and a per-leg `readFailed` when one market could not be read. Each healthy leg also carries `utilizationBps`, `borrowRateBps`, and `supplyRateBps`, which are the rates shown on that market's own page.</ResponseField>

        <ResponseField name="interest" type="object">
          <Expandable>
            <ResponseField name="readFailed" type="boolean">True when any allocation leg could not be read. The other fields are then absent, because a sum over the legs that did answer would understate the total.</ResponseField>
            <ResponseField name="grossAnnual" type="string">Interest the current allocations would earn over a year at today's rates, before the performance fee. In the settlement asset.</ResponseField>
            <ResponseField name="netAnnual" type="string">The same figure after the operator's performance fee.</ResponseField>
            <ResponseField name="blendedGrossApyBps" type="integer">Gross annual interest over total assets, in basis points. Idle funds earn nothing, so this sits below the rate of any single funded market. `null` when the vault holds nothing.</ResponseField>
            <ResponseField name="blendedNetApyBps" type="integer">The same blended rate after the fee. This is the rate an investor earns.</ResponseField>
            <ResponseField name="performanceFeeBps" type="integer">The fee applied to get from gross to net.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="holder" type="object">
      <Expandable>
        <ResponseField name="shares" type="string">The wallet's share balance.</ResponseField>
        <ResponseField name="value" type="string">Those shares at the current share price, in the settlement asset.</ResponseField>
        <ResponseField name="readFailed" type="boolean">True when the position could not be read. `shares` and `value` are then `null`, not zero.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  `readFailed: true` means the RPC could not answer, not that the vault is empty. A vault whose read failed still holds every deposit it held a minute ago. Show your last verified figures with a warning, retry, and never render zeros in their place.
</Warning>

<Note>
  `sharePrice` is an 18-decimal string regardless of the asset's own decimals. Every other amount in the block is formatted at `assetDecimals`.
</Note>

<Note>
  The `interest` block describes what the current allocations would earn at today's rates. Rates move with each market's utilization, so treat it as the present run rate rather than a forecast. It costs no extra call: the rates come from the same market read that produces the allocation legs.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/lending-external-securities/api/vaults/{vaultId}?address=0x5ad87a0621175206b72d10e4b8577b192e7f40ab" \
    -H "X-API-Key: trusset_your_key_here"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/lending-external-securities/api/vaults/${vaultId}?address=${wallet}`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data } = await res.json();
  if (data.onChain?.readFailed) {
    // keep last verified values and retry
  } else {
    console.log(`share price ${data.onChain.sharePrice}, ${data.onChain.idleAssets} ${data.assetSymbol} idle`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "cmssh8t2u0003cghxkx1w1fwd",
      "own": false,
      "vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
      "assetSymbol": "USDC",
      "assetDecimals": 6,
      "name": "Trusset Prime Demo Vault",
      "symbol": "TPV",
      "performanceFeeBps": 500,
      "active": true,
      "riskDisclosure": "Deposits fund overcollateralized security-token lending markets.",
      "riskDisclosureUrl": "https://bank.example/vault-risk",
      "operatedBy": { "instanceName": "Trusset Client Demo", "issuerName": "Trusset UG", "isBank": true },
      "onChain": {
        "isOnChain": true,
        "readFailed": false,
        "owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
        "asset": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
        "identityRegistry": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
        "totalAssets": "125000.0",
        "totalShares": "123456.789012",
        "sharePrice": "1.0125",
        "idleAssets": "25000.0",
        "allocatedAssets": "100000.0",
        "depositsPaused": false,
        "performanceFeeBps": 500,
        "allocations": [
          {
            "marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
            "marketName": "Trusset Security Token",
            "marketSymbol": "TRST",
            "lpShares": "100000000000",
            "lpValue": "101250.0",
            "lpValueRaw": "101250000000",
            "deposited": "100000.0",
            "marketAvailable": "62500.0",
            "utilizationBps": 5503,
            "borrowRateBps": 750,
            "supplyRateBps": 309
          }
        ],
        "interest": {
          "readFailed": false,
          "grossAnnual": "3128.625",
          "netAnnual": "2972.19375",
          "blendedGrossApyBps": 250,
          "blendedNetApyBps": 237,
          "performanceFeeBps": 500
        }
      },
      "holder": {
        "holderAddress": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
        "shares": "1000.0",
        "value": "1012.5",
        "readFailed": false
      }
    }
  }
  ```

  ```json Degraded read theme={null}
  {
    "success": true,
    "data": {
      "id": "cmssh8t2u0003cghxkx1w1fwd",
      "name": "Trusset Prime Demo Vault",
      "onChain": { "readFailed": true, "isOnChain": null },
      "holder": null
    }
  }
  ```

  ```json Error - Not Found theme={null}
  {
    "success": false,
    "error": {
      "code": "VAULT_NOT_FOUND",
      "message": "Vault not found"
    }
  }
  ```
</ResponseExample>