token market simulator

A powerful Node.js simulator for modeling token lifecycles, vesting schedules, AMM pool dynamics, and market agent behavior. Perfect for analyzing tokenomics, stress-testing vesting schedules, and simulating market interactions.

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Quick Start
• Usage Examples
• Configuration
• Strategies
• API Reference
• Project Structure
• Contributing
• License

✨ Features

• Vesting Schedules: Model complex vesting with cliffs, linear vesting, and TGE percentages
• AMM Pool Simulation: Simulate automated market maker behavior with slippage and fees
• Market Agents: 500+ configurable agents with 6 built-in trading strategies
• Token Distribution: Model multi-allocation tokenomics (team, community, investors, etc.)
• Random Number Generation: Seeded RNG for reproducible simulations
• ES6 Modules: Modern JavaScript with clean imports

📦 Prerequisites

• Node.js v14+ (recommended v16+)
• npm or yarn

🚀 Installation

1. Clone the repository

   git clone <repo-url>
   cd token-market-simulator

2. Install dependencies

   npm install

⚡ Quick Start

Programmatic Usage

import {
  TokenSimulator,
  AMMPool,
  VestingSchedule,
} from "token-market-simulator";
import { defaultConfig } from "token-market-simulator";

// Create simulator instance
const simulator = new TokenSimulator(defaultConfig);

// Run simulation for 52 weeks
for (let tick = 0; tick < 52; tick++) {
  simulator.onTick();
}

// Get final state
const finalState = simulator.getState();
console.log(finalState);

📚 Usage Examples

Example 1: Custom Tokenomics Configuration

import { TokenSimulator } from "token-market-simulator";

const customConfig = {
  tokenName: "MyToken",
  tokenSymbol: "MTK",
  totalSupply: 100_000_000,
  initialBaseLiquidity: 1_000_000,
  ammFeeBps: 25, // 0.25% fee
  totalTicks: 104, // 2 years (weekly)
  ticksPerMonth: 4.33,
  agentCount: 1000,
  seed: 12345,
  allocations: [
    {
      name: "seed_round",
      percentOfSupply: 0.1,
      tgePercent: 0.05,
      cliffMonths: 6,
      vestingMonths: 24,
    },
    {
      name: "public_sale",
      percentOfSupply: 0.2,
      tgePercent: 1.0,
      cliffMonths: 0,
      vestingMonths: 0,
    },
    {
      name: "team",
      percentOfSupply: 0.25,
      tgePercent: 0.0,
      cliffMonths: 12,
      vestingMonths: 36,
    },
    {
      name: "community",
      percentOfSupply: 0.45,
      tgePercent: 0.1,
      cliffMonths: 0,
      vestingMonths: 12,
    },
  ],
};

const simulator = new TokenSimulator(customConfig);

// Run simulation
for (let i = 0; i < 104; i++) {
  simulator.onTick();
}

console.log("Simulation complete!", simulator.getState());

Example 2: Analyzing Vesting Schedules

import { VestingSchedule, AllocationPlan } from "token-market-simulator";

// Create a vesting schedule
const allocation = new AllocationPlan({
  name: "team_allocation",
  percentOfSupply: 0.2,
  tgePercent: 0.0,
  cliffMonths: 12,
  vestingMonths: 24,
});

const schedule = new VestingSchedule(1_000_000, allocation);

// Check vesting progress at different months
for (let month = 0; month <= 36; month++) {
  const vested = schedule.getVestedAmount(month);
  const unlocked = schedule.getUnlockedAmount(month);
  console.log(`Month ${month}: Vested ${vested}, Unlocked ${unlocked}`);
}

Example 3: Working with AMM Pools

import { AMMPool } from "token-market-simulator";

// Create an AMM pool
const pool = new AMMPool({
  initialTokenReserve: 100_000,
  initialUsdcReserve: 10_000,
  feeBps: 30, // 0.30% fee
});

// Swap tokens
const usdcSpent = 100;
const tokensReceived = pool.swapUsdcForToken(usdcSpent);
console.log(`Spent ${usdcSpent} USDC, received ${tokensReceived} tokens`);

// Check pool state
const state = pool.getPoolState();
console.log("Pool reserves:", state);

Example 4: Creating Market Agents with Strategies

import { Agent } from "token-market-simulator";
import { MovingAverageCrossoverStrategy } from "token-market-simulator/strategies";

// Create an agent with a moving average crossover strategy
const agent = new Agent({
  id: 1,
  balance: 10_000, // USDC balance
  tokenBalance: 100, // Token balance
  strategy: MovingAverageCrossoverStrategy,
  strategyConfig: {
    shortWindow: 5,
    longWindow: 20,
    tradeSize: 0.1, // 10% of balance
  },
});

// Simulate agent trading over time
const priceHistory = [100, 102, 105, 103, 98, 95, 97, 100];
priceHistory.forEach((price, tick) => {
  agent.onTick(price);
});

Example 5: Running a Full Simulation with State Tracking

import { TokenSimulator } from "token-market-simulator";
import { defaultConfig } from "token-market-simulator";

const simulator = new TokenSimulator(defaultConfig);
const stateHistory = [];

// Run simulation and track state changes
for (let tick = 0; tick < 52; tick++) {
  simulator.onTick();

  const state = simulator.getState();
  stateHistory.push({
    tick,
    price: state.price,
    circulatingSupply: state.circulatingSupply,
    poolReserves: state.poolReserves,
    agentActivity: state.agentMetrics,
  });
}

// Analyze results
const finalState = stateHistory[stateHistory.length - 1];
console.log("Final price:", finalState.price);
console.log("Final circulating supply:", finalState.circulatingSupply);

Example 6: Custom Simulation with Different Agent Populations

import {
  TokenSimulator,
  generateAgentPopulation,
} from "token-market-simulator";
import { defaultConfig } from "token-market-simulator";

// Create a custom agent population mix
const agentMix = {
  dca: 0.4, // 40% DCA (Dollar Cost Averaging)
  movingAverageCrossover: 0.2, // 20% Technical traders
  whaleTrader: 0.1, // 10% Whale traders
  gridBot: 0.2, // 20% Grid bots
  marketMaker: 0.1, // 10% Market makers
};

const config = { ...defaultConfig, agentCount: 500 };
const simulator = new TokenSimulator(config);

// Generate custom population based on mix
const population = generateAgentPopulation(
  500,
  agentMix,
  config.totalSupply,
  config.seed,
);

// Run simulation with custom population
simulator.setAgentPopulation(population);

for (let tick = 0; tick < 52; tick++) {
  simulator.onTick();
}

console.log("Simulation complete with custom agent mix!");

⚙️ Configuration

All simulations are configured via a configuration object. See defaultConfig.js for defaults.

Configuration Parameters

{
  // Token details
  tokenName: "String",                // Name of the token
  tokenSymbol: "String",              // Symbol (e.g., BLUST)
  totalSupply: Number,                // Total token supply

  // AMM Pool
  initialBaseLiquidity: Number,       // Initial liquidity in USDC
  ammFeeBps: Number,                  // Fee in basis points (30 = 0.30%)

  // Simulation parameters
  totalTicks: Number,                 // Total simulation duration
  ticksPerMonth: Number,              // Ticks per month (for vesting)
  agentCount: Number,                 // Number of agents
  seed: Number,                       // Random seed for reproducibility

  // Token allocations
  allocations: [
    {
      name: "String",                 // Allocation name
      percentOfSupply: Number,        // Percentage of total supply
      tgePercent: Number,             // Percentage unlocked at TGE (0-1)
      cliffMonths: Number,            // Cliff period in months
      vestingMonths: Number,          // Vesting period in months
    }
  ]
}

🎯 Strategies

The simulator includes 6 built-in trading strategies for agents:

1. MovingAverageCrossover - Technical analysis based on moving average crossovers
2. RSI - Relative Strength Index based strategy
3. DCA - Dollar Cost Averaging (consistent purchases)
4. GridBot - Grid trading strategy with defined price bands
5. WhaleTrader - Large volume trades with impact consideration
6. MarketMaker - Provides liquidity and profits from spreads

🔌 API Reference

TokenSimulator

const simulator = new TokenSimulator(config);

// Core methods
simulator.onTick(); // Advance one simulation step
simulator.getState(); // Get current simulator state
simulator.setAgentPopulation(); // Set custom agent population

VestingSchedule

const schedule = new VestingSchedule(totalAmount, allocation);

// Vesting methods
schedule.getVestedAmount(months); // Get total vested amount
schedule.getUnlockedAmount(months); // Get unlocked amount
schedule.getRemainingLocked(months); // Get remaining locked amount

AMMPool

const pool = new AMMPool(config);

// Pool methods
pool.swapUsdcForToken(usdcAmount); // Swap USDC for tokens
pool.swapTokenForUsdc(tokenAmount); // Swap tokens for USDC
pool.getPoolState(); // Get current pool reserves
pool.getPrice(); // Get current token price

Agent

const agent = new Agent(config);

// Agent methods
agent.onTick(currentPrice); // Process agent action for tick
agent.getPosition(); // Get current holdings
agent.getBalance(); // Get USDC balance

📁 Project Structure

token-market-simulator/
├── Agent.js                      # Individual agent class
├── AMMPool.js                    # AMM pool implementation
├── TokenSimulator.js             # Main simulator class
├── VestingSchedule.js            # Vesting logic
├── MarketAgents.js               # Agent orchestration
├── defaultConfig.js              # Default configuration
├── index.js                      # Main exports
├── package.json                  # Package metadata and scripts
├── README.md                     # This file
├── rng.js                        # Random number utilities
└── strategies/
    ├── index.js                  # Strategy registry
    ├── DCA.js                    # DCA strategy
    ├── GridBot.js                # Grid bot strategy
    ├── MarketMaker.js            # Market maker strategy
    ├── MovingAverageCrossover.js # MA crossover strategy
    ├── RSI.js                    # RSI strategy
    └── WhaleTrader.js            # Whale trader strategy

🤝 Contributing

Contributions are welcome! Please feel free to:

• Open issues for bugs or feature requests
• Submit pull requests with improvements
• Add new trading strategies
• Improve documentation and examples
• Add tests

📄 License

ISC