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)

   • Fireblocks (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.

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.

• 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 or Blockpass), 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.