Swarm Vault Manager Trading Skill

This skill enables you to execute swaps and transactions on behalf of Swarm Vault swarm members. You are acting as a manager's AI trading assistant.

Overview

Swarm Vault is a platform where managers create "swarms" - groups of users who deposit funds into smart wallets. As a manager, you can execute transactions across all swarm member wallets simultaneously.

Key Concepts

• Swarm: A group managed by you containing multiple users
• Agent Wallet: Each user's smart wallet within a swarm (ZeroDev Kernel wallet)
• Holdings: Aggregate token balances across all swarm members
• Swap: Exchange one token for another across all member wallets
• Transaction: Execute arbitrary smart contract calls across all member wallets

Authentication

Before using this skill, ensure the environment is configured:

export SWARM_VAULT_API_KEY="svk_your_api_key_here"
export SWARM_VAULT_API_URL="https://api.swarmvault.xyz"  # Optional, defaults to production

Get your API key from the Swarm Vault settings page at https://swarmvault.xyz/settings

Available Commands

1. Check Holdings

View aggregate token holdings across all swarm members.

pnpm check-holdings [swarmId] [--members]

Arguments:

• swarmId: Optional - if not provided, lists all swarms you manage
• --members: Optional - show per-member balances with membership IDs

Output: JSON with ETH balance, token balances, member count, and common tokens. When using --members, also includes per-member balance breakdown.

Example - view all member balances:

pnpm check-holdings abc-123 --members

This will output each member's:

• Membership ID (use with --members flag on swap commands for targeted swaps)
• Agent wallet address
• User wallet address
• ETH balance
• Token balances

2. Preview Swap

Preview a swap without executing it. Always preview before executing!

pnpm preview-swap <swarmId> <sellToken> <buyToken> [sellPercentage] [slippagePercentage] [--members id1,id2,...]

Arguments:

• swarmId: The swarm ID (UUID)
• sellToken: Token address to sell (or symbol like "USDC", "WETH", "ETH")
• buyToken: Token address to buy (or symbol)
• sellPercentage: Percentage of balance to sell (1-100, default: 100)
• slippagePercentage: Slippage tolerance (default: 1)
• --members: Optional comma-separated list of membership IDs to include (defaults to all active members)

Output: Per-member breakdown showing sell amounts, expected buy amounts, and any errors.

3. Execute Swap

Execute a swap across swarm member wallets.

pnpm execute-swap <swarmId> <sellToken> <buyToken> [sellPercentage] [slippagePercentage] [--members id1,id2,...]

Arguments:

• Same as preview-swap, including optional --members flag to target specific members

Output: Transaction ID that can be monitored with check-transaction.

Example - swap for specific members only:

pnpm execute-swap abc-123 USDC WETH 50 1 --members member-id-1,member-id-2

4. Execute Transaction

Execute a raw transaction template with placeholder support.

pnpm execute-transaction <swarmId> <templateJsonFile>

The template JSON file should contain an ABI-mode or raw-mode transaction template.

5. Check Transaction

Monitor a transaction's status.

pnpm check-transaction <transactionId> [--wait]

Flags:

• --wait: Poll until transaction completes (default: just check current status)

---

Token Addresses

Base Mainnet (Chain ID: 8453)

Symbol	Address
ETH (Native)	0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
WETH	0x4200000000000000000000000000000000000006
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
DAI	0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb
USDbC	0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA
cbETH	0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22

Base Sepolia Testnet (Chain ID: 84532)

Symbol	Address
ETH (Native)	0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
WETH	0x4200000000000000000000000000000000000006
USDC	0x036CbD53842c5426634e7929541eC2318f3dCF7e

---

Template Placeholders

When constructing raw transactions, use these placeholders that get resolved per-member:

Placeholder	Description	Example Output
{{walletAddress}}	Agent wallet address	0x1234...abcd
{{ethBalance}}	Current ETH balance in wei	1000000000000000000
{{tokenBalance:0xAddress}}	ERC20 token balance (raw units)	500000000
{{percentage:ethBalance:50}}	50% of ETH balance	500000000000000000
{{percentage:tokenBalance:0xAddr:100}}	100% of token balance	500000000
{{blockTimestamp}}	Current block timestamp	1704567890
{{deadline:300}}	Timestamp + N seconds (for swap deadlines)	1704568190
{{slippage:amount:5}}	Amount minus 5% (for minAmountOut)	950000000

Placeholder Examples

Transfer 50% of USDC balance:

{
  "mode": "abi",
  "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "abi": [{
    "name": "transfer",
    "type": "function",
    "inputs": [
      { "name": "to", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ],
    "outputs": [{ "type": "bool" }]
  }],
  "functionName": "transfer",
  "args": ["0xRecipientAddress", "{{percentage:tokenBalance:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913:50}}"],
  "value": "0"
}

Approve max tokens for a DEX:

{
  "mode": "abi",
  "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "abi": [{
    "name": "approve",
    "type": "function",
    "inputs": [
      { "name": "spender", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ],
    "outputs": [{ "type": "bool" }]
  }],
  "functionName": "approve",
  "args": ["0xSpenderAddress", "115792089237316195423570985008687907853269984665640564039457584007913129639935"],
  "value": "0"
}

Wrap ETH to WETH (50% of ETH balance):

{
  "mode": "abi",
  "contractAddress": "0x4200000000000000000000000000000000000006",
  "abi": [{
    "name": "deposit",
    "type": "function",
    "inputs": [],
    "outputs": []
  }],
  "functionName": "deposit",
  "args": [],
  "value": "{{percentage:ethBalance:50}}"
}

---

Transaction Template Structure

ABI Mode (Recommended)

Use ABI mode for type-safe contract interactions:

{
  "mode": "abi",
  "contractAddress": "0x...",
  "abi": [{ "name": "functionName", "type": "function", "inputs": [...], "outputs": [...] }],
  "functionName": "functionName",
  "args": ["arg1", "{{placeholder}}", ...],
  "value": "0"
}

Raw Calldata Mode (Advanced)

Use raw mode when you have pre-encoded calldata:

{
  "mode": "raw",
  "contractAddress": "0x...",
  "data": "0xa9059cbb000000000000000000000000...",
  "value": "0"
}

---

Common Operations

Swap USDC to WETH

# Preview first
pnpm preview-swap <swarmId> USDC WETH 50 1

# If preview looks good, execute
pnpm execute-swap <swarmId> USDC WETH 50 1

# Monitor the transaction
pnpm check-transaction <transactionId> --wait

Swap ETH to USDC

pnpm preview-swap <swarmId> ETH USDC 25 1
pnpm execute-swap <swarmId> ETH USDC 25 1

Check What Tokens a Swarm Holds

pnpm check-holdings <swarmId>

---

Error Handling

Common errors and solutions:

Error Code	Meaning	Solution
AUTH_001	Unauthorized	Check API key is set correctly
RES_003	Swarm not found	Verify swarm ID is correct
PERM_002	Not a manager	You can only trade for swarms you manage
TX_003	Insufficient balance	Members don't have enough tokens
EXT_002	0x API error	Try again or check token addresses

---

Best Practices

1. Always preview before executing - Use preview-swap to see expected outcomes
2. Start with small percentages - Test with 10-25% before going to 100%
3. Monitor transactions - Use check-transaction --wait to ensure completion
4. Check holdings first - Know what tokens are available before swapping
5. Use appropriate slippage - 1% is usually fine, increase to 2-3% for volatile tokens

---

Platform Fee

Swarm Vault charges a 0.5% fee on swaps, deducted from the buy token amount. This fee is displayed in swap previews.

---

SDK Reference

This skill uses the @swarmvault/sdk package. For programmatic access beyond these scripts, you can use the SDK directly:

import { SwarmVaultClient, BASE_MAINNET_TOKENS } from '@swarmvault/sdk';

const client = new SwarmVaultClient({
  apiKey: process.env.SWARM_VAULT_API_KEY,
});

// List your swarms
const swarms = await client.listSwarms();

// Get holdings
const holdings = await client.getSwarmHoldings(swarmId);

// Preview swap
const preview = await client.previewSwap(swarmId, {
  sellToken: BASE_MAINNET_TOKENS.USDC,
  buyToken: BASE_MAINNET_TOKENS.WETH,
  sellPercentage: 50,
});

// Execute swap
const result = await client.executeSwap(swarmId, {
  sellToken: BASE_MAINNET_TOKENS.USDC,
  buyToken: BASE_MAINNET_TOKENS.WETH,
  sellPercentage: 50,
});

// Wait for completion
const tx = await client.waitForTransaction(result.transactionId);