Getting Started

Introduction

Vaultody is a secure digital asset management platform built on Multi-Party Computation (MPC). Our REST API lets you integrate institutional-grade custody directly into your application — enabling you to receive crypto deposits, send withdrawals, manage wallets, and track transactions across every supported blockchain without ever handling a private key.

This page will get you from zero to your first successful API call in minutes.

Before You Begin

Make sure you have the following before proceeding:

A Vaultody account — sign up here
A Vault created in the Dashboard (Dashboard → Vaults)
An API key generated in the Dashboard (Dashboard → Developers → API Keys → Create New)
Your API Key, API Secret, and Passphrase saved securely

How the Platform is Structured

Vaultody organises your assets across four levels. Understanding this hierarchy is essential before making any API call:

Vault                (your company's root container — created in the Dashboard)
└── Vault Account    (one per user or entity — created via API)
    └── Address      (per blockchain/network; a Vault Account may hold several per chain)
        └── Asset    (added explicitly; the asset holds the balance — ETH, BTC, USDT, …)

Vault — top-level container. You get a vaultId from the Dashboard or GET /vaults/{networkType}.
Vault Account — a logical wallet for one user or entity. Created with POST /vaults/{vaultId}/vault-account.
Address — a deposit address on one blockchain and network. The usual way to get one is to add an asset, which derives the address for you. When a Vault Account needs an additional address for a chain it already uses, call POST /vaults/{vaultId}/{blockchain}/{network}/addresses.
Asset — what actually holds a balance. Every asset a Vault Account holds must be added explicitly, including native coins such as ETH and BTC. On UTXO chains (Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash, Zcash) the native coin is attached automatically when the address is derived, and an address holds exactly one asset. On account-based chains (EVM chains, Tron, Solana, XRP) coins and tokens are both added explicitly, and one address can hold many assets.

An address without the matching asset does not receive funds. A deposit sent to an address that has no record of that asset is not credited and produces no webhook. It is held and processed retroactively once you add the asset. Always add the asset before you publish an address to a user.

Supported Protocols and Networks

Vaultody supports Ethereum, Bitcoin, BNB Smart Chain, Tron, Solana, Polygon, Avalanche, XRP, Arbitrum, Optimism, Base and more — on both mainnet and testnet.

For the full list of supported protocols, see Supported Protocols. The exact blockchain and network string values accepted in API calls are listed on Generate Deposit Address.

The Dashboard

The Vaultody Dashboard is your control panel for account-level operations that complement the API. From the Dashboard you can:

Create and manage Vaults
Set approval policies for outgoing transactions
View balances and transaction history
Create and manage transactions
Generate and manage API keys with scoped permissions
Configure and verify webhook endpoints
Manage team members and their access levels
Access the Vaultody mobile app for transaction approvals

Note: Vaults are created in the Dashboard, not via the API. Before making your first API call you need at least one Vault created and your vaultId ready.

Quick Start: Your First 5 API Calls

The minimal sequence to get a funded, tracked deposit address.

Step 1 — Get your Vault ID

GET /vaults/test

Find the id field in the first item — this is your vaultId. Use main instead of test for production vaults.

{
  "data": {
    "items": [
      {
        "id": "66d866bd469e1d00079d91d5",
        "name": "My Test Vault",
        "type": "test"
      }
    ]
  }
}

Step 2 — Create a Vault Account

POST /vaults/{vaultId}/vault-account

{
  "data": {
    "item": {
      "name": "User Alice",
      "color": "#00C7E6",
      "isHiddenInDashboard": false
    }
  }
}

Save the vaultAccountId from the response.

Step 3 — Find the asset you want to hold

GET /supported-assets?assetUnit=ETH&blockchain=ethereum&networkType=test

Take the id of the asset you want — this is your assetId. Every asset a Vault Account holds must be added explicitly, including native coins such as ETH and BTC.

Step 4 — Add the asset and get the deposit address

PUT /vaults/{vaultId}/vault-accounts/{vaultAccountId}/add-asset

{
  "data": {
    "item": {
      "assetId": "6523e058a06ebf1322d7dd6f",
      "label": "Alice deposit"
    }
  }
}

Pass label when the Vault Account has no address yet for that asset's blockchain and network — Vaultody derives one and returns it as address. Pass address instead of label to add the asset to an address the Vault Account already holds. The blockchain and network come from the asset, so you do not repeat them here.

The returned address is what you share with your user to receive funds.

Add the asset before publishing the address. A deposit of an asset that has not been added is not credited and produces no webhook. It is held and processed retroactively once the asset is added, but your user sees nothing in the meantime.

Step 5 — Listen for Events

Create a webhook endpoint in the Dashboard (Developers → Webhooks), set a Signing Secret, and subscribe to the events you need — INCOMING_CONFIRMED_COIN_TX for native coin deposits, INCOMING_CONFIRMED_TOKEN_TX for tokens. Verify the X-Signature header on every delivery: see Webhooks.

What to do next

More addresses for the same user and chain — Generate Deposit Address, then add assets to the new address with Add Asset (pass address instead of label).
Check a balance — Get Address Balance or List Assets by Vault Account ID.
Send funds — Create Single Transfer for EVM chains, Tron and Solana; Create Multiple Transfer or Create UTXO Transfer for UTXO chains. Outgoing transactions also require an approval policy on the Vault and an approver using the Vaultody mobile app.

Authenticate Requests

Every API request must be signed using HMAC-SHA256. The signature is generated from your API Secret, timestamp, HTTP method, path, request body, and query parameters.

You need to include four headers on every call:

Header	Value
`x-api-key`	Your public API key
`x-api-sign`	Base64-encoded HMAC-SHA256 signature
`x-api-timestamp`	Current UNIX timestamp in seconds
`x-api-passphrase`	Your passphrase

For the complete signing process with code examples in Python, Node.js, PHP and Postman, see Vaultody API Authentication.

Test vs. Production

Use a test vault (type: test) during development — it connects to blockchain testnets and uses funds with no real monetary value.

Switch to a main vault (type: main) when going to production. Mainnet access requires a paid subscription plan.

Development:  GET /vaults/test  → use testnet networks (sepolia, nile, testnet…)
Production:   GET /vaults/main  → use mainnet networks (mainnet…)

What's Next

Vaultody API Authentication — complete signing guide with code examples
Standards and Conventions — request and response envelopes, status codes, versioning
Data Flow Limiting — rate limits and cursor pagination
Webhooks — real-time event notifications and signature verification
Transaction Policies — how approvals gate outgoing transactions
Backup and Restore a Vault — the Vaultody Open Source Recovery Tool
Create Single Transfer — send funds from a Vault Account

Need Help?

If you need additional assistance, visit the Vaultody Help Center for FAQs, guides, and direct support, or email us at [email protected].

Was this page helpful?

Yes