Custody Wallet Integration

This guide shows how to route on-chain deposits through your institutional custody provider using action delegates. This is the Tier 2 integration pattern - the most common setup for institutional platforms.

Prerequisites

@keystoneos/react and @keystoneos/node installed
KeystoneProvider configured with settlements:write scope
A backend that can submit transactions via your custody provider (Fireblocks, BitGo, etc.)

Why action delegates exist

Institutional platforms do not let end-users sign transactions in the browser. Assets are held in custody wallets managed by Fireblocks, BitGo, or similar infrastructure. When a settlement requires a deposit to escrow, the transaction must route through the custody provider’s API. Action delegates bridge this gap. Instead of the widget interacting with the blockchain directly, it calls your backend, which submits the transaction through your signing infrastructure.

The deposit flow

Frontend setup

Configuring the provider with action delegates

Pass onDepositRequired (and optionally onApprovalRequired) to the KeystoneProvider. These callbacks fire when the user triggers a deposit from the UI.

// app.tsx
import { useState, useEffect } from 'react';
import { KeystoneProvider } from '@keystoneos/react';

function App() {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    fetch('/api/keystone/session', { method: 'POST' })
      .then(r => r.json())
      .then(d => setToken(d.token));
  }, []);

  if (!token) return <div>Loading...</div>;

  return (
    <KeystoneProvider
      sessionToken={token}
      environment="production"
      onTokenExpired={async () => {
        const res = await fetch('/api/keystone/session', { method: 'POST' });
        return (await res.json()).token;
      }}
      actionDelegates={{
        onDepositRequired: async (leg, depositInfo) => {
          const response = await fetch('/api/deposit', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              calldata: depositInfo.calldata,
              escrowAddress: depositInfo.escrowAddress,
              chainId: depositInfo.chainId,
              tokenAddress: depositInfo.tokenAddress,
              amount: depositInfo.depositAmount,
            }),
          });

          if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message ?? 'Deposit submission failed');
          }

          const result = await response.json();
          return { txHash: result.txHash };
        },
        onApprovalRequired: async (leg, approvalInfo) => {
          const response = await fetch('/api/approve', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              calldata: approvalInfo.approvalCalldata,
              tokenAddress: approvalInfo.tokenAddress,
              spender: approvalInfo.escrowAddress,
              chainId: leg.chain_id,
            }),
          });

          if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message ?? 'Approval submission failed');
          }

          const result = await response.json();
          return { txHash: result.txHash };
        },
      }}
    >
      <YourApp />
    </KeystoneProvider>
  );
}

Building the deposit button component

The useDeposit hook manages the multi-step deposit flow. It returns the current status, deposit info for preview, and the deposit() function to trigger the flow.

// deposit-button.tsx
import { useDeposit } from '@keystoneos/react';

interface DepositButtonProps {
  settlementId: string;
  legIndex: number;
  instrumentId: string;
}

const STATUS_MESSAGES: Record<string, string> = {
  idle: '',
  fetching_info: 'Fetching deposit details...',
  checking_balance: 'Checking token balance...',
  approving: 'Submitting token approval...',
  approval_confirmed: 'Approval confirmed. Submitting deposit...',
  depositing: 'Submitting deposit transaction...',
  deposit_confirmed: 'Deposit confirmed on-chain.',
  error: 'Deposit failed.',
};

export function DepositButton({ settlementId, legIndex, instrumentId }: DepositButtonProps) {
  const { status, depositInfo, txHash, error, deposit } = useDeposit(settlementId, legIndex);

  const isProcessing = ['fetching_info', 'checking_balance', 'approving', 'approval_confirmed', 'depositing'].includes(status);

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
      {/* Deposit info preview */}
      {depositInfo && status === 'idle' && (
        <div style={{ padding: '12px', backgroundColor: '#f9fafb', borderRadius: '6px', fontSize: '13px' }}>
          <p>Escrow: <code>{depositInfo.escrowAddress}</code></p>
          <p>Amount: {depositInfo.depositAmount} {instrumentId}</p>
          <p>Chain: {depositInfo.chainId}</p>
        </div>
      )}

      {/* Action button */}
      {status === 'idle' && (
        <button
          onClick={deposit}
          style={{
            padding: '10px 20px',
            backgroundColor: '#2DD4A8',
            color: '#fff',
            border: 'none',
            borderRadius: '6px',
            fontWeight: 600,
            cursor: 'pointer',
          }}
        >
          Deposit {instrumentId}
        </button>
      )}

      {/* Processing status */}
      {isProcessing && (
        <div style={{ display: 'flex', alignItems: 'center', gap: '8px', color: '#1e40af' }}>
          <div style={{
            width: '16px', height: '16px', border: '2px solid #1e40af',
            borderTopColor: 'transparent', borderRadius: '50%',
            animation: 'spin 1s linear infinite',
          }} />
          <span style={{ fontSize: '14px' }}>{STATUS_MESSAGES[status]}</span>
        </div>
      )}

      {/* Success */}
      {status === 'deposit_confirmed' && (
        <div style={{ padding: '12px', backgroundColor: '#dcfce7', borderRadius: '6px', color: '#166534', fontSize: '14px' }}>
          <p style={{ fontWeight: 600 }}>{STATUS_MESSAGES[status]}</p>
          {txHash && (
            <p style={{ marginTop: '4px', fontFamily: 'monospace', fontSize: '12px' }}>
              TX: {txHash}
            </p>
          )}
        </div>
      )}

      {/* Error */}
      {status === 'error' && (
        <div style={{ padding: '12px', backgroundColor: '#fee2e2', borderRadius: '6px', color: '#991b1b', fontSize: '14px' }}>
          <p style={{ fontWeight: 600 }}>Deposit failed</p>
          <p style={{ marginTop: '4px' }}>{error}</p>
          <button
            onClick={deposit}
            style={{
              marginTop: '8px', padding: '6px 12px', backgroundColor: '#991b1b',
              color: '#fff', border: 'none', borderRadius: '4px', cursor: 'pointer', fontSize: '13px',
            }}
          >
            Retry
          </button>
        </div>
      )}
    </div>
  );
}

Backend implementation

Your backend receives the pre-encoded calldata from the frontend and submits it to your custody provider. The calldata is already ABI-encoded by the KeyStone API - your backend just needs to forward it.

Fireblocks

// routes/deposit.ts
import { FireblocksSDK, TransactionArguments, PeerType } from 'fireblocks-sdk';

const fireblocks = new FireblocksSDK(
  process.env.FIREBLOCKS_API_SECRET!,
  process.env.FIREBLOCKS_API_KEY!,
  process.env.FIREBLOCKS_API_URL,
);

// Map chain IDs to Fireblocks asset IDs
const CHAIN_TO_ASSET: Record<number, string> = {
  1: 'ETH',
  137: 'MATIC_POLYGON',
  43114: 'AVAX',
  11155111: 'ETH_TEST5',
};

app.post('/api/deposit', async (req, res) => {
  const { calldata, escrowAddress, chainId, tokenAddress, amount } = req.body;

  try {
    const txArgs: TransactionArguments = {
      assetId: CHAIN_TO_ASSET[chainId],
      source: {
        type: PeerType.VAULT_ACCOUNT,
        id: process.env.FIREBLOCKS_VAULT_ID!,
      },
      destination: {
        type: PeerType.ONE_TIME_ADDRESS,
        oneTimeAddress: { address: escrowAddress },
      },
      amount: '0', // Value is zero - the deposit amount is in the calldata
      extraParameters: {
        contractCallData: calldata,
      },
      note: `KeyStone escrow deposit: ${amount} to ${escrowAddress}`,
    };

    const tx = await fireblocks.createTransaction(txArgs);

    // Fireblocks returns immediately with a pending tx ID.
    // The actual txHash is available once mined. Poll or use webhook.
    // For simplicity, wait for the tx to complete:
    const completedTx = await waitForFireblocksTx(fireblocks, tx.id);

    res.json({ txHash: completedTx.txHash });
  } catch (err) {
    console.error('Fireblocks deposit failed:', err);
    res.status(500).json({ message: 'Failed to submit deposit transaction' });
  }
});

async function waitForFireblocksTx(fb: FireblocksSDK, txId: string, maxAttempts = 60): Promise<{ txHash: string }> {
  for (let i = 0; i < maxAttempts; i++) {
    const tx = await fb.getTransactionById(txId);
    if (tx.status === 'COMPLETED') {
      return { txHash: tx.txHash };
    }
    if (['FAILED', 'REJECTED', 'CANCELLED', 'BLOCKED'].includes(tx.status)) {
      throw new Error(`Fireblocks transaction ${tx.status}: ${tx.subStatus}`);
    }
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  throw new Error('Fireblocks transaction timed out');
}

BitGo

// routes/deposit-bitgo.ts
import { BitGoAPI } from '@bitgo/sdk-api';

const bitgo = new BitGoAPI({
  accessToken: process.env.BITGO_ACCESS_TOKEN!,
  env: 'prod',
});

const CHAIN_TO_COIN: Record<number, string> = {
  1: 'eth',
  137: 'polygon',
  43114: 'avaxc',
  11155111: 'gteth',
};

app.post('/api/deposit', async (req, res) => {
  const { calldata, escrowAddress, chainId } = req.body;

  try {
    const coin = CHAIN_TO_COIN[chainId];
    const wallet = await bitgo.coin(coin).wallets().get({ id: process.env.BITGO_WALLET_ID! });

    const tx = await wallet.sendTransaction({
      recipients: [{
        address: escrowAddress,
        amount: '0',
        data: calldata,
      }],
      walletPassphrase: process.env.BITGO_WALLET_PASSPHRASE!,
    });

    res.json({ txHash: tx.txid });
  } catch (err) {
    console.error('BitGo deposit failed:', err);
    res.status(500).json({ message: 'Failed to submit deposit transaction' });
  }
});

Generic signing infrastructure

If you use a different custody provider or your own HSM, the pattern is the same - forward the pre-encoded calldata:

app.post('/api/deposit', async (req, res) => {
  const { calldata, escrowAddress, chainId } = req.body;

  const txHash = await yourSigner.sendTransaction({
    to: escrowAddress,
    data: calldata,
    value: '0x0',
    chainId,
  });

  res.json({ txHash });
});

Deposit status states

The useDeposit hook progresses through these states:

idle -> fetching_info -> approving -> approval_confirmed -> depositing -> deposit_confirmed
                \                          \                      \
                 -> error                   -> error                -> error

Status	What is happening	User sees
`idle`	Nothing in progress	Deposit button
`fetching_info`	Calling KeyStone API for calldata	Loading spinner
`approving`	ERC-20 `approve()` submitted to custody	”Submitting approval…”
`approval_confirmed`	Approval mined, proceeding to deposit	Brief transition
`depositing`	`depositLeg()` submitted to custody	”Submitting deposit…”
`deposit_confirmed`	Deposit mined and confirmed by escrow	Success with txHash
`error`	Any step failed	Error message + retry button

Error handling

Common failure scenarios

Failure	Cause	What happens
Custody API rejects	Insufficient balance, policy violation, rate limit	`onDepositRequired` throws, `useDeposit` sets `status: "error"`
Gas estimation fails	Contract revert (wrong calldata, already deposited)	Custody provider returns error before signing
Transaction reverts	On-chain revert (deadline passed, wrong token)	txHash exists but transaction failed
Network timeout	RPC or custody API unreachable	`onDepositRequired` throws with timeout error

Implementing robust error handling

actionDelegates={{
  onDepositRequired: async (leg, depositInfo) => {
    const response = await fetch('/api/deposit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        calldata: depositInfo.calldata,
        escrowAddress: depositInfo.escrowAddress,
        chainId: depositInfo.chainId,
      }),
    });

    if (!response.ok) {
      const error = await response.json();

      // Map backend errors to user-friendly messages
      switch (error.code) {
        case 'INSUFFICIENT_BALANCE':
          throw new Error('Insufficient token balance in custody wallet');
        case 'POLICY_VIOLATION':
          throw new Error('Transaction blocked by custody policy. Contact your administrator.');
        case 'ALREADY_DEPOSITED':
          throw new Error('This leg has already been deposited');
        default:
          throw new Error(error.message ?? 'Deposit failed. Please try again.');
      }
    }

    return (await response.json()) as { txHash: string };
  },
}}

Security considerations

The backend deposit endpoint should authenticate the request (verify the session or user identity before submitting a transaction)
Validate that the escrowAddress matches a known KeyStone escrow contract before signing
Implement rate limiting on the deposit endpoint
Log all deposit submissions with the settlement ID, leg index, and caller identity for audit

Next steps

Real-time Tracking

Track deposit progress and settlement state in real time.

Action Delegates Reference

Full reference for all action delegate callbacks.

useDeposit Reference

Full API reference for the useDeposit hook.

Escrow Deposits Guide

Server-side guide for escrow deposits using the SDK.

Overview

Backend SDKs

Frontend Library

Tools

Custody Wallet Integration

Prerequisites

Why action delegates exist

The deposit flow

Frontend setup

Configuring the provider with action delegates

Building the deposit button component

Backend implementation

Fireblocks

BitGo

Generic signing infrastructure

Deposit status states

Error handling

Common failure scenarios

Implementing robust error handling

Security considerations

Next steps

Real-time Tracking

Action Delegates Reference

useDeposit Reference

Escrow Deposits Guide

Overview

Backend SDKs

Frontend Library

Tools

​Prerequisites

​Why action delegates exist

​The deposit flow

​Frontend setup

​Configuring the provider with action delegates

​Building the deposit button component

​Backend implementation

​Fireblocks

​BitGo

​Generic signing infrastructure

​Deposit status states

​Error handling

​Common failure scenarios

​Implementing robust error handling

​Security considerations

​Next steps

Real-time Tracking

Action Delegates Reference

useDeposit Reference

Escrow Deposits Guide

Prerequisites

Why action delegates exist

The deposit flow

Frontend setup

Configuring the provider with action delegates

Building the deposit button component

Backend implementation

Fireblocks

BitGo

Generic signing infrastructure

Deposit status states

Error handling

Common failure scenarios

Implementing robust error handling

Security considerations

Next steps