SHS: Signal Herding Strength ABM

ABM Research: A Calibrated Agent-Based Model of Prediction-Market Spillovers in Bitcoin Markets

• This project was developed as part of the King's College London Master in Computational Finance.

• Paper Link

• Video Link

Team: Peiyan Zou, Qingfan Hou, Jiasen Tian, Yidan Huang

Summary

This study examines how public signals from a prediction market affect Bitcoin spot-price dynamics through trader behavior. We develop an agent-based model with heterogeneous traders who differ in signal sensitivity, herding tendency, and baseline activity. In each period, traders decide whether to participate, choose an order direction and size, and then contribute to aggregate order-flow imbalance that updates returns through a nonlinear price-impact mechanism.

The main result is that stronger herding amplifies the transmission of public signals into market outcomes. As herding rises, market participation increases, imbalance moves toward its upper bound, and price dynamics shift from a fluctuating regime toward a more one-sided regime with persistent net selling pressure. The effect remains visible even when the direct response to the public signal is weakened, suggesting that social interaction among traders can materially amplify the market impact of public information.

Overview

shs-abm is an agent-based market simulation framework for controlled experiments on how exogenous prediction-market signals can influence BTC-like spot-price dynamics.

The package is intended for research and experimentation, not production trading.

Core Features

• Configurable market impact model with nonlinear concave price response.
• Personality-template catalog for agent behavior archetypes.
• Population registration + per-agent parameter sampling.
• Step-aligned simulation outputs as pandas DataFrames.
• Interactive Solara + Mesa monitoring app.

Repository Layout

• Core model: src/shs_abm/model/market_model.py
• Agent logic: src/shs_abm/model/trader_agents.py
• Personality templates: src/shs_abm/model/personality.py
• Data provider: src/shs_abm/data_provider/signal.py
• Interactive app: src/shs_abm/apps/app.py
• Script entrypoint: src/shs_abm/run/run.py

Requirements

• Python >=3.12 (declared in pyproject.toml)
• Mesa ==3.5.0
• Dependencies from requirements.txt

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e . --no-build-isolation

Data Inputs

Processed signal CSVs are expected under src/data/processed/.

The loaders support both naming variants:

• corrected: *_with_signal_series.csv
• legacy (kept for compatibility): *_with_siganl_series.csv

Quick Start (Python Script)

python -m shs_abm.run.run

This writes run_outputs/simulation_result.csv.

Quick Start (Python API)

from shs_abm.data_provider.signal import SignalTimeframe, load_signal_probabilities
from shs_abm.model.market_model import MarketModel

signal = load_signal_probabilities(SignalTimeframe.DAILY)

model = MarketModel(
    signal_series=signal,
    initial_price=100.0,
    impact_eta=0.002,
    impact_i_star=1.0,
    impact_delta=0.5,
    market_noise_scale=0.0,
    rng=42,
    shuffle_activation=False,
)

model.add_agent_population(
    name="baseline",
    count=300,
    trader_population_name="conservative",
    personality_std_scale=0.2,
)
model.build_agents()

while not model.is_finished():
    model.step()

results_df = model.get_results_dataframe()
print(results_df.tail())

Run Interactive App (Solara + Mesa)

solara run src/shs_abm/apps/app.py

Public API Guide

Main MarketModel APIs:

• Catalog: get_personality_catalog, list_personality_catalog_df, add_personality_template, delete_personality_template
• Populations: add_agent_population, delete_population, clear_agent_populations, list_populations_df
• Lifecycle: build_agents, step, is_finished, reset_simulation
• Outputs: get_results_dataframe, get_population_agents_dataframe, get_population_summary_dataframe

Release Checklist

1. Run syntax check:

   PYTHONPYCACHEPREFIX=.pycache_tmp python3 -m py_compile $(rg --files src/shs_abm | rg '\\.py$')

2. Run smoke script:

   python -m shs_abm.run.run

3. Verify app launch:

   solara run src/shs_abm/apps/app.py

4. Tag/release current package version from pyproject.toml.