vultisig-sdk

Use this skill when an agent needs to create crypto wallets, send transactions, swap tokens, check balances, or perform any on-chain operation across 36+ blockchains using threshold signatures (TSS). Vultisig SDK provides self-custodial MPC vaults — no seed phrases, no single point of failure. Fast Vaults (2-of-2 with VultiServer) enable fully autonomous agent operations without human approval.

Security Scan

The skill's instructions match a crypto-wallet SDK workflow, but it asks agents to perform fully autonomous on-chain actions (via a remote co-signer) and to handle highly sensitive secrets without declaring or explaining required credentials/endpoints — this mismatch is concerning and needs clarification before use.

Purpose & Capability

The skill's name/description (TSS-based multi-chain wallet operations) aligns with the SDK usage in SKILL.md (create vaults, sign, broadcast, swaps). However: (1) the Fast Vault pattern relies on a remote VultiServer co-signer and email verification but the skill declares no credentials, endpoints, or trust model for that server; (2) the SKILL.md also lists importing wallets via BIP39 seedphrases — a capability that requires handling secrets yet the top-level metadata requests no environment variables or storage configuration. These omissions make the declared purpose only partially coherent with the required operational context.

Instruction Scope

The runtime instructions direct the agent to create Fast Vaults (agent holds a share, VultiServer holds the other), perform prepare→sign→broadcast flows, import/export backups and even import BIP39 seed phrases. They also require email verification for Fast Vault creation and reference multiple external services for swaps (THORChain, 1inch, etc.). The instructions imply network calls and sharing signing payloads with an external co-signer (VultiServer) but do not specify endpoints, auth, or limits — giving broad discretion to the agent to interact with remote services and to handle sensitive secrets (seed phrases, vault shares, backup files).

Install Mechanism

This is instruction-only (no install spec, no code files). That reduces installation risk. The SKILL.md points to an npm package and a GitHub repo as the SDK source; using those is a normal approach but the skill does not perform any automatic network downloads itself.

Credentials

The skill declares no required environment variables or primary credential, yet the workflow clearly needs: email delivery/access (for verification codes), likely a VultiServer endpoint and credentials or API keys for co-signing, and possibly API keys for some swap/price services. Asking the agent to manage/ingest seed phrases and vault backups without declaring how those secrets are stored, protected, or supplied is disproportionate and opaque.

Persistence & Privilege

always:false (good) and disable-model-invocation:false (normal). However the documented Fast Vault design explicitly enables fully autonomous agent operations (VultiServer auto-co-signs based on policies). Combined with the other concerns (no declared auth, handling of seed phrases), this gives the skill high real-world impact: an autonomous agent could create and move funds without human intervention if the VultiServer policy allows it. That elevated blast radius should be visible to administrators before enabling the skill.

What to consider before installing

Before installing or enabling this skill, get clear, authoritative answers from the skill provider: (1) Where is the SDK package published (official npm package name) and what is the canonical GitHub repo / maintainer identity? Inspect that repo and npm package before use. (2) Who operates VultiServer? You need explicit configuration: VULTISERVER_URL, authentication tokens, and a trust/SLAs/privacy policy — the skill should declare these as required variables. (3) How are email verification codes delivered and what credentials/access does the agent need to receive them? Avoid giving agent access to an email account unless you control and monitor it. (4) Do not allow the agent to import BIP39 seed phrases or backups unless you fully understand where those secrets are stored and who can access the co-signer service — prefer Secure Vault (human co-sign) for high-value operations. (5) If you intend to run this in production, require human approval/force multi-signer flows for any transfer above a threshold and run the SDK code review/security audit and a sandbox testnet trial first. Additional information that would change this assessment to 'benign': an official, verifiable upstream repo and npm package; explicit config requirements (VULTISERVER_* env vars) documented in the skill metadata; clear trust / operator details for VultiServer; and explicit instructions that limit autonomous transfers (policy/default limits or required human approval).

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

import { Vultisig, MemoryStorage } from '@vultisig/sdk';

const sdk = new Vultisig({ storage: new MemoryStorage() });
await sdk.initialize();

Source: Vultisig.ts

2. Create a Fast Vault

Two-step process: create (triggers email verification) then verify.

const vaultId = await sdk.createFastVault({
  name: 'my-agent-vault',
  email: '[e-mail]',
  password: 'secure-password',
});

// Verify with the code sent to the email
const vault = await sdk.verifyVault(vaultId, '123456');
// Returns: FastVault instance — ready for operations

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.

const { vault, vaultId, sessionId } = await sdk.createSecureVault({
  name: 'agent-with-human-approval',
  onQRCodeReady: (qrPayload) => {
    // Display QR for the human co-signer to scan with Vultisig app
    displayQRCode(qrPayload);
  },
  onDeviceJoined: (deviceId, total, required) => {
    console.log(`Device joined: ${total}/${required}`);
  },
});

Signing requires the human to participate:

const signature = await vault.sign(payload, {
  onQRCodeReady: (qr) => {
    // Human must scan this QR with Vultisig app to co-sign
    displayQRCode(qr);
  },
  onDeviceJoined: (id, total, required) => {
    console.log(`Signing: ${total}/${required} devices ready`);
  },
});
// Completes only when the human co-signer participates

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

const ethAddress = await vault.address('Ethereum');
const btcAddress = await vault.address('Bitcoin');
const solAddress = await vault.address('Solana');

// All addresses at once
const allAddresses = await vault.addresses();
// Returns: Record<string, string>

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

// Native chain balance
const ethBalance = await vault.balance('Ethereum');
// Returns Balance: {
//   amount: string,      // Raw amount in smallest unit
//   decimals: number,    // Chain decimals (18 for ETH)
//   symbol: string,      // "ETH"
//   chainId: string,
//   fiatValue?: number,  // USD value if available
// }

// Multiple chains
const allBalances = await vault.balances();
// Returns: Record<string, Balance>

// Force refresh (clears cache)
const fresh = await vault.updateBalance('Ethereum');

Token balances (ERC-20, SPL, etc.)

// Get a specific token balance by contract address
const usdcBalance = await vault.balance('Ethereum', '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48');
// Returns Balance: { amount: "1000000", decimals: 6, symbol: "USDC", ... }

// Get all token balances on a chain
const ethTokens = await vault.tokenBalances('Ethereum');
// Returns: Token[] — all tokens with non-zero balances

// Include tokens when fetching multi-chain balances
const everything = await vault.balances(undefined, true); // includeTokens = true

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

// Returns chain-specific gas info
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 }

Source: VaultBase.ts — gas<C extends Chain>(chain: C): Promise<GasInfoForChain<C>>

6. Send a transaction

3-step flow: prepareSendTx → sign → broadcastTx

// Step 1: Prepare keysign payload
const payload = await vault.prepareSendTx({
  coin: {
    chain: 'Ethereum',
    address: ethAddress,     // Sender address (from vault.address())
    decimals: 18,
    ticker: 'ETH',
  },
  receiver: '0xRecipientAddress...',
  amount: BigInt('100000000000000000'), // 0.1 ETH in wei
  memo: '',                             // Optional
});
// Returns: KeysignPayload

// Step 2: Sign (Fast Vault — VultiServer co-signs automatically)
const signature = await vault.sign(payload);
// Returns: Signature { signature: string, recovery?: number, format: 'DER' | 'ECDSA' | 'EdDSA' }

// Step 3: Broadcast
const txHash = await vault.broadcastTx({
  chain: 'Ethereum',
  keysignPayload: payload,
  signature: signature,
});
// Returns: string (transaction hash)

// Explorer URL
const url = Vultisig.getTxExplorerUrl('Ethereum', txHash);

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:

// Send 10 USDC on Ethereum
const tokenPayload = await vault.prepareSendTx({
  coin: {
    chain: 'Ethereum',
    address: ethAddress,
    decimals: 6,            // USDC has 6 decimals
    ticker: 'USDC',
    id: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // Token contract address
  },
  receiver: '0xRecipientAddress...',
  amount: BigInt('10000000'), // 10 USDC (6 decimals)
});

const sig = await vault.sign(tokenPayload);
const txHash = await vault.broadcastTx({
  chain: 'Ethereum',
  keysignPayload: tokenPayload,
  signature: sig,
});

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 → broadcastTx

// Step 1: Get quote
const quote = await vault.getSwapQuote({
  fromCoin: {
    chain: 'Ethereum',
    address: ethAddress,
    decimals: 18,
    ticker: 'ETH',
  },
  toCoin: {
    chain: 'Ethereum',
    address: usdcAddress,
    decimals: 6,
    ticker: 'USDC',
    id: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // Token contract
  },
  amount: 0.1, // Human-readable (NOT bigint)
});
// Returns: SwapQuoteResult {
//   provider: string,
//   estimatedOutput: bigint,
//   estimatedOutputFiat?: number,
//   requiresApproval: boolean,
//   fees: SwapFees,
//   warnings: string[],
// }

// Step 2: Prepare swap transaction
const swapResult = await vault.prepareSwapTx({
  fromCoin: quote.fromCoin,
  toCoin: quote.toCoin,
  amount: 0.1,
  swapQuote: quote,
});
// Returns: SwapPrepareResult {
//   keysignPayload: KeysignPayload,
//   approvalPayload?: KeysignPayload,  // If token approval needed
//   quote: SwapQuoteResult,
// }

// Step 2.5: If approval required, sign and broadcast approval first
if (swapResult.approvalPayload) {
  const approvalSig = await vault.sign(swapResult.approvalPayload);
  await vault.broadcastTx({
    chain: 'Ethereum',
    keysignPayload: swapResult.approvalPayload,
    signature: approvalSig,
  });
}

// Step 3: Sign swap
const swapSig = await vault.sign(swapResult.keysignPayload);

// Step 4: Broadcast swap
const swapTxHash = await vault.broadcastTx({
  chain: 'Ethereum',
  keysignPayload: swapResult.keysignPayload,
  signature: swapSig,
});

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

// Export to encrypted .vult file
const { filename, data } = await vault.export('backup-password');
// filename: string, data: Base64-encoded vault backup

// Import from .vult file
const importedVault = await sdk.importVault(data, 'backup-password');

9. Create vault from seedphrase

// Validate BIP39 seedphrase
const validation = await sdk.validateSeedphrase('word1 word2 ...');
// Returns: { valid: boolean, wordCount: number, error?: string }

// Discover which chains have existing balances
const discovery = await sdk.discoverChainsFromSeedphrase('word1 word2 ...');
// Returns: ChainDiscoveryAggregate

// Create Fast Vault from seedphrase (still needs email verification)
const vaultId = await sdk.createFastVaultFromSeedphrase({
  name: 'imported-vault',
  email: '[e-mail]',
  password: 'secure-password',
  mnemonic: 'word1 word2 ...',
});
const vault = await sdk.verifyVault(vaultId, 'email-code');

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

// List all vaults
const vaults = await sdk.listVaults();

// Set active vault
await sdk.setActiveVault(vault);

// Get active vault
const active = await sdk.getActiveVault();

// Check vault type
if (Vultisig.isFastVault(vault)) { /* FastVault methods */ }
if (Vultisig.isSecureVault(vault)) { /* SecureVault methods */ }

// Delete vault
await sdk.deleteVault(vault);

11. Check transaction status

After broadcasting, use the explorer URL or chain-specific methods to confirm transactions:

// Get explorer URL for any chain
const explorerUrl = Vultisig.getTxExplorerUrl('Ethereum', txHash);
// e.g., "https://etherscan.io/tx/0x..."

const addressUrl = Vultisig.getAddressExplorerUrl('Bitcoin', btcAddress);
// e.g., "https://mempool.space/address/bc1..."

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.

// Pattern: confirm send completed
const balanceBefore = await vault.balance('Ethereum');
// ... broadcast transaction ...
await new Promise(r => setTimeout(r, 15000)); // Wait for block confirmation
const balanceAfter = await vault.updateBalance('Ethereum');
// Compare balanceBefore.amount vs balanceAfter.amount

12. Address book

Manage recurring recipients for automated transfers:

// Get saved addresses (optionally filter by chain)
const allContacts = await sdk.getAddressBook();
const ethContacts = await sdk.getAddressBook('Ethereum');

// Add entries
await sdk.addAddressBookEntry([
  { chain: 'Ethereum', address: '0x...', name: 'Treasury' },
  { chain: 'Bitcoin', address: 'bc1...', name: 'Cold Storage' },
]);

// Update a name
await sdk.updateAddressBookEntry('Ethereum', '0x...', 'Main Treasury');

// Remove entries
await sdk.removeAddressBookEntry([
  { chain: 'Ethereum', address: '0x...' },
]);

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:

// Check current discount tier
const tier = await vault.getDiscountTier();
// Returns: string | null — e.g., "gold", "silver", or null if no discount

// Update tier (after acquiring more $VULT)
const newTier = await vault.updateDiscountTier();

Token contract: 0xb788144DF611029C60b859DF47e79B7726C4DEBa (Ethereum)

14. Listen to events

// SDK-level events
sdk.on('vaultCreationProgress', (data) => { /* keygen progress */ });
sdk.on('vaultCreationComplete', (data) => { /* vault ready */ });
sdk.on('vaultChanged', (data) => { /* active vault switched */ });

// Vault-level events
vault.on('balanceUpdated', (data) => { /* balance changed */ });
vault.on('transactionSigned', (data) => { /* signature complete */ });
vault.on('transactionBroadcast', (data) => { /* tx submitted */ });
vault.on('signingProgress', (data) => { /* signing steps */ });
vault.on('swapQuoteReceived', (data) => { /* quote ready */ });

// SecureVault only (multi-device coordination)
vault.on('qrCodeReady', (data) => { /* show QR for device pairing */ });
vault.on('deviceJoined', (data) => { /* co-signer connected */ });
vault.on('allDevicesReady', (data) => { /* threshold met, signing can proceed */ });

// Error handling
vault.on('error', (error) => { /* handle errors */ });
sdk.on('error', (error) => { /* handle SDK-level errors */ });

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

npm install -g @vultisig/sdk

vsig vault create --name agent-vault --type fast
vsig balance --chain Ethereum
vsig send --chain Ethereum --to 0x... --amount 0.1
vsig swap --from ETH --to USDC --amount 0.1

Source: clients/cli/

Progressive disclosure

• SDK Users Guide — Complete API walkthrough
• Architecture — SDK internals, data flow, design patterns
• Agent Integration Guide — Agent-specific patterns and best practices
• Fast Vault Docs — How VultiServer co-signing works
• Marketplace Plugin Guide — Build automation plugins
• llms.txt — Concise link index for web-browsing agents
• llms-full.txt — Extended context with examples