TypeScript SDK for Swarm Vault API - execute swaps and transactions on behalf of swarm members
npm install @swarmvault/sdkTypeScript SDK for the Swarm Vault API. Execute swaps and transactions on behalf of your swarm members with a simple, type-safe client.
``bash`
npm install @swarmvault/sdkor
pnpm add @swarmvault/sdkor
yarn add @swarmvault/sdk
`typescript
import { SwarmVaultClient, BASE_MAINNET_TOKENS } from '@swarmvault/sdk';
// Initialize client with your API key
const client = new SwarmVaultClient({
apiKey: 'svk_your_api_key_here',
});
// Get your swarms
const swarms = await client.listSwarms();
const mySwarm = swarms.find(s => s.isManager);
// Check holdings
const holdings = await client.getSwarmHoldings(mySwarm.id);
console.log('ETH Balance:', holdings.ethBalance);
console.log('Tokens:', holdings.tokens);
// Preview a swap
const preview = await client.previewSwap(mySwarm.id, {
sellToken: BASE_MAINNET_TOKENS.USDC,
buyToken: BASE_MAINNET_TOKENS.WETH,
sellPercentage: 50, // Sell 50% of USDC
});
console.log('Expected output:', preview.totalBuyAmount, 'WETH');
// Execute the swap
const result = await client.executeSwap(mySwarm.id, {
sellToken: BASE_MAINNET_TOKENS.USDC,
buyToken: BASE_MAINNET_TOKENS.WETH,
sellPercentage: 50,
});
// Wait for completion
const tx = await client.waitForTransaction(result.transactionId, {
onPoll: (t) => console.log('Status:', t.status),
});
console.log('Swap completed!');
`
Generate an API key from the Swarm Vault settings page. API keys start with svk_.
`typescript`
const client = new SwarmVaultClient({
apiKey: 'svk_your_api_key_here',
});
Alternatively, you can use a JWT token obtained through the SIWE login flow:
`typescript
const client = new SwarmVaultClient({
jwt: 'eyJhbGciOiJIUzI1NiIs...',
});
// Or set it later
client.setJwt(token);
`
`typescript
const client = new SwarmVaultClient({
// API base URL (default: https://api.swarmvault.xyz)
baseUrl: 'https://api.swarmvault.xyz',
// API key for authentication
apiKey: 'svk_...',
// Or JWT token
jwt: 'eyJ...',
// Custom fetch function (optional, for testing)
fetch: customFetch,
});
`
#### getMe()
Get the authenticated user.
`typescript`
const user = await client.getMe();
console.log(user.walletAddress);
console.log(user.twitterUsername);
#### setApiKey(key: string)
Set or update the API key.
`typescript`
client.setApiKey('svk_new_key');
#### setJwt(token: string)
Set or update the JWT token.
`typescript`
client.setJwt('eyJ...');
#### listSwarms()
List all swarms. Returns your management status for authenticated requests.
`typescript`
const swarms = await client.listSwarms();
const managedSwarms = swarms.filter(s => s.isManager);
#### getSwarm(swarmId: string)
Get details of a specific swarm.
`typescript`
const swarm = await client.getSwarm('swarm-id');
console.log(swarm.name, swarm.memberCount);
#### getSwarmMembers(swarmId: string)
Get members of a swarm. Manager only.
`typescript`
const members = await client.getSwarmMembers('swarm-id');
for (const member of members) {
console.log(member.agentWalletAddress, member.status);
}
#### getSwarmHoldings(swarmId: string)
Get aggregate token holdings across all swarm members. Manager only.
`typescript${token.symbol}: ${token.totalBalance} (${token.holderCount} holders)
const holdings = await client.getSwarmHoldings('swarm-id');
console.log('ETH:', holdings.ethBalance);
console.log('Members:', holdings.memberCount);
for (const token of holdings.tokens) {
console.log();`
}
#### previewSwap(swarmId: string, params: SwapPreviewParams)
Preview a swap without executing it. Manager only.
`typescript
const preview = await client.previewSwap('swarm-id', {
sellToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
buyToken: '0x4200000000000000000000000000000000000006', // WETH
sellPercentage: 50, // Sell 50% of balance (default: 100)
slippagePercentage: 1, // 1% slippage (default: 1)
});
console.log('Total sell:', preview.totalSellAmount);
console.log('Total buy:', preview.totalBuyAmount);
console.log('Success:', preview.successCount);
console.log('Errors:', preview.errorCount);
// Per-member breakdown
for (const member of preview.members) {
if (member.error) {
console.log(${member.agentWalletAddress}: Error - ${member.error});${member.agentWalletAddress}: ${member.sellAmount} → ${member.buyAmount}
} else {
console.log();`
}
}
#### executeSwap(swarmId: string, params: SwapExecuteParams)
Execute a swap for all swarm members. Manager only.
A platform fee (default 0.5%) is deducted from the buy token amount.
`typescript
const result = await client.executeSwap('swarm-id', {
sellToken: BASE_MAINNET_TOKENS.USDC,
buyToken: BASE_MAINNET_TOKENS.WETH,
sellPercentage: 50,
slippagePercentage: 1,
});
console.log('Transaction ID:', result.transactionId);
console.log('Members:', result.memberCount);
console.log('Fee:', result.fee?.percentage);
`
#### executeTransaction(swarmId: string, template: TransactionTemplate)
Execute a raw transaction template. Manager only. For swaps, prefer executeSwap.
`typescript
// ABI mode
const result = await client.executeTransaction('swarm-id', {
mode: 'abi',
contractAddress: '0x...',
abi: [{ name: 'transfer', type: 'function', ... }],
functionName: 'transfer',
args: ['0xRecipient', '{{percentage:tokenBalance:0x...:50}}'],
value: '0',
});
// Raw calldata mode
const result = await client.executeTransaction('swarm-id', {
mode: 'raw',
contractAddress: '0x...',
data: '0xa9059cbb...',
value: '0',
});
`
#### listTransactions(swarmId: string)
List all transactions for a swarm.
`typescript`
const transactions = await client.listTransactions('swarm-id');
for (const tx of transactions) {
console.log(tx.id, tx.status, tx.createdAt);
}
#### getTransaction(transactionId: string)
Get transaction details including per-member status.
`typescript${target.membership?.agentWalletAddress}: ${target.status}
const tx = await client.getTransaction('tx-id');
console.log('Status:', tx.status);
for (const target of tx.targets || []) {
console.log();`
}
#### waitForTransaction(transactionId: string, options?: WaitForTransactionOptions)
Wait for a transaction to complete.
`typescriptProgress: ${confirmed}/${total}
const tx = await client.waitForTransaction('tx-id', {
timeoutMs: 300000, // 5 minutes (default)
pollIntervalMs: 3000, // 3 seconds (default)
onPoll: (transaction) => {
const confirmed = transaction.targets?.filter(t => t.status === 'CONFIRMED').length ?? 0;
const total = transaction.targets?.length ?? 0;
console.log();
},
});
console.log('Final status:', tx.status);
`
The SDK exports common token addresses for convenience:
`typescript
import {
NATIVE_ETH_ADDRESS,
BASE_MAINNET_TOKENS,
BASE_SEPOLIA_TOKENS
} from '@swarmvault/sdk';
// Native ETH (for swaps)
const ethAddress = NATIVE_ETH_ADDRESS;
// => '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
// Base Mainnet tokens
BASE_MAINNET_TOKENS.USDC // => '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
BASE_MAINNET_TOKENS.WETH // => '0x4200000000000000000000000000000000000006'
BASE_MAINNET_TOKENS.DAI // => '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb'
BASE_MAINNET_TOKENS.USDbC // => '0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA'
BASE_MAINNET_TOKENS.cbETH // => '0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22'
// Base Sepolia tokens (testnet)
BASE_SEPOLIA_TOKENS.USDC // => '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
BASE_SEPOLIA_TOKENS.WETH // => '0x4200000000000000000000000000000000000006'
`
The SDK throws SwarmVaultError for API errors:
`typescript
import { SwarmVaultClient, SwarmVaultError } from '@swarmvault/sdk';
try {
const holdings = await client.getSwarmHoldings('swarm-id');
} catch (error) {
if (error instanceof SwarmVaultError) {
console.error('Message:', error.message);
console.error('Error Code:', error.errorCode);
console.error('Status Code:', error.statusCode);
console.error('Details:', error.details);
}
}
`
| Code | Description |
|------|-------------|
| AUTH_001 | Unauthorized - missing or invalid authentication |AUTH_002
| | Invalid token |RES_003
| | Swarm not found |PERM_002
| | Not a manager of this swarm |TX_001
| | Transaction failed |TX_003
| | Insufficient balance |
When using executeTransaction, you can use placeholders that get resolved per-member:
| Placeholder | Description | Example |
|-------------|-------------|---------|
| {{walletAddress}} | Agent wallet address | 0x1234... |{{ethBalance}}
| | ETH balance (wei) | 1000000000000000000 |{{tokenBalance:0xAddr}}
| | Token balance | 500000000 |{{percentage:ethBalance:50}}
| | 50% of ETH | 500000000000000000 |{{percentage:tokenBalance:0xAddr:100}}
| | 100% of token | 500000000 |{{blockTimestamp}}
| | Current timestamp | 1704567890 |{{deadline:300}}
| | Timestamp + 300s | 1704568190 |{{slippage:amount:5}}
| | Amount - 5% | 950000000 |
See the examples directory for complete working examples:
- check-holdings.ts - View holdings across all managed swarmsswap-usdc-to-weth.ts
- - Preview and execute a swap
The SDK is fully typed. Import types as needed:
`typescript``
import type {
Swarm,
SwarmMember,
SwarmHoldings,
Transaction,
TransactionTarget,
SwapPreviewResult,
SwapExecuteResult,
SwarmVaultClientOptions,
} from '@swarmvault/sdk';
- Node.js 18+ (for native fetch) or provide a custom fetch implementation
- TypeScript 4.7+ (optional, for type checking)
MIT