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

Always preview before executing - Use preview-swap to see expected outcomes
Start with small percentages - Test with 10-25% before going to 100%
Monitor transactions - Use check-transaction --wait to ensure completion
Check holdings first - Know what tokens are available before swapping
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);

swarm-vault-manager-trading

Swarm Vault Manager Trading Skill

Overview

Key Concepts

Authentication

Available Commands

1. Check Holdings

2. Preview Swap

3. Execute Swap

4. Execute Transaction

5. Check Transaction

Token Addresses

Base Mainnet (Chain ID: 8453)

Base Sepolia Testnet (Chain ID: 84532)

Template Placeholders

Placeholder Examples

Transaction Template Structure

ABI Mode (Recommended)

Raw Calldata Mode (Advanced)

Common Operations

Swap USDC to WETH

Swap ETH to USDC

Check What Tokens a Swarm Holds

Error Handling

Best Practices

Platform Fee

SDK Reference