# Investor Custody

This page describes how to configure and manage custodial investor wallets using a supported custody provider (Tangany or Fireblocks) in the Offering Manager.

## Configure a Custody Provider

1. In the Admin UI, go to **Settings** > **Integrations**.
2. Locate the **Investor Custody** card and select **Configure**.
3. Choose a provider:
   * **Tangany** ([tangany.com](https://tangany.com))
   * **Fireblocks** ([fireblocks.com](https://www.fireblocks.com))
4. Choose a **Default Wallet Policy** for your offerings:
   * `byo_only` (BYO only)
   * `investor_choice` (Investor choice)
   * `custodial_only` (Custodial only)
5. Enter the required credentials and settings for the selected provider:

   #### Tangany

   * **Tangany Subscription**
   * **Client ID**
   * **Client Secret**
   * **API Base URL** (optional)
   * **Auth Base URL** (optional)
   * **Wallet Label Template** (optional) – a string template for wallet labels. You can include:
     * `{tenantId}` – first 8 characters of your tenant ID
     * `{userId}` – first 8 characters of the investor’s user ID
     * `{chain}` – chain type (e.g. `evm`)

   #### Fireblocks

   * **Fireblocks API Key**
   * **Fireblocks Private Key (PEM)**
   * **API Base URL** (optional)
   * **Vault Name Template** (optional) – a string template for vault account names. You can include:
     * `{tenantId}` – first 8 characters of your tenant ID
     * `{userId}` – first 8 characters of the investor’s user ID
   * **Chain Asset Overrides** (optional) – map each chain to the Fireblocks asset ID. Click **Load supported assets** to fetch available asset IDs from Fireblocks, then select or enter the correct ID per chain (for example, `evm: ETH`, `polygon: MATIC_POLYGON`, `solana: SOL`).
6. Click **Test Connection** to verify connectivity and list vaults.<br>
7. After a successful test, click **Save** to apply the settings.

## Set the Investor Wallet Policy per Offering

Each offering can override the default wallet policy:

1. Go to **Offerings** and select an existing offering or create a new one.
2. Open the **Invest Page** tab in the **Invest Page Builder**.
3. In the **Wallet Policy** section, choose one of:
   * **BYO only** (`byo_only`)
   * **Investor choice** (`investor_choice`)
   * **Custodial only** (`custodial_only`)
4. Click **Save**.

## Investor Checkout Experience

The wallet options displayed during checkout depend on the policy:

* BYO only (`byo_only`):\
  Investors must connect an external wallet (e.g. MetaMask) to complete a purchase.
* Investor choice (`investor_choice`):\
  Investors can either connect their own wallet or opt for a custodial wallet without an external connection.
* Custodial only (`custodial_only`):\
  A custodial wallet is created automatically after KYC approval. No external wallet connection is required.

## Supported Chains

* Tangany supports EVM chains only. For details, visit [Tangany](https://tangany.com).
* Fireblocks supports a wide range of chains (EVM, Solana, and others) and all assets available in your Fireblocks vault. Use the **Chain Asset Overrides** field in the integration settings to select which asset ID to use on each chain.

## Custodial Wallet Provisioning Lifecycle

1. After an investor completes KYC (via [Sumsub](https://sumsub.com) or [Blockpass](https://www.blockpass.org)), a custodial account is created automatically.
2. When the investor places their first order on a new chain, a custodial wallet for that chain is provisioned in the background.
3. Provisioning runs asynchronously; the status updates to **active** or **failed** once complete.
4. You can also manually provision or retry provisioning in the Admin UI.

## Manual Provisioning and Retry

* To provision a custody account before checkout:
  1. Go to **Admin** > **Investors** and select an investor.
  2. In the **Custody** section, click **Provision Now**.

     > Note: The investor must have an **approved** KYC status before provisioning can succeed. This action is idempotent — if an account already exists, it will return the existing account.
* To retry failed provisioning jobs:
  1. In the same **Custody** section, locate the failed account or wallet.
  2. Click **Retry** to re-queue all failed account and wallet provisioning jobs for that investor.

## Monitor Custody Status

* **Investors** list:\
  Navigate to **Admin** > **Investors**, select an investor, and open the **Custody** section to view:
  * Account status (`pending`, `active`, `failed`)
  * Wallet list with chain, address, status, and error details
  * Retry controls for failed items
* **Orders** list:\
  Under **Admin** > **Offerings** > select an offering > **Orders**, open an order to see:
  * Custodial wallet address (if used)
  * Provisioning status and retry options for the associated wallets

## API Reference

For details on custody endpoints, see the interactive OpenAPI reference at <https://om.bitbond.com/api/docs>.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbond.com/asset-tokenization-suite/offering-manager/investor-custody.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.