MicroWorld: a multi-agent world model of US equity markets
A multi-agent world model of US equity markets — simulating institutional players, information asymmetry, and emergent price dynamics
At a glance
- What is it?
- MicroWorld casts institutions, regulators and retail cohorts as agents, solves for a denoised equilibrium price, and reports divergence from it. It is a research signal for weeks-to-months horizons, not a trading system.
- Who is it for?
- MicroWorld suits quantitative researchers and mid-to-long-horizon holders who want a causal, agent-level account of crowding and de-crowding rather than another price-only feature set, and who can accept a model whose own README calls it a research signal. It is the wrong tool for intraday and high-frequency traders: the README states that at those horizons behavioral noise dominates and cites Theorem 1 to argue no volume of data can out-model it.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 23 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The residue problem MicroWorld is built around
Most machine learning applied to prices trains on the outcome of decisions: trades, quotes, returns. MicroWorld's README calls that data "the residue of decisions" and argues residue explains nothing, which is why signals born in backtests die without an explanation. The project's answer is to model the decision-makers instead. Institutions, regulators and retail cohorts become agents with objectives, constraints and information sets, and the price is what falls out of their interaction.
The audience follows from that framing. The README names mid and long horizon holders, To-C and retail, and explicitly excludes intraday and high-frequency trading. The stated reason is a horizon argument, not a performance claim: at weeks-to-months horizons the equilibrium component of price dominates, and at tick horizons behavioral noise does. The project presents a dual Cramér-Rao bound, Theorem 1, as the formal version of that boundary.
How the agent game produces a denoised price
The core object is P^eq, an equilibrium price track the world model solves for. The observed market price is treated as P^eq plus a behavioral wedge, and that wedge widens as institutions crowd into a position and homogenized retail chases the tape. Two quantities come out of the engine. Λₜ is a regime-stability measure: when it crosses its threshold, the README says the sector has left a stable regime. D_t is the divergence, computed as P_t/P^eq_t − 1.
The README's own figure describes the inference as a fully connected agent network in which every neuron is an agent, and the five highlighted edges are principal couplings, a PCA-like subset of interactions that carry a given episode. Their loadings drive a mechanism: information reaches the informed first, institutions de-crowd, momentum pulls retail in, market-maker inventory sets gap risk, and the wedge collapses back onto equilibrium. The division of labor is stated plainly: Λₜ tells you the regime is unstable, and D_t combined with institutional rotation tells you when the instability resolves.
Installing MicroWorld and running the keyless demo
The README gives a one-command entry point that needs no API keys. It is a synthetic concept demo shaped on the July 2026 memory-sector unwind, so the output is generated, not fetched.
python demo/denoised_price_2026.pyThe README says the figure shows a blue equilibrium track P^eq and a black market track that is equilibrium plus a behavioral wedge. The signal fires 11 trading days before the unwind accelerates in the synthetic series. Treat that number as a property of the demo, not a measured result on live data.
The real-data counterpart replays vendored daily closes for a memory basket including SK Hynix, Samsung, Micron, Western Digital, Seagate and SanDisk, again without keys.
python demo/hindcast_memory_2026.pyFor the full environment, requirements.txt pins Python 3.11+ dependencies and setup.sh is the repository's install script. The core stack is heavy: torch>=2.1.0, jax[cuda12]>=0.4.20, flax, optax, transformers, plus kafka-python, psycopg2-binary, sqlalchemy, apache-airflow and streamlit. If you only want the demos, installing the whole file pulls a GPU-oriented JAX build and an orchestration server you may not need.
Live data paths are configured through environment variables. .env.example lists POLYGON_KEY, ALPACA_KEY, ALPACA_SECRET, FRED_KEY, NEWSAPI_KEY, BARCHART_KEY, DB_URL and KAFKA_BOOTSTRAP, with DB_URL defaulting to postgresql://postgres:alphaflow@localhost:5432/alphaflow and KAFKA_BOOTSTRAP to localhost:9092. The README does not document rollback or migration steps for that Postgres schema.
The hindcast is honest, and that honesty is the limitation
The repository's strongest section is also the one that constrains how it can be used. On the vendored memory basket, Λₜ did not cross its threshold once across three years covering the 2022 memory bear and the 2023 to 2025 recovery. The first alarm in the sample is dated October 22, 2025, described as the AI-memory mania itself, 232 trading days before July 2026 delivered the sector's worst month since 2008.
Then the README states the other half: after that alarm the basket rose another 446 percent before it broke. Basin-exit detection is not crash timing. An unstable crowding regime can keep inflating for months. Anyone reading Λₜ as a sell signal would have exited roughly a year and a half of upside early, and the project says so in its own text rather than burying it.
The README also labels the exercise a hindcast computed after the event, with no "we predicted it" claim. The recipe was frozen from 2008 with one disclosed adaptation, funding stress to crowding extension. That is a single-episode replay, not a walk-forward across many regimes, and the README does not present it as one.
Where the signal still depends on an unfinished experiment
The synthetic demo shows both halves of the MVP signal working: regime instability plus divergence with institutional rotation. The real-data version has only the first half. Reconstructing the κ-rotation condition, meaning who is holding the wedge up and when they rotate out, from real 13F and COT positioning is listed as experiment E7 in RESOURCES.md.
That is the honest state of the project. The mechanism that would tell you when an unstable regime resolves is demonstrated on synthetic data and explicitly deferred to future work on real data. Until E7 lands, the real-data hindcast can flag instability but cannot date the resolution.
The repository layout supports that reading. There are directories for agents, encoder, game, controller, events, online, backtest and dashboard, plus an e5 directory and a notebooks directory. The README's own framing is that this is the MVP. Breadth of directories is not evidence that each path is complete, and the README does not document which ones are.
MicroWorld against factor mining and price-only deep learning
The obvious alternative is the standard quantitative workflow: mine factors from price and fundamental panels, fit a supervised model, validate on a held-out period. That approach treats the market as a data-generating process to be approximated. MicroWorld treats it as a game to be simulated, and the price is an output of agent behavior rather than the input to a regressor.
The practical difference shows up in what you can say about a signal. A factor model gives you a coefficient and an out-of-sample return. MicroWorld gives you a named mechanism: information reached the informed first, institutions de-crowded, momentum pulled retail in. That is auditable in a way a factor loading is not.
The cost is different too. A factor pipeline runs on a price panel. MicroWorld's full stack wants Kafka, Postgres, Airflow and several paid data APIs with free tiers, and its most interesting real-data result depends on positioning data that the README says is not yet wired in. If your goal is a deployable signal this quarter, a factor pipeline is the lower-risk path. If your goal is understanding why a crowding episode resolved when it did, the agent game is the more informative frame.
Licence, maintenance and the cost of upgrading
The README carries an MIT badge linking to LICENSE, but the repository metadata does not state a licence, so read the LICENSE file itself before you depend on the code. If it is MIT, the usual implications apply: permissive reuse with attribution and no warranty, which matters for a project that ships a signal people might act on. Nothing here is legal advice.
The repository is not archived. The last push was on 2026-08-25. There are no retrieved releases, so upgrades happen by tracking the main branch rather than by pinning a version. That raises the cost of staying current: requirements.txt pins minimum versions with >= rather than exact pins, which means a fresh install can resolve to different library versions than an older one, and there is no changelog to read between pulls. The README does not document a migration path for the Postgres schema behind DB_URL.
There is a companion paper repository and a separate engineering repository linked from the README badges, so part of the design rationale lives outside this tree.
Editorial conclusion
MicroWorld suits quantitative researchers and mid-to-long-horizon holders who want a causal, agent-level account of crowding and de-crowding rather than another price-only feature set, and who can accept a model whose own README calls it a research signal. It is the wrong tool for intraday and high-frequency traders: the README states that at those horizons behavioral noise dominates and cites Theorem 1 to argue no volume of data can out-model it. Before adopting it, verify the licence text in LICENSE against the MIT badge in the README, check whether setup.sh installs the full requirements.txt stack, and read RESOURCES.md to see what experiment E7 still leaves open.
Frequently asked questions
What is MicroWorld?
MicroWorld is a multi-agent world model of US equity markets that simulates institutional players, information asymmetry and emergent price dynamics, and solves for a denoised equilibrium price track P^eq. The README frames it as a world model architecture designed for quantitative finance rather than a factor-mining pipeline.
What is MicroWorld used for?
The README describes two uses: a synthetic demo that predicts a denoised equilibrium price, and a real-data hindcast of a memory-sector basket that flags when the sector leaves a stable regime. It is aimed at mid and long horizon holders, and the README states it is deliberately not for intraday or high-frequency trading.
Who created MicroWorld?
The README credits Alpha Flow Research and HongJin HE, with HKUST and Stanford IHP, dated July 2026. The repository is hosted at hongjin-he/MicroWorld.
What is the difference between a micro world and a macro world in MicroWorld?
MicroWorld works at the level of individual agents, institutions, regulators and retail cohorts, and derives aggregate price behavior from their interactions. The README does not use the term macro world, so the project does not document a separate macro-level model.
Community notes