> ## 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 Group

> One multi-currency vault group with every pocket, live totals per currency and an optional holder position

Returns one vault group with its pockets read from the chain. A vault group is one vault product with two to four currency pockets. Each pocket is a vault of its own that holds one settlement token (stablecoin), for example one in USDC and one in EURC. All pockets examine their depositors against the same register for the life of the group, are run by one operator, and are published together under the group's risk disclosure.

A deposit goes into one pocket and stays in its currency. Nothing converts between pockets, so the group's value is reported per currency in `tvlByCurrency`. Only on a group that mixes exactly EUR and USD is `approximateTotal` filled in, at the ECB euro reference rate of its date, labelled as an approximation.

You see your own groups, and the groups other operators published on the same network and in the same environment. On another operator's group only its published pockets with a deployed address are listed. Creating a group, adding a currency, publishing and the operator's batched pocket actions are done in the Issuer Portal.

## Path Parameters

<ParamField path="groupId" type="string" required>
  Vault group ID, as `groups[].id` on [List Vaults](/endpoints/vaults/list-vaults) or `groupId` on a pocket's vault row.
</ParamField>

## Query Parameters

<ParamField query="holderAddress" type="string">
  Wallet to read a position for in every pocket. `address` is accepted too. Any value that is not a `0x` address is ignored, and each pocket's `holder` is then `null`.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="id" type="string">Vault group ID.</ResponseField>
    <ResponseField name="instanceId" type="string">The operating instance.</ResponseField>
    <ResponseField name="own" type="boolean">`true` when your instance operates the group.</ResponseField>
    <ResponseField name="onChainGroupId" type="integer">The group's ID on the vault factory.</ResponseField>
    <ResponseField name="factoryAddress" type="string">The vault factory that holds the group.</ResponseField>
    <ResponseField name="name" type="string">Group name.</ResponseField>
    <ResponseField name="symbolStem" type="string">The share symbol stem the pockets' symbols derive from, or `null`.</ResponseField>
    <ResponseField name="operatorWallet" type="string">The wallet that created the group.</ResponseField>
    <ResponseField name="identityRegistryAddress" type="string">The depositor register every pocket examines its depositors against.</ResponseField>
    <ResponseField name="depositorGate" type="object">`kind`, `register` and a display `statement`, as on a vault row of [List Vaults](/endpoints/vaults/list-vaults).</ResponseField>
    <ResponseField name="depositorProfile" type="object">Your group only. The verification profile whose eligibility register the depositor register is, or `null`.</ResponseField>
    <ResponseField name="depositorAccessList" type="object">Your group only. The whitelist the depositor register is, as `{ id, name, purpose, address, own }`, or `null`.</ResponseField>
    <ResponseField name="depositorRegisterRetired" type="boolean">Present, and `true`, only when the group's depositor register is the previous Trusset ID Register, `0xE9114c40934f6fB6BB317935156b731f7A86D006`. That register takes no new identities, so every pocket refuses a depositor verified since 10 October 2026. See [The Previous Trusset ID Register](/endpoints/lending/set-identity-gates#the-previous-trusset-id-register).</ResponseField>
    <ResponseField name="currentRegistry" type="string">Present with `depositorRegisterRetired`. The current Trusset ID Register, lowercased.</ResponseField>
    <ResponseField name="depositorRegisterNote" type="string">Present with `depositorRegisterRetired`. The same note as on [List Vaults](/endpoints/vaults/list-vaults).</ResponseField>
    <ResponseField name="performanceFeeBps" type="integer">The group's performance fee in basis points as recorded. Each pocket carries its own, reconciled with the chain.</ResponseField>
    <ResponseField name="active" type="boolean">Whether the group is published.</ResponseField>
    <ResponseField name="archived" type="boolean">Always `false` here.</ResponseField>
    <ResponseField name="riskDisclosure" type="string">The operator's risk statement, shown on every pocket. Show it before any deposit control.</ResponseField>
    <ResponseField name="riskDisclosureUrl" type="string">Link to the full risk disclosure, `https`, or `null`.</ResponseField>
    <ResponseField name="network" type="string">The chain the group lives on.</ResponseField>
    <ResponseField name="operatedBy" type="object">`instanceName`, `issuerName`, `isBank`, `image` and `profileImage`. Display the operator next to the group name.</ResponseField>
    <ResponseField name="pockets" type="array">Each pocket as a vault row of [List Vaults](/endpoints/vaults/list-vaults), with `onChain` as on [Get Vault](/endpoints/vaults/get-vault) and `holder` for `holderAddress`. A pocket row leaves out `depositorProfile`, `depositorAccessList` and the retired-register fields, which the group carries once. `onChain` and `holder` are `null` on a pocket with no deployed address. Deposit into a pocket with [Deposit to Vault Group](/endpoints/vaults/deposit-to-vault-group) or with [Deposit](/endpoints/vaults/deposit) on its vault ID.</ResponseField>
    <ResponseField name="operatorDiverged" type="boolean">`true` when the pockets are owned by different wallets on chain, `false` when one wallet owns them all, `null` when an owner could not be read.</ResponseField>
    <ResponseField name="currentOperator" type="string">The one wallet that owns every pocket, or `null`.</ResponseField>
    <ResponseField name="tvl" type="object">Total assets per currency, keyed by currency code, for example `{ "USD": "1250000.0", "EUR": "480000.0" }`. A pocket whose asset has no known currency is keyed by its symbol.</ResponseField>
    <ResponseField name="tvlByCurrency" type="array">The same per currency: `currency`, `amount` (`null` when a pocket could not be read), `pockets`, `symbols` and `readFailed`.</ResponseField>
    <ResponseField name="approximateTotal" type="object">Only when the pockets hold exactly EUR and USD and every figure was read: `currency` (`USD`), `amount`, `eurAmount`, `eurUsd`, `referenceDate`, `source` (`ECB`), `approximate: true` and a `label`. `null` otherwise.</ResponseField>
    <ResponseField name="chain" type="object">The group as the vault factory holds it: `operator`, `identityRegistry`, `performanceFeeBps` and `vaults`, or `{ readFailed: true }`.</ResponseField>
    <ResponseField name="unregisteredPockets" type="string[]">Your group only. Pockets the factory holds that your instance has not registered yet. Empty otherwise.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601.</ResponseField>
  </Expandable>
</ResponseField>

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

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/lending-external-securities-v2/api/vaults/groups/${groupId}?holderAddress=${wallet}`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data: group } = await res.json();
  for (const pocket of group.pockets) {
    console.log(pocket.assetSymbol, pocket.onChain?.totalAssets, pocket.holder?.shares);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "cmv3a1b2c0007l80d4e5f6g7h",
      "instanceId": "inst_abc123",
      "own": false,
      "onChainGroupId": 3,
      "factoryAddress": "0x4c8e2a7f1b9d03e56a2c8f4b1d7e9a03c5b2e8f1",
      "name": "Prime Liquidity",
      "symbolStem": "PRL",
      "operatorWallet": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
      "identityRegistryAddress": "0xef244c4bd4d71bd9a30edf6edef7ccc72642291a",
      "depositorGate": {
        "kind": "REGISTER",
        "register": "0xef244c4bd4d71bd9a30edf6edef7ccc72642291a",
        "statement": "Deposits and share transfers are examined against this register."
      },
      "performanceFeeBps": 500,
      "active": true,
      "archived": false,
      "riskDisclosure": "Deposits fund overcollateralized lending markets. Each pocket holds one currency and redemptions can fill partially under high utilization.",
      "riskDisclosureUrl": "https://bank.example/vault-risk",
      "network": "ETHEREUM",
      "operatedBy": {
        "instanceName": "Trusset Client Demo",
        "issuerName": "Trusset UG",
        "image": null,
        "profileImage": null,
        "isBank": true
      },
      "pockets": [
        {
          "id": "cmv3a1b2c0008l80d9k2m4n6p",
          "vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
          "assetAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
          "assetSymbol": "USDC",
          "assetDecimals": 6,
          "name": "Prime Liquidity USDC",
          "symbol": "PRLUSDC",
          "groupId": "cmv3a1b2c0007l80d4e5f6g7h",
          "group": { "id": "cmv3a1b2c0007l80d4e5f6g7h", "name": "Prime Liquidity", "onChainGroupId": 3 },
          "settlementCurrency": "USD",
          "onChain": { "isOnChain": true, "readFailed": false, "totalAssets": "1250000.0", "sharePrice": "1.0209" },
          "holder": { "shares": "979.528" }
        },
        {
          "id": "cmv3a1b2c0009l80d1q3r5s7t",
          "vaultAddress": "0x7a1c3e5f9b2d40e68c1a3f5b7d9e02c46a8f1b3d",
          "assetAddress": "0x08210f9170f89ab7658f0b5e3ff39b0e03c594d4",
          "assetSymbol": "EURC",
          "assetDecimals": 6,
          "name": "Prime Liquidity EURC",
          "symbol": "PRLEURC",
          "groupId": "cmv3a1b2c0007l80d4e5f6g7h",
          "group": { "id": "cmv3a1b2c0007l80d4e5f6g7h", "name": "Prime Liquidity", "onChainGroupId": 3 },
          "settlementCurrency": "EUR",
          "onChain": { "isOnChain": true, "readFailed": false, "totalAssets": "480000.0", "sharePrice": "1.0104" },
          "holder": null
        }
      ],
      "operatorDiverged": false,
      "currentOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
      "tvl": { "USD": "1250000.0", "EUR": "480000.0" },
      "tvlByCurrency": [
        { "currency": "USD", "amount": "1250000.0", "pockets": 1, "symbols": ["USDC"], "readFailed": false },
        { "currency": "EUR", "amount": "480000.0", "pockets": 1, "symbols": ["EURC"], "readFailed": false }
      ],
      "approximateTotal": {
        "currency": "USD",
        "amount": "1771232.0",
        "eurAmount": "1631118.887558707063265494",
        "eurUsd": 1.0859,
        "referenceDate": "2026-10-08",
        "source": "ECB",
        "approximate": true,
        "label": "Approximate total at the ECB euro reference rate of 2026-10-08. The pockets hold different currencies and nothing converts between them."
      },
      "chain": {
        "readFailed": false,
        "operator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
        "identityRegistry": "0xef244c4bd4d71bd9a30edf6edef7ccc72642291a",
        "performanceFeeBps": 500,
        "vaults": [
          "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
          "0x7a1c3e5f9b2d40e68c1a3f5b7d9e02c46a8f1b3d"
        ]
      },
      "unregisteredPockets": [],
      "createdAt": "2026-10-08T16:20:00.000Z",
      "updatedAt": "2026-10-09T07:45:00.000Z"
    }
  }
  ```
</ResponseExample>

The example shortens each pocket's vault row and its `onChain` and `holder` blocks.

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `VAULT_GROUP_NOT_FOUND` | `404` | No such group, it is archived, or it belongs to another operator and is unpublished or on another network or environment |
| `VAULT_GROUP_READ_FAILED` | `500` | Unexpected failure. Retry, or contact support with the request ID |
| `CHAIN_UNAVAILABLE` | `503` | The chain could not be read. Retry shortly |
| `SERVICE_UNAVAILABLE` | `503` | The vault records could not be reached. Retry shortly |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.