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.

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.

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 and Authentication.

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 for what the SDK keeps in your share store and why.

Recovery Phrase

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.

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

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.

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

npm

npm install vaults-multichain-sdk

Node.js 18 or newer is required.

Configuration options

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

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.

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

A runnable first integration, install to first transaction

Authentication

API keys, the wallet-password session lifecycle, and userRef

Key Management

shareStore, key shares, rotation and recovery

Recovery Phrase

The account seed: derivation, reveal, and what it means for your wallets

Wallets

Create, import, list, rename, export, portfolio

Hardware Wallets

Ledger and Trezor accounts: what you build, what the SDK gives you

Transactions

Native and token transfers, fee estimation, history

Preflight

Simulate and validate a transaction before broadcasting

Multisig

Personal and organization vaults, owners, thresholds

Orders

Create, sign, reject, and execute multisig orders

Organization

B2B members, roles, org wallets and policies

Errors

Typed error classes, HTTP mapping, retry guidance

FAQ

Common integration questions