Agent-Based Modeling in Tokenomics

The Problem: Spreadsheets Model Averages, Systems Break at Extremes

A spreadsheet tokenomics model works with aggregates: total supply, average price, total staking. It’s a useful tool — we start every project with a spreadsheet. But spreadsheets have a fundamental limitation: they don’t model individual participant behavior.

Consider staking. A spreadsheet says: “at 5% APR, 60% of tokens will be staked.” One scenario, one number. But in reality, stake distribution is uneven — 10 wallets may control 25% of the stake. If three whales exit simultaneously, the APR changes, triggering reactions from other participants. A spreadsheet won’t show this.

Agent-based modeling (ABM) builds the system bottom-up: each participant is a separate agent with their own balance, strategy, and decision thresholds. The model runs for hundreds of iterations, and at each step agents make decisions based on the current system state.

The result is not one forecast, but a distribution of possible outcomes, including extreme scenarios.

When You Need ABM vs When a Spreadsheet Is Enough

The rule is simple: if one participant’s actions change conditions for others — you need ABM. If not — a spreadsheet is sufficient.

Example: Staking and Bank Run

A concrete case where a spreadsheet gives false confidence, while an agent-based simulation reveals systemic risk.

Setup

A protocol with fixed emission: 800 tokens per day distributed to stakers proportionally. At 60% of tokens staked, this yields an APR of ~4.9%.

Questions:

• How many stakers will remain if APR falls below some participants’ expectations?
• What happens if the 10 largest wallets exit simultaneously?

A spreadsheet would answer: “when 10 stakers exit, APR increases proportionally.” But this doesn’t account for who exits (a whale or a small holder) and what happens next (cascading reactions).

The Model: 200 Agents with Different Strategies

Each agent has three parameters:

The top 10 agents control ~22% of the stake — a power-law distribution.

Simulation Code

Full code — copy into Google Colab and run:

import numpy as np
import matplotlib.pyplot as plt

np.random.seed(42)

# === Parameters ===
num_agents = 200
num_steps = 365            # days
total_supply = 10_000_000
daily_rewards = 800        # tokens/day (~4.9% APR at full stake)

# === Generate agents ===
# Balances: power law (Pareto) — a few whales, many small holders
raw = np.random.pareto(a=1.5, size=num_agents) + 1
balances = (raw / raw.sum() * total_supply * 0.6).astype(int)

# APR threshold: below this value the agent exits staking
apr_thresholds = np.random.uniform(0.03, 0.15, size=num_agents)

# Reaction delay: how many days APR must stay below threshold
reaction_delay = np.random.randint(1, 15, size=num_agents)

# State
is_staking = np.ones(num_agents, dtype=bool)
days_below_threshold = np.zeros(num_agents, dtype=int)

# Metrics
h_staked = np.zeros(num_steps)
h_apr = np.zeros(num_steps)
h_num = np.zeros(num_steps)

# === Simulation ===
for day in range(num_steps):
    staked_total = balances[is_staking].sum()
    if staked_total == 0:
        break

    current_apr = (daily_rewards * 365) / staked_total

    h_staked[day] = staked_total
    h_apr[day] = current_apr
    h_num[day] = is_staking.sum()

    for i in range(num_agents):
        if not is_staking[i]:
            continue
        if current_apr < apr_thresholds[i]:
            days_below_threshold[i] += 1
            if days_below_threshold[i] >= reaction_delay[i]:
                is_staking[i] = False  # exit
        else:
            days_below_threshold[i] = 0  # reset counter

Key mechanic: at each step, every agent checks the current APR. If APR is below their threshold for longer than their reaction delay — they exit. One agent’s exit reduces the total stake, which changes the APR for everyone else. This is the cascading effect that’s invisible in a spreadsheet.

Results

Two scenarios with the same agents:

• No shock — the system evolves on its own
• With shock — on day 60, the 10 largest stakers are forcibly removed

No-Shock Scenario

Starting APR of 4.9% is below threshold for most agents. Over 14 days, 120 agents exit — those whose thresholds remain above the rising APR long enough to trigger their reaction delay. Stake drops from 6M to 2.4M, APR rises to 12.1%, and the system stabilizes. The remaining 80 agents are satisfied.

A spreadsheet would say: “60% is staked at 4.9% APR.” The simulation showed: actually 24% is staked (2.4M out of 10M), and equilibrium APR is 12.1%, not 4.9%.

Shock Scenario (10 Whales Exit on Day 60)

By day 60, the system is already at equilibrium (80 stakers, 12.1% APR). Then 10 largest wallets exit simultaneously:

The 10 whales’ exit removes ~1M tokens from the stake. APR jumps to 21.2%. In this specific run, there is no cascade — all remaining 70 agents have thresholds below 21.2% and reach equilibrium immediately.

In a more realistic model (accounting for token price drops during mass exits), the effect would be amplified: whale exit → sell pressure → price drops → real USD yield falls → cascade intensifies.

What the Simulation Showed That a Spreadsheet Wouldn’t

1. Real equilibrium (80 stakers, not 200) — with the same APR and supply
2. Cascade speed (14 days to stabilization) — specific dynamics, not “instant recalculation”
3. Reaction delay matters — agents with delay=14 exit later, stretching the cascade
4. Distribution matters — 10 whales exiting removed ~1M, while 10 smallest holders would remove ~130K

Scaling the Model

The example above is basic. For a real project, you can add:

Price feedback. Currently, the token price doesn’t change when stakers exit. In reality: exit → sell → price drops → real yield falls → cascade intensifies. This turns a soft stabilization into a hard bank run.

Multiple agent types. “Farmers” move between protocols as APR changes, “holders” ignore APR and react only to price, “attackers” deliberately destabilize the stake.

Multiple runs. One run = one outcome. 100 runs with different seeds yield a distribution of outcomes. The question isn’t “what will happen” but “in what percentage of runs does stake fall below 20% of supply.”

Tools

For the example in this article, NumPy + Matplotlib is enough. For more complex models:

cadCAD — the original Python framework by BlockScience (largely unmaintained since 2022). Formalizes the model as a chain of “state → policy → state update mechanism.” Was used for modeling Ethereum 2.0, Filecoin, Ocean Protocol.

radCAD — a lightweight reimplementation of the cadCAD execution engine by CADLabs (Rust+Python). Compatible model structure, faster execution, less boilerplate.

Mesa — the most popular general-purpose ABM framework for Python. Well-documented, actively maintained. Many tokenomics teams use Mesa instead of cadCAD for its broader community and flexibility.

TokenSPICE — a simulator by Ocean Protocol. Works with actual EVM contracts via a local EVM network (Ganache). Tests not an abstract model but specific Solidity code. The project has been unmaintained since late 2022, but the code is available.

Workflow

1. Design the economy in a spreadsheet. Allocation, vesting, emission, unit economics. Make sure the supply model converges.
2. Identify the critical mechanism. What can break? Staking, governance, liquidity?
3. Define agent types. Who are the participants, what are their goals? Which parameters vary?
4. Run 100+ simulations. One run proves nothing.
5. Analyze the tails. Not the average outcome, but the 5th percentile — what happens in the worst 5% of scenarios?
6. Iterate on mechanism parameters. The goal: robustness in 95%+ of runs.

Checklist: do you need an agent-based model?

3+ items checked — ABM will pay for itself. 0–1 — start with a spreadsheet model.