Vultisig SDK Skill (agent-first)
What this Skill is for
- - Creating and managing self-custodial crypto vaults (Fast Vault for agents, Secure Vault for multi-device)
- Sending transactions across 36+ blockchains (Bitcoin, Ethereum, Solana, Cosmos, and more)
- Swapping tokens cross-chain via THORChain, MayaChain, 1inch, LiFi, KyberSwap
- Querying balances and gas fees across all supported chains
- Importing/exporting vault backups (.vult files)
- Importing existing wallets via BIP39 seedphrase
- Building automated strategies: DCA, rebalancing, conditional swaps, agent-to-agent payments
Default stack decisions
1) Fast Vault (2-of-2) for all agent use cases
- Agent holds one key share, VultiServer holds the other
- VultiServer auto-co-signs based on policy rules — no human in the loop
- Use Secure Vault only when multi-device human approval is required
2) TypeScript SDK (@vultisig/sdk) as primary interface
- npm install @vultisig/sdk
- Source: github.com/vultisig/vultisig-sdk
- SDK Users Guide: docs/SDK-USERS-GUIDE.md
3) MemoryStorage for ephemeral agents, implement Storage interface for persistent agents
- MemoryStorage is the only storage exported from the SDK
- For persistent vaults, implement the Storage interface backed by your preferred store
4) 3-step transaction flow: prepare → sign → broadcast
- Never skip steps. Always prepare the keysign payload first, then sign, then broadcast.
- Fast Vault signing is automatic (VultiServer co-signs). Secure Vault requires device coordination.
5) Amounts as bigint (smallest unit) for sends, number (human-readable) for swaps
- prepareSendTx takes amount: bigint (e.g., BigInt('100000000000000000') for 0.1 ETH)
- getSwapQuote takes amount: number (e.g., 0.1 for 0.1 ETH)
Operating procedure
1. Initialize SDK
CODEBLOCK0
Source: Vultisig.ts
2. Create a Fast Vault
Two-step process: create (triggers email verification) then verify.
CODEBLOCK1
Risk notes:
- - The password encrypts the vault share. If lost, the vault cannot be recovered.
- The email verification code is required — agents must have email access or an email relay.
2b. Create a Secure Vault (human co-signing)
When agents need human approval before executing transactions (high-value transfers, treasury ops, compliance flows), use a Secure Vault. The agent holds one share, the human holds the other. The human co-signs via the Vultisig mobile app by scanning a QR code — the transaction only executes when both parties agree.
CODEBLOCK2
Signing requires the human to participate:
CODEBLOCK3
Source: SecureVault.ts
When to use Secure Vault over Fast Vault:
- - Transactions above a risk threshold that need human sign-off
- Treasury or DAO operations requiring human approval
- Compliance workflows where an agent should not act unilaterally
3. Get addresses
CODEBLOCK4
Source: VaultBase.ts
Chain identifiers use PascalCase strings matching the Chain enum: 'Bitcoin', 'Ethereum', 'Solana', 'THORChain', 'Cosmos', 'Polygon', 'Arbitrum', 'Base', 'Optimism', 'Avalanche', 'BSC', etc.
Full chain list: Chain.ts
4. Check balances
CODEBLOCK5
Token balances (ERC-20, SPL, etc.)
CODEBLOCK6
Risk notes:
- - Native balance and token balances are separate queries.
vault.balance('Ethereum') returns only ETH, not ERC-20s. - Token balances require the contract address as the
tokenId parameter.
5. Estimate gas
CODEBLOCK7
Source: VaultBase.ts — INLINECODE34
6. Send a transaction
3-step flow: prepareSendTx → sign → INLINECODE37
CODEBLOCK8
Source: VaultBase.prepareSendTx(), FastVault.sign()
Risk notes:
- -
amount is in the chain's smallest unit (wei for ETH, satoshi for BTC). Miscalculating decimals will send wrong amounts. - Always verify the receiver address. Transactions are irreversible.
- Check gas estimation before sending to avoid stuck transactions.
Sending ERC-20 / tokens
To send tokens instead of native currency, add the id field (contract address) to the coin object:
CODEBLOCK9
Risk notes:
- - The
id field is the token contract address. Without it, the SDK treats it as a native transfer. - Use the token's decimals, not the chain's. USDC = 6, WETH = 18, WBTC = 8.
- The sender still needs native ETH/gas token to pay transaction fees.
7. Swap tokens
4-step flow: getSwapQuote → prepareSwapTx → sign → INLINECODE47
CODEBLOCK10
Swap providers (auto-routed for best rate):
- - THORChain — Native cross-chain (BTC <> ETH, etc.)
- MayaChain — Additional cross-chain pairs
- 1inch — EVM DEX aggregation
- LiFi — Cross-chain + cross-DEX
- KyberSwap — EVM DEX aggregation
Risk notes:
- - Swap amounts use human-readable numbers (
0.1), not bigint. The SDK handles decimal conversion. - Check
quote.warnings before executing — may contain slippage or liquidity warnings. - ERC-20 token swaps may require a separate approval transaction (
approvalPayload). - Cross-chain swaps take longer (minutes, not seconds) and have different failure modes.
8. Export / Import vault
CODEBLOCK11
9. Create vault from seedphrase
CODEBLOCK12
Risk notes:
- - Seedphrase import creates a new TSS vault from the seed — the original seed-based wallet still exists independently.
- Handle seedphrases with extreme care. Never log, store in plaintext, or transmit unencrypted.
10. Vault lifecycle management
CODEBLOCK13
11. Check transaction status
After broadcasting, use the explorer URL or chain-specific methods to confirm transactions:
CODEBLOCK14
For automated strategies that need to confirm completion before the next action, poll the balance or use an external RPC/indexer to check transaction finality. The SDK does not provide a built-in tx status poller — use vault.updateBalance() to force-refresh after a broadcast and compare before/after.
CODEBLOCK15
12. Address book
Manage recurring recipients for automated transfers:
CODEBLOCK16
Source: Vultisig.ts
13. $VULT discount tiers
Holding $VULT tokens reduces swap fees (up to 50%). The SDK can check and update the agent's discount tier:
CODEBLOCK17
Token contract: 0xb788144DF611029C60b859DF47e79B7726C4DEBa (Ethereum)
14. Listen to events
CODEBLOCK18
Source: packages/sdk/src/events/
Supported chains
Source: Chain.ts
| Category | Chains | Signature |
|---|
| UTXO | Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Dash, Zcash | ECDSA |
| EVM |
Ethereum, BSC, Polygon, Avalanche, Arbitrum, Optimism, Base, Blast, Cronos, zkSync, Hyperliquid, Mantle, Sei | ECDSA |
|
Cosmos/IBC | THORChain, MayaChain, Cosmos Hub, Osmosis, Dydx, Kujira, Noble, Terra, Terra Classic, Akash | ECDSA |
|
Other | Solana, Sui, Polkadot, TON, Ripple, Tron, Cardano | EdDSA / Mixed |
Security model
- - No seed phrases — vault shares replace 12/24 word seeds
- No single point of failure — no device holds a complete private key
- No on-chain key registration — unlike multi-sig wallets
- DKLS23 protocol — 3-round TSS, co-developed with Silence Laboratories
- Open source and audited
- Docs: Security & Technology
CLI alternative
CODEBLOCK19
Source: clients/cli/
Progressive disclosure
Vultisig SDK 技能（智能体优先）
本技能的用途
- - 创建和管理自托管加密金库（智能体用快速金库，多设备用安全金库）
- 在36+条区块链上发送交易（比特币、以太坊、Solana、Cosmos等）
- 通过THORChain、MayaChain、1inch、LiFi、KyberSwap进行跨链代币兑换
- 查询所有支持链上的余额和Gas费用
- 导入/导出金库备份（.vult文件）
- 通过BIP39助记词导入现有钱包
- 构建自动化策略：定投、再平衡、条件兑换、智能体间支付
默认技术栈决策
1) 所有智能体用例使用快速金库（2-of-2）
- 智能体持有一个密钥分片，VultiServer持有另一个
- VultiServer根据策略规则自动联合签名——无需人工参与
- 仅在需要多设备人工审批时使用安全金库
2) TypeScript SDK（@vultisig/sdk）作为主要接口
- npm install @vultisig/sdk
- 源码：github.com/vultisig/vultisig-sdk
- SDK用户指南：docs/SDK-USERS-GUIDE.md
3) 临时智能体使用MemoryStorage，持久化智能体实现Storage接口
- MemoryStorage是SDK导出的唯一存储实现
- 对于持久化金库，实现由你偏好的存储后端支持的Storage接口
4) 3步交易流程：准备 → 签名 → 广播
- 切勿跳过步骤。始终先准备密钥签名负载，然后签名，最后广播。
- 快速金库签名是自动的（VultiServer联合签名）。安全金库需要设备协调。
5) 发送时金额使用bigint（最小单位），兑换时使用number（人类可读）
- prepareSendTx接收amount: bigint（例如，0.1 ETH为BigInt(100000000000000000)）
- getSwapQuote接收amount: number（例如，0.1 ETH为0.1）
操作流程
1. 初始化SDK
typescript
import { Vultisig, MemoryStorage } from @vultisig/sdk;
const sdk = new Vultisig({ storage: new MemoryStorage() });
await sdk.initialize();
源码：Vultisig.ts
2. 创建快速金库
两步流程：创建（触发邮箱验证）然后验证。
typescript
const vaultId = await sdk.createFastVault({
name: my-agent-vault,
email: agent@example.com,
password: secure-password,
});
// 使用发送到邮箱的验证码进行验证
const vault = await sdk.verifyVault(vaultId, 123456);
// 返回：FastVault实例——可立即操作
风险提示：
- - 密码加密金库分片。如果丢失，金库无法恢复。
- 需要邮箱验证码——智能体必须能访问邮箱或使用邮箱中继。
2b. 创建安全金库（人工联合签名）
当智能体在执行交易前需要人工审批时（高价值转账、资金库操作、合规流程），使用安全金库。智能体持有一个分片，人工持有另一个。人工通过Vultisig移动应用扫描二维码进行联合签名——交易仅在双方同意时执行。
typescript
const { vault, vaultId, sessionId } = await sdk.createSecureVault({
name: agent-with-human-approval,
onQRCodeReady: (qrPayload) => {
// 显示二维码供人工联合签名者用Vultisig应用扫描
displayQRCode(qrPayload);
},
onDeviceJoined: (deviceId, total, required) => {
console.log(设备已加入：${total}/${required});
},
});
签名需要人工参与：
typescript
const signature = await vault.sign(payload, {
onQRCodeReady: (qr) => {
// 人工必须用Vultisig应用扫描此二维码以联合签名
displayQRCode(qr);
},
onDeviceJoined: (id, total, required) => {
console.log(签名中：${total}/${required}台设备就绪);
},
});
// 仅在人工联合签名者参与时完成
源码：SecureVault.ts
何时使用安全金库而非快速金库：
- - 超过风险阈值需要人工签批的交易
- 需要人工审批的资金库或DAO操作
- 智能体不应单方面行动的合规工作流
3. 获取地址
typescript
const ethAddress = await vault.address(Ethereum);
const btcAddress = await vault.address(Bitcoin);
const solAddress = await vault.address(Solana);
// 一次性获取所有地址
const allAddresses = await vault.addresses();
// 返回：Record
源码：VaultBase.ts
链标识符使用与Chain枚举匹配的帕斯卡命名法字符串：Bitcoin、Ethereum、Solana、THORChain、Cosmos、Polygon、Arbitrum、Base、Optimism、Avalanche、BSC等。
完整链列表：Chain.ts
4. 检查余额
typescript
// 原生链余额
const ethBalance = await vault.balance(Ethereum);
// 返回 Balance：{
// amount: string, // 最小单位的原始金额
// decimals: number, // 链的小数位数（ETH为18）
// symbol: string, // ETH
// chainId: string,
// fiatValue?: number, // 如有，美元价值
// }
// 多条链
const allBalances = await vault.balances();
// 返回：Record
// 强制刷新（清除缓存）
const fresh = await vault.updateBalance(Ethereum);
代币余额（ERC-20、SPL等）
typescript
// 通过合约地址获取特定代币余额
const usdcBalance = await vault.balance(Ethereum, 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48);
// 返回 Balance：{ amount: 1000000, decimals: 6, symbol: USDC, ... }
// 获取链上所有代币余额
const ethTokens = await vault.tokenBalances(Ethereum);
// 返回：Token[]——所有非零余额的代币
// 获取多链余额时包含代币
const everything = await vault.balances(undefined, true); // includeTokens = true
风险提示：
- - 原生余额和代币余额是分开的查询。vault.balance(Ethereum)仅返回ETH，不返回ERC-20代币。
- 代币余额需要将合约地址作为tokenId参数。
5. 估算Gas
typescript
// 返回链特定的Gas信息
const evmGas = await vault.gas(Ethereum);
// EvmGasInfo：{ gasPrice, gasPriceGwei, maxFeePerGas, maxPriorityFeePerGas, gasLimit, estimatedCostUSD }
const utxoGas = await vault.gas(Bitcoin);
// UtxoGasInfo：{ gasPrice, byteFee, estimatedCostUSD }
const cosmosGas = await vault.gas(Cosmos);
// CosmosGasInfo：{ gasPrice, gas, estimatedCostUSD }
源码：VaultBase.ts — gas(chain: C): Promise>
6. 发送交易
3步流程：prepareSendTx → sign → broad
