Deep diveCapital Raising & Tokenomics
Agent-based simulation for tokenomics, explained
Spreadsheet tokenomics shows what happens if everyone behaves as the spreadsheet assumes. Agent-based simulation asks a harder question: what happens when stakers, traders, liquidity providers, the team and early investors each follow their own rules and react to one another. This deep dive explains how such a model is built and run, what it can reveal about a token design, where it misleads, and how to read a simulation report.
On this page
- What an agent-based model adds to a tokenomics spreadsheet
- Terms used in a token simulation
- Holder archetypes and the behaviour each one tests
- How one time step runs
- Sweeps, Monte Carlo runs and stress paths
- A hypothetical network modelled as one system
- Recalibrating the model with real holder data
- Where token simulations mislead
- Questions to ask of any simulation report
- Questions and answers
- Sources
What an agent-based model adds to a tokenomics spreadsheet
A spreadsheet applies average behaviour to totals: a fixed share of released tokens is sold, a fixed share is staked, the rest is held. That is enough to check that an allocation reconciles and to project circulating supply. It cannot show what happens when behaviours interact, for instance when falling staking yields push stakers to sell, which weakens the price, which pushes yields lower again.
An agent-based model represents holders as many individual agents grouped into archetypes, each with rules for what to do given the state of the system. The model advances in time steps: at each one, agents observe the state, act, and the state updates. Feedback loops, thresholds and tipping points emerge from those interactions instead of being written in by hand, and they are what a design review most needs to see.
Open-source token-engineering tools support this way of working. The cadCAD library, written in Python for designing, testing and validating complex systems through simulation, supports Monte Carlo runs, A/B tests and parameter sweeps1. Equivalent models can be built in general-purpose languages; the method matters more than the tool.
Terms used in a token simulation
- Agent
- One simulated holder, or a small group treated as one, with its own balances and decision rules.
- Archetype
- A class of agents sharing a behavioural profile, such as long-term stakers. The mix of archetypes is itself a parameter to vary.
- State
- Everything the model tracks at a point in time: balances, circulating and staked supply, treasury holdings, a price or demand proxy and governance positions.
- Policy
- The rule that turns what an agent observes into an action, such as selling part of each release when yield drops below a threshold.
- Time step
- One tick of the model, often a day or a week, at which agents act and the state updates.
- Parameter sweep
- Running the model across a grid of design choices, such as reward rates or cliff lengths, to find which settings are fragile.
- Monte Carlo run
- Repeating a scenario many times with randomness in behaviour or outside shocks, so results appear as a spread rather than a single path.
- Stress path
- An externally imposed scenario, such as a prolonged market drawdown or a large holder's exit, used to test resilience.
Holder archetypes and the behaviour each one tests
| Archetype | What drives its decisions | Example rule in the model | What it reveals |
|---|---|---|---|
| Long-term stakers | Yield against alternatives; lock-up terms | Stakes while yield stays above a threshold, then exits gradually | Whether rewards retain holders once emissions fall |
| Liquidity providers | Fees and incentives against price risk | Withdraws when incentives end or volatility rises | How deep markets stay when liquidity rewards taper |
| Short-horizon traders | Momentum and news | Buys after rises and sells after falls, with randomness | How strongly the design amplifies price moves |
| Team and contributors | Vesting, personal liquidity needs, commitment | Sells a small share of each release to cover costs and taxes | Whether team releases create visible selling |
| Early investors | Fund life, entry price and portfolio rules | Sells more of each release as fund end nears or when in profit | Pressure around investor release dates |
| Governance delegates | Influence, reputation and alignment | Votes with the largest bloc unless a proposal harms its stake | Whether governance can be captured |
Rules like these are assumptions, not observations. A good report states each one and shows how results change when it varies.
How one time step runs
- Scheduled events fire
Vesting releases, emissions and planned treasury spending for this step are applied.
- Outside shocks applied
The scenario injects external events, such as a market drawdown, at the step it specifies.
- Agents observe state
Each agent reads the variables its rules depend on: yield, the price proxy and its own transferable balance.
- Policies choose actions
Rules turn observations into actions: stake, unstake, sell, buy, add liquidity or vote.
- State updates
Balances, supply figures, treasury holdings and the price proxy are recalculated from the actions.
- Metrics recorded
Supply, treasury runway, holder concentration and voting power are logged before the next step.
Sweeps, Monte Carlo runs and stress paths
A single run proves little: it depends on random draws and on parameters nobody knows precisely. Three techniques turn runs into evidence. Parameter sweeps vary the levers the team controls, such as reward rate, cliff length or treasury sale limits, to find fragile settings. Monte Carlo repetition runs each setting many times with random variation, so results come as distributions with bands rather than lines. Stress paths impose conditions the team does not control: a prolonged drawdown, a large holder exiting, liquidity thinning after incentives end.
Two tests deserve particular attention. Treasury runway asks how long the treasury funds operations when the token trades far below its launch price for an extended period, and what spending or emission changes would extend it. Governance capture asks whether one large holder, or a coordinated group of insiders, could reach quorum and pass proposals against minority holders. Both change as tokens vest, so they are tested at several points along the schedule rather than once.
A hypothetical network modelled as one system
Recalibrating the model with real holder data
Before launch, behavioural rules come from judgement, comparable projects and investor conversations. After launch, the ledger supplies evidence: how much of each release actually moved, how staking responded to yield changes, how concentrated holdings became. Replacing assumed rules with fitted ones, archetype by archetype, turns the model from a design aid into a decision aid.
Recalibrate before any change to emissions, reward rates or treasury spending, keeping old and new parameter sets side by side. A governance proposal citing a simulation calibrated only on pre-launch assumptions deserves scepticism, however detailed it looks.
Where token simulations mislead
Behavioural rules chosen to produce a good answer
Early signalEvery archetype holds or stakes in the central case, and no scenario shows sustained selling.
MitigationHave someone outside the design team set or challenge the rules, and include pessimistic archetype mixes in every sweep.
Reflexivity treated as noise
Early signalPrice is fed in as a fixed series rather than moved by agents' actions.
MitigationModel a price or demand proxy that responds to net buying and selling, and show results with and without that feedback.
False precision
Early signalResults quoted as single figures to several decimal places.
MitigationReport distributions and bands, and state which conclusions hold across the whole range.
Outputs read as a price forecast
Early signalCharts of simulated price appear in marketing or investor materials.
MitigationLabel outputs as conditional scenarios. In the EU, a crypto-asset white paper may not assert future value beyond the required risk statements2.
Questions to ask of any simulation report
Questions and answers
Can a tokenomics simulation predict the token price?
No, and a report that claims to should be treated with caution. Prices depend on market conditions, sentiment and events outside any model. A simulation shows how a design behaves across many plausible combinations of holder behaviour and outside conditions, which settings are fragile and where treasury or governance risk concentrates. Its outputs are conditional scenarios for comparing designs, not forecasts of value.
What makes building a token simulation slow or fast?
Mostly the assumptions, not the code. Every behavioural rule needs to be argued for and documented, and early runs usually expose design questions that must be answered before the model is finished. Teams that arrive with a reconciled allocation table, written emission rules and governance parameters move much faster than those still settling the design.
Do we need a simulation if our token supply is fixed?
Usually, yes. A fixed supply removes emissions but not the questions that matter most: how releases interact with holder behaviour, whether a treasury holding mostly its own token survives a long downturn, and whether insiders can control governance during the vesting period. A simpler model may be enough, but those interactions still need testing before launch.
Who should see the simulation results?
The protocol team and board first, then investors during diligence and counsel preparing any disclosure. Governance participants benefit from seeing the model behind proposals to change emissions or treasury policy. Share the assumptions and code alongside the results wherever confidentiality allows; a result that cannot be inspected carries little weight with experienced reviewers.
Sources
- cadCAD: open-source Python package for complex adaptive systems simulation — cadCAD on GitHub · checked 10 October 2026
- Regulation (EU) 2023/1114 on markets in crypto-assets (MiCA), Article 6(4) — EUR-Lex · checked 10 October 2026