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

# Hedera Custodians Library

## Introduction

The Hedera Custodians Library is a TypeScript utility that simplifies custodial wallet management and account operations for the Hedera network. It provides a foundation for building secure, scalable custodial integrations in TypeScript applications.

#### Key Features

* Simplifies integration with the Hedera network
* Abstracts away complexities of custodial wallet management
* Provides a unified interface for different custodial services
* Enhances security and compliance in digital asset management

By leveraging the Hedera Custodians Library, developers can efficiently implement secure and scalable custodial wallet solutions in their Hedera-based applications.

***

## Custodial Wallet Management

Custodial wallet management is the practice of a third party being trusted with storage and security concerning the private keys that are associated with the cryptocurrency. Within the Hedera ecosystem, custodial wallet management is essential for the following reasons:

* **Security**: Custodial services have robust security and safety mechanisms to maintain digital assets.
* **Institutional Adoption**: Many institutional investors require custodial solutions to comply with regulatory requirements and internal risk management policies.
* **Simplified User Experience**: Custodial services may abstract the complexities of key management, making the user's interaction with the Hedera network much easier.
* **Integration with Traditional Finance**: This often bridges cryptocurrency and traditional finance, furthering adoption.
* **Multi-signature Support**: It can be done in various ways through custodial implementations with multi-signature wallets, which contribute to higher security and make more complex governance structures possible.
* **Regulatory Compliance**: Custodial services typically have some in-built compliance features to assist users in conforming to KYC/AML.

The Custodians Library makes it easier to integrate custodial services, providing access to these benefits without custom implementations. It currently supports two providers: **Fireblocks** and **DFNS**.

***

## Fireblocks

If you’re integrating [Fireblocks](https://www.fireblocks.com/), use the official [Fireblocks Hedera SDK Client and Signer](https://github.com/fireblocks/hbar-fireblocks-sdk), which implements [HIP-338](https://hips.hedera.com/hip/hip-338). It provides a drop-in Hedera `Client` and a signer for raw-signing via Fireblocks, plus examples for single and multi-signer flows.

In the context of the Hedera ecosystem:

* **Secure Storage**: HBAR is stored securely on Fireblocks alongside Hedera tokens, using a combination of MPC (Multi-Party Computation) technology and hardware isolation.
* **Securing Transactions**: It offers a policy engine that enables the setup of custom approval flows for every transaction conducted on the Hedera network.
* **Integration**: Fireblocks can be integrated into the Hedera network, allowing seamless transactions with Hedera-based assets and their custodial management.
* **API Access**: The Hedera Custodian Library has full access to the API, which it uses for wallet automation and signing transactions.

<Warning>
  ⚠️ This Custodians Library remains compatible with Fireblocks via its `FireblocksConfig` strategy in the Custodians Integration package (`@hashgraph/hedera-custodians-integration`). However, the official SDK Client/Signer is the **recommended** **path for new builds**.
</Warning>

## DFNS

[DFNS](https://www.dfns.co/) (Digital Financial Network & Security) is a custodial wallet infrastructure provider that offers MPC-based key management and transaction signing services. In the Hedera ecosystem:

* **Key Management**: DFNS provides secure key generation and management for Hedera accounts without exposing private keys.
* **Programmable Authorization**: It offers customizable authorization policies for Hedera transactions, enabling complex approval flows.
* **Multi-Tenancy**: DFNS supports multi-tenant architectures, allowing businesses to manage multiple Hedera accounts for different users or purposes.
* **API-First Approach**: The service provides RESTful APIs that the Hedera Custodian Library uses to interact with Hedera accounts and sign transactions.

Both Fireblocks and DFNS provide secure, compliant custodial solutions. By supporting these providers, the Custodians Library gives developers a unified interface for managing custodial wallets on Hedera.

***

## API Reference

<Accordion title="CustodialWalletService">
  The `CustodialWalletService` class is the main entry point for interacting with custodial wallets.

  ### Constructor

  ```typescript theme={null}
  constructor(config: FireblocksConfig | DFNSConfig)
  ```

  Creates a new instance of the CustodialWalletService with the specified configuration.

  ### Methods

  ```typescript theme={null}
  async signTransaction(request: SignatureRequest): Promise<Uint8Array>
  ```

  Signs a transaction using the configured custodial service.

  * Parameters:
    * `request`: A `SignatureRequest` object containing the transaction to be signed.
  * Returns: A `Promise` that resolves to a `Uint8Array` containing the signature.
</Accordion>

<Accordion title="FireblocksConfig">
  The `FireblocksConfig` class represents the configuration for the Fireblocks custodial service. This configuration is used to initialize the `CustodialWalletService` for Fireblocks integration.

  ### Constructor

  ```typescript theme={null}
  constructor(
    apiKey: string,
    apiSecretKey: string,
    baseUrl: string,
    vaultAccountId: string,
    assetId: string
  )
  ```

  Creates a new `FireblocksConfig` instance.

  ### Properties

  * `apiKey`: The API key for Fireblocks.
  * `apiSecretKey`: The API secret key for Fireblocks.

  - `baseUrl`: The base URL for the Fireblocks API.
  - `vaultAccountId`: The Fireblocks vault account ID.
  - `assetId`: The asset ID for the Hedera token in Fireblocks.
</Accordion>

<Accordion title="DFNSConfig">
  The `DFNSConfig` class represents the configuration for the DFNS custodial service.

  ### Constructor

  ```typescript theme={null}
  constructor(
    serviceAccountAuthorizationToken: string,
    serviceAccountCredentialId: string,
    serviceAccountPrivateKey: string,
    appOrigin: string,
    appId: string,
    walletId: string
  )
  ```

  Creates a new DFNSConfig instance.

  ### Properties

  * `serviceAccountAuthorizationToken`: The authorization token for the DFNS service account.
  * `serviceAccountCredentialId`: The credential ID for the DFNS service account.
  * `serviceAccountPrivateKey`: The private key for the DFNS service account.
  * `appOrigin`: The origin URL of the DFNS app.
  * `appId`: The ID of the DFNS app.
  * `walletId`: The ID of the DFNS wallet.
</Accordion>

<Accordion title="SignatureRequest">
  The `SignatureRequest` class represents a request to sign a transaction.

  ### Constructor

  ```typescript theme={null}
  constructor(transactionBytes: Uint8Array)
  ```

  Creates a new SignatureRequest instance.

  ### Properties

  * `transactionBytes`: A `Uint8Array` containing the transaction bytes to be signed.
</Accordion>

## How to Use the Hedera Custodians Library

See the [How-To Guides](#how-to-use-the-hedera-custodians-library) for integration steps with each provider.