API docs by Redocly

Swarm Vault API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/swarm-vault/swarm-vault License: MIT

Swarm Vault API enables managers to execute transactions on behalf of multiple users on Base.

SDK vs Direct API

For JavaScript/TypeScript projects, use the official SDK:

npm install @swarmvault/sdk

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

const client = new SwarmVaultClient({
  apiKey: 'svk_your_api_key_here',
});

const result = await client.executeSwap('swarm-id', {
  sellToken: BASE_MAINNET_TOKENS.USDC,
  buyToken: BASE_MAINNET_TOKENS.WETH,
  sellPercentage: 50,
});

const tx = await client.waitForTransaction(result.transactionId);

See the SDK README for full documentation.

Option 2: Direct API (Any Language)

Use the REST API directly by following this documentation.

Authentication

All authenticated endpoints require an API key in the Authorization header:

Authorization: Bearer svk_xxxxx...

Getting an API Key

  1. Log in to the Swarm Vault web app at swarmvault.xyz
  2. Go to Settings
  3. Click Generate API Key
  4. Copy the API key immediately - it's only shown once!

Important: Store your API key securely. If you lose it, you'll need to generate a new one (which revokes the old key).

Using Your API Key

Include the API key in the Authorization header for all requests:

const API_KEY = 'svk_your_api_key_here';

const response = await fetch('https://api.swarmvault.xyz/api/swarms', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

API Key Management

  • Regenerate: Generate a new key at any time from Settings. This automatically revokes the old key.
  • Revoke: Delete your API key from Settings if you no longer need programmatic access.

Manager Operations

Managers can execute swaps across all swarm member wallets:

  1. Get holdings: GET /api/swarms/:id/holdings - See aggregate token balances
  2. Preview swap: POST /api/swarms/:id/swap/preview - Get expected outcomes
  3. Execute swap: POST /api/swarms/:id/swap/execute - Execute the swap
  4. Check status: GET /api/transactions/:id - Poll for completion

Template Placeholders

When creating custom transactions, use these placeholders:

Placeholder Description
{{walletAddress}} Agent wallet address
{{ethBalance}} Current ETH balance (wei)
{{tokenBalance:0xAddr}} ERC20 token balance
{{percentage:ethBalance:50}} 50% of ETH balance
{{percentage:tokenBalance:0xAddr:100}} 100% of token balance
{{blockTimestamp}} Current block timestamp
{{deadline:300}} Timestamp + N seconds
{{slippage:amount:5}} Amount minus 5%

Authentication

API key management for programmatic access

Verify API key and get user info

Verify your API key is valid and retrieve your user profile. Use this endpoint to test your API key is working correctly.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get API key info

Get information about the user's current API key. Returns the key prefix (for identification) and creation date. The full API key is never returned.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Revoke API key

Revoke the current API key. After revocation, the key can no longer be used for authentication. You can generate a new key at any time.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Generate new API key

Generate a new API key for programmatic access to the Swarm Vault API.

IMPORTANT: The full API key is only returned ONCE in this response. Store it securely - you will not be able to retrieve it again.

If you already have an API key, generating a new one will automatically revoke the old key.

Use the API key by including it in the Authorization header: Authorization: Bearer svk_xxxxx...

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Swarms

Swarm creation and management

List all swarms

Get a list of all public swarms. If authenticated, the response includes whether the current user is a manager of each swarm.

Authorizations:
bearerAuthNone

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Create a new swarm

Create a new swarm with the authenticated user as manager. Requires a linked Twitter account for manager verification. A new Lit Protocol PKP is minted for the swarm.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Name of the swarm

description
string <= 500 characters

Description of the swarm

Responses

Request samples

Content type
application/json
{
  • "name": "Alpha Traders",
  • "description": "A swarm for professional traders"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get swarm details

Get detailed information about a specific swarm. Managers see additional details like PKP public key.

Authorizations:
bearerAuthNone
path Parameters
id
required
string <uuid>

Swarm ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get swarm members

Get a list of all active members in the swarm. Manager only - only swarm managers can view members.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Swarm ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get swarm by invite code

Get swarm details using an invite code. This allows users to preview a private swarm before joining.

Authorizations:
bearerAuthNone
path Parameters
inviteCode
required
string

Unique invite code for the swarm

Responses

Update swarm visibility

Toggle whether a swarm is public or private. Manager only.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
isPublic
required
boolean

Responses

Request samples

Content type
application/json
{
  • "isPublic": true
}

Regenerate invite code

Generate a new invite code, invalidating the old one. Manager only.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Memberships

User swarm memberships and agent wallets

Join a swarm

Join a swarm as a member. The client must create the smart wallet and serialize the permission account before calling this endpoint.

Authorizations:
bearerAuth
path Parameters
swarmId
required
string <uuid>

Swarm ID to join

Request Body schema: application/json
required
agentWalletAddress
required
string^0x[a-fA-F0-9]{40}$

The smart wallet address created by the client

sessionKeyApproval
required
string

Serialized permission account for PKP signing

Responses

Request samples

Content type
application/json
{
  • "agentWalletAddress": "string",
  • "sessionKeyApproval": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List user's memberships

Get all active swarm memberships for the authenticated user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get membership details

Get detailed information about a specific membership

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Membership ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Leave a swarm

Leave a swarm membership. The agent wallet remains but swarm managers can no longer execute transactions.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Membership ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get agent wallet balance

Get ETH and token balances for the membership's agent wallet

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Membership ID

query Parameters
refresh
string
Enum: "true" "false"

Force refresh from blockchain (bypasses cache)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Swaps

Token swap operations for swarm managers

Preview swap for all swarm members

Get a preview of what a swap would look like for all swarm members. Returns expected amounts for each member without executing the swap. Manager only - only swarm managers can preview swaps.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Swarm ID

Request Body schema: application/json
required
sellToken
required
string^0x[a-fA-F0-9]{40}$

Token address to sell (use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH)

buyToken
required
string^0x[a-fA-F0-9]{40}$

Token address to buy

sellPercentage
number [ 1 .. 100 ]
Default: 100

Percentage of token balance to sell

slippagePercentage
number [ 0.01 .. 50 ]
Default: 1

Slippage tolerance percentage

Responses

Request samples

Content type
application/json
{
  • "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  • "buyToken": "0x4200000000000000000000000000000000000006",
  • "sellPercentage": 100,
  • "slippagePercentage": 1
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Execute swap for all swarm members

Execute a token swap for all active swarm members. The swap is executed asynchronously - poll the returned transaction ID for status updates. Manager only - only swarm managers can execute swaps.

A platform fee (default 0.5%) is deducted from the buy token amount.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Swarm ID

Request Body schema: application/json
required
sellToken
required
string^0x[a-fA-F0-9]{40}$

Token address to sell

buyToken
required
string^0x[a-fA-F0-9]{40}$

Token address to buy

sellPercentage
number [ 1 .. 100 ]
Default: 100
slippagePercentage
number [ 0.01 .. 50 ]
Default: 1

Responses

Request samples

Content type
application/json
{
  • "sellToken": "string",
  • "buyToken": "string",
  • "sellPercentage": 100,
  • "slippagePercentage": 1
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get aggregate swarm holdings

Get aggregate token holdings across all swarm members. Returns total ETH and token balances with holder counts. Manager only - only swarm managers can view holdings.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Swarm ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Transactions

Custom transaction execution and status tracking

Execute a custom transaction

Execute a custom transaction across all swarm member wallets using a template. Templates support placeholders for wallet addresses, balances, and computed values. Manager only - only swarm managers can execute transactions.

The transaction is executed asynchronously - poll the returned transaction ID for status updates.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Swarm ID

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List swarm transactions

Get a list of all transactions executed for this swarm. Manager only - only swarm managers can view transactions.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Swarm ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get transaction details

Get detailed status and results for a specific transaction. Includes per-member status for tracking progress. Manager only - only swarm managers can view transaction details.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Transaction ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}