> ## Documentation Index
> Fetch the complete documentation index at: https://sdk-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Server-side, non-custodial multi-chain wallets with vaults-multichain-sdk (TrustodianSDK)

## Overview

`vaults-multichain-sdk` (main class `TrustodianSDK`) is a TypeScript library for server-side integrators. It wraps the Trustodian REST API and handles all key material locally: unlocking a session from the user's wallet password, rebuilding keys from shares, deriving wallets from the account recovery phrase, and signing on each chain.

> [!WARNING]
>
> **Backend only.** The SDK holds API keys, wallet passwords and reconstructed key material in
> process memory. Never ship it to a browser or mobile client.

## Before you start

The SDK works with accounts that already exist. It cannot create one.

An API key is only issued once its account has finished onboarding in the Trustodian app, so three things are already true before your integration runs:

1. The account is registered.
2. It has a wallet password.
3. It has a recovery phrase, generated or imported, or a hardware wallet (Ledger or Trezor) as the account root.

Your integration takes the API key and the user's wallet password, unlocks the session, and works with wallets derived from the seed that already exists.

> [!NOTE]
>
> There is no registration, login or key-issuing call in the SDK, and an API key cannot create
> another API key. If you need one, someone signs in to the app and issues it.

## Non-custodial model

Trustodian never stores a complete private key or a complete recovery phrase.

| Piece | Who provides it |
| - | - |
| API key | Your backend. Authenticates every API call |
| Wallet password | Your end user. Unlocks the keys that decrypt the stored shares |
| Device share | Your backend, persisted through the `shareStore` you implement |
| `userRef` | `await sdk.getSdkUserId()`. Ties sessions and `shareStore` entries to one account |

Read-only calls (wallet lists, portfolio, orders) need only the API key. Anything that touches key material needs `shareStore` plus an unlocked wallet-password session. See [Key Management](https://sdk-guide.mintlify.site/sdk-guide/key-management.md) and [Authentication](https://sdk-guide.mintlify.site/sdk-guide/authentication.md).

## The account recovery phrase

Each account has one recovery phrase, created during app onboarding, and every wallet is derived from it, so omit `mode` on `createWallet`. See [Key Management](https://sdk-guide.mintlify.site/sdk-guide/key-management.md) for what the SDK keeps in your share store and why.

> **[Recovery Phrase](https://sdk-guide.mintlify.site/sdk-guide/recovery-phrase.md)**
>
> Derivation paths per chain, reading the state, revealing the phrase, and the errors

An account can instead use a hardware wallet as its root. The wallets then derive on the device, and your frontend runs the device steps. See [Hardware Wallets](https://sdk-guide.mintlify.site/sdk-guide/hardware-wallets.md).

## Supported chains

`EChainType` defines seven chain types:

| Chain | `EChainType` | Native currency | Decimals | Chain id values |
| - | - | - | - | - |
| EVM | `EVM` | ETH | 18 | numeric chain ids, listed below |
| Solana | `SOL` | SOL | 9 | `sol_mainnet` / `sol_devnet` |
| Tron | `TRON` | TRX | 6 | `tron_mainnet` / `tron_shasta` |
| Bitcoin | `BTC` | BTC | 8 | `BTC` (mainnet only) |
| Bitcoin testnet | `BTC_T3` | BTC | 8 | `BTC_T3` (testnet only) |
| Cardano | `ADA` | ADA | 6 | `ada_mainnet` / `ada_preprod` |
| XRP Ledger | `XRP` | XRP | 6 | `xrp_mainnet` / `xrp_testnet` |

> [!NOTE]
>
> Bitcoin is the one chain whose chain type differs per network: `BTC` on mainnet, `BTC_T3` on
> testnet. Call `getBtcChainType()` instead of hardcoding either.

### EVM chain ids

`network: 'mainnet'` and `network: 'testnet'` each ship a fixed set of EVM chain ids with default RPC endpoints. A chain id outside the configured set throws `No RPC endpoint configured for EVM chain ID …` unless you add it via `rpcOverrides`.

| Chain id | Network |
| - | - |
| `1` | Ethereum |
| `10` | Optimism |
| `56` | BNB Smart Chain |
| `137` | Polygon |
| `8453` | Base |
| `42161` | Arbitrum One |
| `43114` | Avalanche C-Chain |

The same seven networks are configured on testnet under their own chain ids, Ethereum Sepolia
(`'11155111'`) among them.

> [!NOTE]
>
> Cardano ships no default RPC endpoint and does not need one, because Cardano UTXO sourcing goes
> through the Trustodian backend. Set `rpcOverrides.ada_mainnet` / `rpcOverrides.ada_preprod` only
> if your own code resolves an ADA endpoint from the SDK's RPC config.

## Installation

```bash npm theme={null}
npm install vaults-multichain-sdk
```

```bash yarn theme={null}
yarn add vaults-multichain-sdk
```

Node.js 18 or newer is required.

## Configuration options

```typescript theme={null}
import { TrustodianSDK, InMemoryShareStore } from 'vaults-multichain-sdk';

const sdk = new TrustodianSDK({
  apiKey: process.env.TRUSTODIAN_API_KEY!,
  network: 'testnet',
  shareStore: new InMemoryShareStore(),
});
```

| Option | Required | Default | Description |
| - | - | - | - |
| `apiKey` | Yes | none | Sent as the `x-api-key` header. Empty or whitespace throws `apiKey is required` |
| `network` | Yes | none | `'mainnet'` or `'testnet'`. Optional in the type, but omitting it throws `network must be provided` |
| `shareStore` | Yes | none | Your `IntegratorShareStore` for device shares. Omitting it throws `shareStore is required for SDK v2 wallet-password flows` |
| `apiBaseUrl` | No | Per network, see below | Override the API host |
| `apiPathPrefix` | No | `'/sdk'` | Route prefix. Normalized: leading slash added, trailing slashes stripped, empty falls back to `/sdk` |
| `timeout` | No | `30000` | Per-request timeout in ms. An overrun raises `TimeoutError` |
| `rpcOverrides` | No | `{}` | Per-chain RPC URLs, keyed by `ChainIdValue` (`'1'`, `'sol_mainnet'`, `'ada_preprod'`) |
| `keyTtlMs` | No | `300000` (5 min) | How long an unlocked session stays open |
| `seedEntropyCache` | No | none | Deprecated and ignored. The account seed is never kept between calls; setting it logs a one-time warning. See [Strict authentication](https://sdk-guide.mintlify.site/sdk-guide/strict-authentication.md#seed-wallets-need-the-password-on-every-signature) |

The SDK carries a default API host for each network, so `apiBaseUrl` is optional. Set it explicitly
for your own deployment, and ask your Trustodian contact which host your API key is issued against
rather than relying on the default.

```typescript theme={null}
const sdk = new TrustodianSDK({
  apiKey: process.env.TRUSTODIAN_API_KEY!,
  network: 'testnet',
  shareStore: myShareStore,
  apiBaseUrl: 'https://your-api.example.com',
  keyTtlMs: 600_000,
  rpcOverrides: {
    '11155111': 'https://your-sepolia-rpc.example.com',
    ada_preprod: 'https://your-cardano-endpoint.example.com',
  },
});
```

## Where to go next

> **[Quickstart](https://sdk-guide.mintlify.site/sdk-guide/quickstart.md)**
>
> A runnable first integration, install to first transaction

> **[Authentication](https://sdk-guide.mintlify.site/sdk-guide/authentication.md)**
>
> API keys, the wallet-password session lifecycle, and `userRef`

> **[Key Management](https://sdk-guide.mintlify.site/sdk-guide/key-management.md)**
>
> `shareStore`, key shares, rotation and recovery

> **[Recovery Phrase](https://sdk-guide.mintlify.site/sdk-guide/recovery-phrase.md)**
>
> The account seed: derivation, reveal, and what it means for your wallets

> **[Wallets](https://sdk-guide.mintlify.site/sdk-guide/wallets.md)**
>
> Create, import, list, rename, export, portfolio

> **[Hardware Wallets](https://sdk-guide.mintlify.site/sdk-guide/hardware-wallets.md)**
>
> Ledger and Trezor accounts: what you build, what the SDK gives you

> **[Transactions](https://sdk-guide.mintlify.site/sdk-guide/transactions.md)**
>
> Native and token transfers, fee estimation, history

> **[Preflight](https://sdk-guide.mintlify.site/sdk-guide/preflight.md)**
>
> Simulate and validate a transaction before broadcasting

> **[Multisig](https://sdk-guide.mintlify.site/sdk-guide/multisig.md)**
>
> Personal and organization vaults, owners, thresholds

> **[Orders](https://sdk-guide.mintlify.site/sdk-guide/orders.md)**
>
> Create, sign, reject, and execute multisig orders

> **[Organization](https://sdk-guide.mintlify.site/sdk-guide/organization.md)**
>
> B2B members, roles, org wallets and policies

> **[Errors](https://sdk-guide.mintlify.site/sdk-guide/errors.md)**
>
> Typed error classes, HTTP mapping, retry guidance

> **[FAQ](https://sdk-guide.mintlify.site/sdk-guide/faq.md)**
>
> Common integration questions


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