EigenSwarm Protocol

What Is EigenSwarm

EigenSwarm is a protocol for deploying autonomous market making agents — called Eigens — on clanker tokens. Each Eigen operates independently: it buys, sells, rebalances, and takes profit based on configurable parameters, generating organic trading volume while capturing LP interface fees.

The protocol runs on Base (chain ID 8453) and integrates with Uniswap V3/V4 for trade execution, Clanker for token deployment, and the x402 machine-to-machine payment protocol for programmatic access.

Key Concepts

Architecture

The protocol has three layers:

1. Smart Contract Layer — EigenVault holds funds, enforces ownership, and gates keeper execution. Deployed on Base with OpenZeppelin Ownable and ReentrancyGuard.
2. Keeper Layer — Off-chain agents that read market data, compute optimal trades, and submit transactions through the EigenVault's executeBuy and returnEth functions.
3. Interface Layer — The web dashboard for deploying, monitoring, and controlling Eigens, plus the API/SDK for programmatic access.

Getting Started

Connect Wallet

EigenSwarm requires a wallet connected to Base (chain ID 8453). The app supports any EVM wallet through ConnectKit — MetaMask, Coinbase Wallet, WalletConnect, and others. If you're on the wrong chain, the app will prompt you to switch.

Deploy on Existing Token

Navigate to Deploy in the app to attach an Eigen to any existing clanker token on Base. The process follows four steps:

1. Select Token — Enter the token's contract address on Base. The app verifies it's a valid ERC-20 with an active Uniswap pool.
2. Choose Agent Class — Pick from Lite, Core, Pro, or Ultra based on your volume and risk goals.
3. Configure Parameters — Set volume target, trade frequency, order sizes, spread width, risk limits, and wallet count.
4. Fund & Deploy — Deposit ETH (at or above the class minimum) and confirm the on-chain transaction. Your Eigen begins trading within seconds.

Launch New Token + Eigen

Navigate to Launch to deploy a new clanker token and attach a market making agent in one flow. This has three phases:

1. Deploy Token — Provide a name, symbol, image URL, and description (280 chars max). Advanced options include fee type (static 1% or dynamic 0.25–5%), MEV protection (2-block snipe delay), and optional dev buy.
2. Create Eigen On-Chain — The EigenVault entry is created and funded with your ETH deposit.
3. Register Configuration — Agent parameters are submitted to the keeper network and execution begins.

Agent Classes

Four tiers of autonomous intelligence, each tuned for different volume targets and risk profiles. All classes support the full parameter set — they differ in capacity, minimum deposit, and protocol fee rate.

Lite

Core

Pro

Ultra

Protocol Mechanics

EigenVault Contract

The EigenVault is the core smart contract that holds all user deposits. It is non-custodial — you always retain withdrawal rights regardless of Eigen status or keeper availability.

Each Eigen has an isolated balance tracked by a bytes32 identifier. The contract enforces that:

• Only the Eigen owner can deposit to or withdraw from their Eigen
• Only the authorized keeper can execute trades
• Trade execution can only pull from the Eigen's own balance
• All withdrawals use ReentrancyGuard protection
• Protocol fee collection requires owner authorization

Deposits & Withdrawals

Deposits: Send ETH when calling createEigen(eigenId) for initial funding, or deposit(eigenId) to add more later. Funds are immediately available for the keeper to execute trades.

Withdrawals: Call withdraw(eigenId, amount) to pull ETH back to your wallet at any time. Partial withdrawals are supported. If you want to close the agent entirely, use terminate(eigenId) — this sells any remaining token inventory and returns all ETH.

Trade Execution

The keeper network monitors market conditions and executes trades through the EigenVault:

1. Buy execution — Keeper calls executeBuy(eigenId, router, swapData, ethAmount), pulling ETH from the Eigen's balance and routing it through the Uniswap swap router.
2. Sell execution — Keeper sells tokens on Uniswap and returns ETH proceeds via returnEth(eigenId).
3. Rebalancing — When inventory drifts past the rebalanceThreshold, the keeper adjusts the ETH/token ratio.
4. Profit-taking — When unrealized gains exceed the profitTarget, the keeper sells a portion to lock in returns.

Trades are distributed across multiple wallets (configurable, 1–10) to create natural-looking market activity and reduce single-point execution risk.

Fee Model

EigenSwarm has two revenue streams:

Configuration

Execution Parameters

Risk Parameters

Wallet Distribution

The walletCount parameter (1–10) controls how many execution wallets the keeper uses for your Eigen. Multi-wallet execution distributes trades across separate addresses, producing more organic-looking market activity and reducing the concentration of trade flow from a single address.

Fleet Dashboard

Portfolio Overview

The Fleet page (/app) shows all your active Eigens with aggregate portfolio statistics:

Eigen Detail View

Click any Eigen to see its dedicated dashboard with price charts (1h/4h/1d/7d/30d ranges), cumulative P&L history, volume-by-hour distribution, trade distribution breakdown, full performance metrics, inventory composition bar, live activity feed, and parameter configuration.

Key metrics tracked per Eigen: entry price, current price, unrealized and realized P&L, net return (realized + unrealized + LP fees - protocol fees), win rate, total volume, trade count, LP fees earned/claimed, protocol fee accrued, and remaining ETH balance.

Controls & Actions

API Reference

Overview

The EigenSwarm API allows AI agents and bots to programmatically purchase trading volume on any clanker token. Payments use the x402 protocol — a machine-to-machine payment standard where the server responds with HTTP 402 and payment instructions, the client pays on-chain, then retries with proof.

https://api.eigenswarm.xyz

Pricing

GET /api/pricing

Response:
{
  "packages": [
    { "id": "starter",  "ethVolume": 1,   "priceUSDC": 10,  "duration": "24h" },
    { "id": "growth",   "ethVolume": 5,   "priceUSDC": 40,  "duration": "24h" },
    { "id": "pro",      "ethVolume": 20,  "priceUSDC": 120, "duration": "24h" },
    { "id": "whale",    "ethVolume": 100, "priceUSDC": 500, "duration": "24h" }
  ],
  "paymentToken": "MON",
  "paymentChain": 10143,
  "paymentAddress": "0x..."
}

Buy Volume (x402)

POST /api/agents/buy-volume
Content-Type: application/json

{
  "tokenAddress": "0x...",
  "packageId": "growth",
  "tokenSymbol": "TOKEN",
  "tokenName": "My Token"
}

// Success Response (201):
{
  "success": true,
  "eigenId": "0x...",
  "package": "growth",
  "ethVolume": 5,
  "duration": "24h",
  "status": "active",
  "expiresAt": "2025-01-02T00:00:00Z"
}

Monitor Eigen

// Fetch eigen status and metrics
GET /api/eigens/{eigenId}

// Fetch trade history
GET /api/eigens/{eigenId}/trades

// API health check
GET /api/health

// Protocol-wide statistics
GET /api/stats

x402 Payment Flow

The x402 protocol enables machine-to-machine payments without API keys or accounts. Here's the complete flow:

1. Request — POST to /api/agents/buy-volume with token address and package ID.
2. 402 Response — Server responds with X-PAYMENT-REQUIRED header containing: USDC amount, recipient address, and token contract (USDC on Base).
3. On-Chain Payment — Execute the USDC transfer on Base. Confirmation takes ~2 seconds.
4. Retry with Proof — Resend the same POST request with X-PAYMENT header containing the transaction hash.
5. Activation — Server verifies the payment, creates the Eigen, and returns 201 with the eigen ID and status.

# AI agents can discover EigenSwarm's API by fetching:
curl -s https://www.eigenswarm.xyz/skill.md

SDK Reference

Installation

npm install @eigenswarm/sdk viem

Quick Start

import { EigenSwarm } from '@eigenswarm/sdk';

const swarm = new EigenSwarm({ wallet });

// Deploy on existing token
const eigen = await swarm.deploy({
  token: '0x...',
  class: 'operator',
  params: {
    volumeTarget: 5,
    tradeFrequency: 12,
    orderSizeMin: 0.005,
    orderSizeMax: 0.05,
    spreadWidth: 1,
    profitTarget: 15,
    stopLoss: 10,
    rebalanceThreshold: 0.5,
    walletCount: 3,
  },
  deposit: 0.5, // ETH
});

console.log(eigen.id);     // "ES-a1b2"
console.log(eigen.status);  // "active"

Types

type AgentClass = 'sentinel' | 'operator' | 'architect' | 'sovereign';
type EigenStatus = 'active' | 'suspended' | 'terminated';
type TradeType = 'buy' | 'sell' | 'rebalance' | 'profit_take' | 'fee_claim';

interface Eigen {
  id: string;                    // "ES-XXXX"
  ownerAddress: string;
  tokenAddress: string;
  tokenSymbol: string;
  tokenName: string;
  poolAddress: string;
  class: AgentClass;
  status: EigenStatus;
  vaultEigenId: string;          // bytes32 on-chain ID

  // Parameters
  volumeTarget: number;
  tradeFrequency: number;
  orderSizeMin: number;
  orderSizeMax: number;
  spreadWidth: number;
  profitTarget: number;
  stopLoss: number;
  rebalanceThreshold: number;
  walletCount: number;

  // Balances
  ethDeposited: number;
  ethBalance: number;
  tokenBalance: number;

  // Metrics
  entryPrice: number;
  currentPrice: number;
  volumeGenerated: number;
  tradesExecuted: number;
  realizedPnl: number;
  unrealizedPnl: number;
  lpFeesEarned: number;
  lpFeesClaimed: number;
  protocolFeeAccrued: number;
  winRate: number;

  createdAt: string;
  terminatedAt: string | null;
  updatedAt: string;
}

interface Trade {
  id: number;
  eigenId: string;
  type: TradeType;
  ethAmount: number;
  tokenAmount: number;
  price: number;
  txHash: string;
  pnlImpact: number;
  gasCost: number;
  createdAt: string;
}

Utilities

import {
  truncateAddress,     // "0x1234...abcd"
  eigenIdToBytes32,    // ES-XXXX → keccak256 hash
  isValidEigenId,      // validates /^ES-[0-9a-f]{4}$/
  formatEth,           // format ETH values (4 decimals)
  formatUsd,           // format USD with Intl.NumberFormat
  formatPercent,       // "+12.5%" with sign
  formatCompact,       // 1.2M, 34.5K
  formatDuration,      // ms → "2d 5h"
  formatRuntime,       // ISO → time since
  formatTimestamp,     // ISO → HH:MM:SS
  pnlColor,           // value → 'positive' | 'negative' | 'neutral'
} from '@eigenswarm/shared';

Smart Contracts

Addresses

All contracts are deployed on Base (chain ID 8453).

Clanker Factory Contracts

EigenVault ABI

Core functions of the EigenVault contract:

// Create a new Eigen and deposit initial ETH
function createEigen(bytes32 eigenId) external payable

// Add more ETH to an existing Eigen
function deposit(bytes32 eigenId) external payable

// Withdraw ETH (partial or full)
function withdraw(bytes32 eigenId, uint256 amount) external

// Permanently close Eigen, sell inventory, return ETH
function terminate(bytes32 eigenId) external

// Pause / resume keeper execution
function suspend(bytes32 eigenId) external
function resume(bytes32 eigenId) external

// Keeper-only: execute a buy swap through Uniswap
function executeBuy(
  bytes32 eigenId,
  address router,
  bytes calldata swapData,
  uint256 ethAmount
) external

// Keeper-only: return ETH from sell proceeds
function returnEth(bytes32 eigenId) external payable

// Owner-only: collect protocol fees
function collectFee(bytes32 eigenId, uint256 amount) external

// View: query Eigen ownership, status, balance
function getEigenInfo(bytes32 eigenId) external view
  returns (address owner, bool active, uint256 balance)

Security Model

• Non-custodial — Users always retain withdrawal rights. No admin function can freeze or redirect user funds.
• ReentrancyGuard — All withdrawal and termination functions use OpenZeppelin's ReentrancyGuard to prevent reentrancy attacks.
• Ownable — Admin functions (keeper management, fee collection) are restricted to the contract owner.
• Keeper isolation — The keeper can only execute swaps using funds within the Eigen's balance. It cannot withdraw, transfer, or access other Eigens' funds.
• Balance isolation — Each Eigen has an independent balance. One Eigen's losses or compromised parameters cannot affect another.

Frequently Asked Questions