vultisig

Original source / Raw SKILL.md

---
name: vultisig
description: MPC wallet for AI agents. Secure multi-chain crypto operations with threshold signing across 36+ blockchains. Routes to CLI (shell commands) or SDK (TypeScript) based on your use case.
version: 1.0.0
author: Vultisig
repository: https://github.com/vultisig/vultisig-sdk
metadata:
  openclaw:
    emoji: "🔐"
    homepage: https://github.com/vultisig/vultisig-sdk
tags:
  - crypto
  - wallet
  - mpc
  - blockchain
  - defi
  - bitcoin
  - ethereum
  - solana
  - polygon
  - arbitrum
  - optimism
  - base
  - avalanche
  - bsc
  - litecoin
  - dogecoin
  - cosmos
  - thorchain
  - mayachain
  - osmosis
  - dydx
  - kujira
  - sui
  - polkadot
  - ton
  - ripple
  - tron
  - cardano
  - zcash
  - dash
  - blast
  - cronos
  - zksync
  - hyperliquid
  - mantle
  - sei
  - terra
  - noble
  - akash
  - bitcoin-cash
---

# Vultisig

Vultisig is an MPC (Multi-Party Computation) wallet that enables secure crypto operations across 36+ blockchains. Unlike traditional wallets, private keys are split across multiple parties using threshold cryptography - there's no single key to steal.

## Why MPC Wallets for AI Agents

Traditional wallets store a single private key or seed phrase. If compromised, all funds are lost. MPC eliminates this risk:

- **No single point of failure**: Keys are split across parties using cryptographic secret sharing
- **Threshold security**: 2-of-2 or N-of-M signing - compromising one party isn't enough
- **No seed phrase exposure**: No mnemonic stored in plaintext anywhere
- **Automation-friendly**: FastVault enables instant server-assisted signing for bots
- **Programmable trust**: Choose speed (FastVault) or maximum security (SecureVault)
- **Audit trail**: All signing requires explicit multi-party coordination

## Choose Your Interface

| Use Case | Interface | Why |
|----------|-----------|-----|
| Shell scripts | [CLI](./vultisig-cli/SKILL.md) | Direct commands, easy scripting |
| Automation bots | [CLI](./vultisig-cli/SKILL.md) | Simple, pipes to jq, env vars |
| One-off operations | [CLI](./vultisig-cli/SKILL.md) | Quick, no code needed |
| TypeScript/Node apps | [SDK](./vultisig-sdk/SKILL.md) | Full API, type safety |
| Custom transaction logic | [SDK](./vultisig-sdk/SKILL.md) | signBytes, broadcastRawTx |
| Browser/React apps | [SDK](./vultisig-sdk/SKILL.md) | Event system, async/await |
| Complex workflows | [SDK](./vultisig-sdk/SKILL.md) | Programmatic control |

### Quick Decision

**Use CLI if**: You're writing shell scripts, need quick commands, or want JSON output piped to other tools.

**Use SDK if**: You're building a TypeScript application, need programmatic control, or want event-driven updates.

## Vault Types

| Type | Threshold | Signing | Best For |
|------|-----------|---------|----------|
| **FastVault** | 2-of-2 (device + server) | Instant (~1-2s) | AI agents, bots, automation |
| **SecureVault** | N-of-M (configurable) | Multi-device coordination | Teams, high-value assets |

**For AI agents, FastVault is recommended** - instant signing without multi-device coordination.

## Supported Chains (36+)

### EVM Chains (13)
Ethereum, Polygon, BSC, Arbitrum, Optimism, Base, Avalanche, Blast, Cronos, zkSync, Hyperliquid, Mantle, Sei

### UTXO Chains (6)
Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Dash, Zcash

### Cosmos Chains (10)
Cosmos, THORChain, MayaChain, Osmosis, dYdX, Kujira, Terra, Terra Classic, Noble, Akash

### Other Chains (7)
Solana, Sui, Polkadot, TON, Ripple, Tron, Cardano

## Core Operations

Both CLI and SDK support:
- **Create vaults**: FastVault (instant) or SecureVault (multi-device)
- **Import/Export**: Backup and restore vaults, import from seedphrase (BIP39)
- **Addresses**: Derive addresses for any chain
- **Balances**: Check native and token balances
- **Send**: Transfer crypto to any address
- **Swap**: Cross-chain swaps via THORChain, same-chain via 1inch and LiFi
- **Sign**: Sign transactions or arbitrary bytes

SDK-only capabilities:
- **Token Discovery**: Look up known tokens, discover tokens at addresses
- **Price Feeds**: Fetch token prices via CoinGecko
- **Security Scanning**: Site scanning, transaction validation, transaction simulation
- **Fiat On-Ramp**: Buy crypto via Banxa integration
- **Cosmos Signing**: SignAmino and SignDirect for Cosmos dApps
- **Event System**: Reactive updates for balances, signing, and more

## Get Started

### CLI Quick Start
```bash
npm install -g @vultisig/cli
vultisig create fast --name "bot-wallet" --email "[email protected]" --password "SecurePass123!"
vultisig balance -o json
```
→ [Full CLI Documentation](./vultisig-cli/SKILL.md)

### SDK Quick Start
```typescript
import { Vultisig, Chain } from '@vultisig/sdk'

const sdk = new Vultisig()
await sdk.initialize()

const vaultId = await sdk.createFastVault({
  name: 'bot-wallet',
  email: '[email protected]',
  password: 'SecurePass123!'
})
const vault = await sdk.verifyVault(vaultId, 'email-code')
const balance = await vault.balance(Chain.Ethereum)
```
→ [Full SDK Documentation](./vultisig-sdk/SKILL.md)

## Resources

- [GitHub Repository](https://github.com/vultisig/vultisig-sdk)
- [CLI Documentation](./vultisig-cli/SKILL.md)
- [SDK Documentation](./vultisig-sdk/SKILL.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### vultisig-cli/SKILL.md

```markdown
---
name: vultisig-cli
description: MPC wallet CLI for secure multi-chain crypto operations across 36+ blockchains. Use when the user wants to create MPC wallets, send crypto, swap tokens cross-chain, check balances, sign transactions, or manage multi-signature vaults. Supports Bitcoin, Ethereum, Solana, and 33+ other chains with threshold signing security.
version: 1.0.0
author: Vultisig
repository: https://github.com/vultisig/vultisig-sdk
metadata:
  openclaw:
    emoji: "🔐"
    homepage: https://github.com/vultisig/vultisig-sdk
    requires:
      bins:
        - vultisig
    install:
      npm: "@vultisig/cli"
tags:
  - crypto
  - wallet
  - mpc
  - cli
  - defi
  - bitcoin
  - ethereum
  - solana
---

# Vultisig CLI

Command-line interface for Vultisig MPC wallet operations. See the [router skill](../SKILL.md) for an overview of MPC benefits and to choose between CLI and SDK.

## Installation

```bash
npm install -g @vultisig/cli
vultisig --version
```

Or run without installing:
```bash
npx @vultisig/cli balance ethereum
```

## Security Considerations

**CRITICAL: Read before executing any commands**

1. **Never store passwords in scripts, logs, or environment variables visible to others**
2. **Use `--password` flag only in secure, ephemeral contexts**
3. **Always verify recipient addresses** - transactions are irreversible
4. **Export backups before destructive operations** - use `vultisig export`
5. **Use `-o json` for automation** - structured output prevents parsing errors

## Vault Types

| Type | Threshold | Signing | Best For |
|------|-----------|---------|----------|
| **FastVault** | 2-of-2 (device + server) | Instant, server-assisted | AI agents, automation, bots |
| **SecureVault** | N-of-M (configurable) | Multi-device coordination | Teams, high-value assets |

**For AI agents, FastVault is recommended** - it enables instant signing without multi-device coordination.

See [references/vault-types.md](references/vault-types.md) for detailed comparison.

## Quick Start

### 1. Create a FastVault

```bash
vultisig create fast --name "agent-wallet" --email "[email protected]" --password "SecurePass123!"
# Enter email verification code when prompted
```

### 2. Get Addresses

```bash
vultisig addresses -o json
```

### 3. Check Balance

```bash
vultisig balance ethereum -o json
vultisig balance --tokens -o json  # Include ERC-20 tokens
```

### 4. Send Transaction

```bash
vultisig send ethereum 0xRecipient... 0.1 --password "SecurePass123!" -y -o json
```

### 5. Swap Tokens

```bash
vultisig swap-quote ethereum bitcoin 0.1 -o json
vultisig swap ethereum bitcoin 0.1 --password "SecurePass123!" -y -o json
```

## Core Commands

### Vault Management

| Command | Description |
|---------|-------------|
| `create fast --name --email --password` | Create FastVault (server-assisted 2-of-2) |
| `create secure --name --shares N` | Create SecureVault (multi-device N-of-M) |
| `vaults -o json` | List all vaults |
| `switch <vaultId>` | Switch active vault |
| `info -o json` | Show vault details |
| `import <file.vult>` | Import vault from backup |
| `export [path]` | Export vault backup |
| `delete [vault] -y` | Delete vault |
| `verify <vaultId>` | Verify with email code |

### Wallet Operations

| Command | Description |
|---------|-------------|
| `addresses -o json` | Get all addresses |
| `balance [chain] -o json` | Get balance (optional: specific chain) |
| `balance --tokens -o json` | Include token balances |
| `portfolio -o json` | Total portfolio value in fiat |
| `send <chain> <to> <amount>` | Send native token |
| `send <chain> <to> <amount> --token <addr>` | Send ERC-20 token |

### Swap Operations

| Command | Description |
|---------|-------------|
| `swap-chains` | List chains supporting swaps |
| `swap-quote <from> <to> <amount>` | Get swap quote |
| `swap <from> <to> <amount>` | Execute swap |

### Chain & Token Management

| Command | Description |
|---------|-------------|
| `chains` | List active chains |
| `chains --add Solana` | Enable a chain |
| `chains --add-all` | Enable all 36+ chains |
| `chains --remove Litecoin` | Disable a chain |
| `tokens <chain>` | List tokens on chain |
| `tokens <chain> --add <contract>` | Add custom token |

### Advanced Operations

| Command | Description |
|---------|-------------|
| `sign --chain <chain> --bytes <base64>` | Sign pre-hashed bytes |
| `broadcast --chain <chain> --raw-tx <hex>` | Broadcast raw transaction |

## JSON Output Mode

**Always use `-o json` for AI agent automation.** This provides structured, parseable output:

```bash
# Balance
vultisig balance ethereum -o json
# {"chain":"ethereum","balance":{"native":"1.5","symbol":"ETH","usdValue":"3750.00"}}

# Send transaction
vultisig send ethereum 0x... 0.1 -y --password "pass" -o json
# {"txHash":"0x...","chain":"ethereum","explorerUrl":"https://etherscan.io/tx/0x..."}

# Vault info
vultisig info -o json
# {"vault":{"id":"...","name":"...","type":"fast","chains":[...]}}
```

## Common Workflows

### Workflow: First-Time Setup

```bash
# 1. Create vault
vultisig create fast --name "agent-wallet" --email "[email protected]" --password "SecurePass123!"
# Enter verification code

# 2. Enable desired chains
vultisig chains --add-all

# 3. Get addresses
vultisig addresses -o json

# 4. Check balances
vultisig balance -o json
```

### Workflow: Send Crypto

```bash
# 1. Check balance
BALANCE=$(vultisig balance ethereum -o json | jq -r '.balance.native')

# 2. Verify sufficient funds
if (( $(echo "$BALANCE > 0.1" | bc -l) )); then
  # 3. Send
  vultisig send ethereum 0xRecipient... 0.1 --password "$VAULT_PASSWORD" -y -o json
fi
```

### Workflow: Cross-Chain Swap

```bash
# 1. Get quote
QUOTE=$(vultisig swap-quote ethereum bitcoin 0.1 -o json)
echo "Expected output: $(echo $QUOTE | jq -r '.expectedOutput') BTC"

# 2. Execute swap
vultisig swap ethereum bitcoin 0.1 --password "$VAULT_PASSWORD" -y -o json
```

### Workflow: Backup Vault

```bash
# Export encrypted backup
vultisig export /backups/ --password "$VAULT_PASSWORD"
```

## Environment Variables

```bash
VULTISIG_VAULT="my-wallet"       # Pre-select vault by name/ID
VAULT_PASSWORD="password"         # Vault password (use with caution)
VULTISIG_SILENT=1                # Suppress spinners/info messages
VULTISIG_NO_COLOR=1              # Disable colored output
```

## Error Handling

| Exit Code | Meaning |
|-----------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid usage |
| 4 | Authentication error |
| 5 | Network error |
| 6 | Vault error |
| 7 | Transaction error |

See [references/errors.md](references/errors.md) for common errors and solutions.

## Supported Chains

36+ blockchains including:
- **EVM**: Ethereum, Polygon, Arbitrum, Optimism, BSC, Base, Avalanche, Blast, Cronos, ZkSync, Hyperliquid, Mantle, Sei
- **UTXO**: Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Dash, Zcash
- **Cosmos**: Cosmos, THORChain, MayaChain, Osmosis, Dydx, Kujira, Terra, Noble, Akash
- **Other**: Solana, Sui, Polkadot, TON, Ripple, Tron, Cardano

See [references/chains.md](references/chains.md) for full list with details.

## Resources

- [GitHub Repository](https://github.com/vultisig/vultisig-sdk)
- [Full CLI Documentation](https://github.com/vultisig/vultisig-sdk/blob/main/clients/cli/README.md)
- [SDK Documentation](https://github.com/vultisig/vultisig-sdk/blob/main/docs/SDK-USERS-GUIDE.md)

```

### vultisig-sdk/SKILL.md

```markdown
---
name: vultisig-sdk
description: TypeScript SDK for MPC wallet integration across 36+ blockchains. Create wallets, import from seedphrase, sign transactions, execute swaps, scan for security threats, and more. Supports Bitcoin, Ethereum, Solana, and 33+ other chains with threshold signing security.
version: 1.0.0
author: Vultisig
repository: https://github.com/vultisig/vultisig-sdk
metadata:
  openclaw:
    emoji: "🛡️"
    homepage: https://github.com/vultisig/vultisig-sdk
    requires:
      bins:
        - node
        - npm
    install:
      npm: "@vultisig/sdk"
tags:
  - crypto
  - wallet
  - mpc
  - typescript
  - sdk
  - defi
  - bitcoin
  - ethereum
  - solana
---

# Vultisig SDK

TypeScript SDK for Vultisig MPC wallet operations. See the [router skill](../SKILL.md) for an overview of MPC benefits and to choose between CLI and SDK.

## Installation

```bash
npm install @vultisig/sdk
# or
yarn add @vultisig/sdk
```

**Requirements:**
- Node.js 20+
- TypeScript (recommended)
- Platforms: Node.js, Browser (with WASM), React Native, Electron

## Quick Start

```typescript
import { Vultisig, Chain } from '@vultisig/sdk'

// Initialize SDK
const sdk = new Vultisig({
  onPasswordRequired: async (vaultId, vaultName) => {
    return process.env.VAULT_PASSWORD || ''
  },
  passwordCache: { defaultTTL: 300000 } // 5 minutes
})
await sdk.initialize()

// Create a FastVault
const vaultId = await sdk.createFastVault({
  name: 'agent-wallet',
  email: '[email protected]',
  password: 'SecurePassword123!'
})

// Verify with email code
const vault = await sdk.verifyVault(vaultId, 'verification-code')

// Get address
const address = await vault.address(Chain.Ethereum)
console.log('ETH address:', address)

// Check balance
const balance = await vault.balance(Chain.Ethereum)
console.log(`Balance: ${balance.amount} ${balance.symbol}`)

// Clean up
sdk.dispose()
```

## Vault Types

| Type | Threshold | Signing | Best For |
|------|-----------|---------|----------|
| **FastVault** | 2-of-2 (device + server) | Instant | AI agents, automation |
| **SecureVault** | N-of-M (configurable) | Multi-device coordination | Teams, high security |

**For AI agents, FastVault is recommended** - instant signing without coordination.

## Core Classes

### Vultisig (Main Entry Point)

```typescript
const sdk = new Vultisig({
  storage?: Storage,                    // Default: FileStorage (Node) / BrowserStorage
  defaultChains?: Chain[],              // Chains for new vaults
  defaultCurrency?: string,             // Fiat currency (default: 'USD')
  onPasswordRequired?: (id, name) => Promise<string>,
  passwordCache?: { defaultTTL: number }
})

// Lifecycle
await sdk.initialize()
sdk.dispose()

// Vault creation
const vaultId = await sdk.createFastVault({ name, email, password })
const vault = await sdk.verifyVault(vaultId, code)
const { vault } = await sdk.createSecureVault({ name, devices, threshold })

// Vault management
const vaults = await sdk.listVaults()
const vault = await sdk.getActiveVault()
await sdk.setActiveVault(vault)
await sdk.deleteVault(vault)

// Import/Export
const vault = await sdk.importVault(vultContent, password)
const isEncrypted = sdk.isVaultEncrypted(vultContent)

// Seedphrase
await sdk.validateSeedphrase(mnemonic)
await sdk.discoverChainsFromSeedphrase(mnemonic, chains?, onProgress?)
await sdk.createFastVaultFromSeedphrase({ mnemonic, name, email, password })
```

### VaultBase (Shared Vault Methods)

```typescript
// Properties
vault.id: string
vault.name: string
vault.type: 'fast' | 'secure'
vault.isEncrypted: boolean

// Addresses
const address = await vault.address(Chain.Bitcoin)
const addresses = await vault.addresses([Chain.Bitcoin, Chain.Ethereum])

// Balances
const balance = await vault.balance(Chain.Ethereum)
const balances = await vault.balances()  // All chains
await vault.updateBalance(Chain.Ethereum)  // Force refresh

// Transactions
const payload = await vault.prepareSendTx({ coin, receiver, amount })
const signature = await vault.sign(payload)
const txHash = await vault.broadcastTx({ chain, keysignPayload: payload, signature })

// Swaps
const quote = await vault.getSwapQuote({ fromCoin, toCoin, amount })
const { keysignPayload } = await vault.prepareSwapTx({ fromCoin, toCoin, amount, swapQuote })

// Management
await vault.addChain(Chain.Solana)
await vault.removeChain(Chain.Litecoin)
await vault.rename('New Name')
const { filename, data } = await vault.export(password)
```

### Chain Enum

```typescript
import { Chain } from '@vultisig/sdk'

// EVM
Chain.Ethereum, Chain.Polygon, Chain.BSC, Chain.Arbitrum, Chain.Optimism,
Chain.Base, Chain.Avalanche, Chain.Blast, Chain.CronosChain, Chain.ZkSync,
Chain.Hyperliquid, Chain.Mantle, Chain.Sei

// UTXO
Chain.Bitcoin, Chain.Litecoin, Chain.Dogecoin, Chain.BitcoinCash,
Chain.Dash, Chain.Zcash

// Cosmos
Chain.Cosmos, Chain.THORChain, Chain.MayaChain, Chain.Osmosis, Chain.Dydx,
Chain.Kujira, Chain.Terra, Chain.TerraClassic, Chain.Noble, Chain.Akash

// Other
Chain.Solana, Chain.Sui, Chain.Polkadot, Chain.Ton, Chain.Ripple,
Chain.Tron, Chain.Cardano
```

## All Capabilities

For full details and code examples, see the [SDK Users Guide](../../docs/SDK-USERS-GUIDE.md).

| Capability | Description | Guide Section |
|-----------|-------------|---------------|
| Vault Creation | FastVault (2-of-2) and SecureVault (N-of-M) | [Vault Management](../../docs/SDK-USERS-GUIDE.md#vault-management) |
| Seedphrase Import | Validate mnemonics, discover chains, create vaults from seedphrase | [Seedphrase](../../docs/SDK-USERS-GUIDE.md#creating-vaults-from-seedphrase) |
| Send Transactions | Prepare, sign, broadcast for all 36+ chains | [Essential Operations](../../docs/SDK-USERS-GUIDE.md#essential-operations) |
| Token Swaps | Cross-chain (THORChain), same-chain (1inch, LiFi), ERC-20 approval handling | [Token Swaps](../../docs/SDK-USERS-GUIDE.md#token-swaps) |
| Sign Arbitrary Bytes | Custom tx construction with signBytes and broadcastRawTx | [Signing](../../docs/SDK-USERS-GUIDE.md#signing-arbitrary-bytes) |
| Cosmos Signing | SignAmino and SignDirect for Cosmos dApps | [Cosmos Signing](../../docs/SDK-USERS-GUIDE.md#cosmos-signing-signamino--signdirect) |
| Gas Estimation | Get gas info per chain via `vault.gas(chain)` | [Gas Estimation](../../docs/SDK-USERS-GUIDE.md#gas-estimation) |
| Token Discovery | Look up known tokens, discover at address, resolve metadata | [Token Registry](../../docs/SDK-USERS-GUIDE.md#token-registry--discovery) |
| Price Feeds | CoinGecko token prices via `vault.getPrice()` | [Price Feeds](../../docs/SDK-USERS-GUIDE.md#price-feeds) |
| Security Scanning | Site scanning, transaction validation, transaction simulation | [Security](../../docs/SDK-USERS-GUIDE.md#security-scanning) |
| Fiat On-Ramp | Buy crypto via Banxa integration | [Fiat On-Ramp](../../docs/SDK-USERS-GUIDE.md#fiat-on-ramp-banxa) |
| Portfolio Value | Fiat valuations across all chains | [Portfolio](../../docs/SDK-USERS-GUIDE.md#portfolio-value) |
| Password Management | Callbacks, caching, manual lock/unlock | [Password Management](../../docs/SDK-USERS-GUIDE.md#password-management) |
| Event System | Reactive updates for balances, signing, chains, tokens | [Events](../../docs/SDK-USERS-GUIDE.md#event-system) |
| Caching | Address, balance, password, portfolio caching with configurable TTLs | [Caching](../../docs/SDK-USERS-GUIDE.md#caching-system) |
| Error Handling | Typed VaultError with error codes (PasswordRequired, InsufficientBalance, etc.) | [Quick Reference](../../docs/SDK-USERS-GUIDE.md#quick-reference) |
| Stateless Mode | MemoryStorage for serverless, testing, one-off operations | [Stateless Usage](../../docs/SDK-USERS-GUIDE.md#stateless-usage) |
| Multi-Platform | Node.js, Browser (WASM), React Native, Electron | [Platform Notes](../../docs/SDK-USERS-GUIDE.md#platform-notes) |
| Storage Options | FileStorage, BrowserStorage, MemoryStorage, or custom | [Configuration](../../docs/SDK-USERS-GUIDE.md#configuration) |

## Supported Chains

36+ blockchains:
- **EVM (13)**: Ethereum, Polygon, BSC, Arbitrum, Optimism, Base, Avalanche, Blast, Cronos, ZkSync, Hyperliquid, Mantle, Sei
- **UTXO (6)**: Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Dash, Zcash
- **Cosmos (10)**: Cosmos, THORChain, MayaChain, Osmosis, Dydx, Kujira, Terra, Terra Classic, Noble, Akash
- **Other (7)**: Solana, Sui, Polkadot, TON, Ripple, Tron, Cardano

## Resources

- [SDK Users Guide](../../docs/SDK-USERS-GUIDE.md) - Complete documentation with examples
- [GitHub Repository](https://github.com/vultisig/vultisig-sdk)

```