Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/at6132/econ/llms.txt

Use this file to discover all available pages before exploring further.

The Realm engine exposes a REST API built with FastAPI. Every client interaction — claiming a plot, placing a market order, proposing a contract, or advancing the simulation — goes through this API. The engine validates every request and either commits the action to world state or returns an error; it never applies partial changes.
All endpoints are served at http://localhost:8000 in development. The engine runs on FastAPI with CORS allowed for localhost:3000.

​
World & Tick

​
GET /health

Returns engine liveness. Use this to confirm the server is running before making other requests. 
curl http://localhost:8000/health
​
status
string
Always "ok" when the engine is running.

​
GET /world

Returns the full public world state as a single JSON object. This is the primary data source for the web client — it includes plots, balances, inventory, market order books, contracts, event log, and more. 
curl http://localhost:8000/world
​
seed
integer
The seed used to generate this world.
​
tick
integer
Current simulation tick (starts at 0, increments with each POST /tick).
​
scenario_id
string
The active scenario name (e.g. frontier, genesis).
​
plots
array
All plots in the world grid.
​
balances_cents
object
Map of party ID → cash balance in cents.
​
inventory
object
Nested map of party ID → material ID → quantity.
​
market_asks
object
Open sell orders, grouped by material ID.
​
market_bids
object
Open buy orders, grouped by material ID.
​
contracts
array
All active contracts with their current state.
​
event_log
array
Last 120 engine events (most recent last).
​
market_history
array
Recent market price history snapshots (up to 160 entries, or full history if market intel is active).
​
deployed_lua
object
Map of party ID → { chars, lines } for any deployed Lua sources (Phase 4 staging).

​
POST /tick

Advances the simulation by one tick. Runs the full tick pipeline: transit delivery, building decay, production, spoilage, employment, Tier 1 agents, Tier 2 agents, Tier 3 LLM agents, clock advance, contract breach checks, financial contract processing, and market snapshot. 
curl -X POST http://localhost:8000/tick
​
ok
boolean
true on success.
​
tick
integer
The new tick number after advancing.

​
Plots

​
POST /plots//claim

Claims an unclaimed plot for a party.
​
plot_id
string
required
The plot ID to claim (e.g. p-3-5).
​
party
string
The party claiming the plot. Defaults to "player".
curl -X POST "http://localhost:8000/plots/p-3-5/claim?party=player"
​
ok
boolean
true on success. false with a reason field on failure (already claimed, unknown plot, etc.).

​
POST /plots//survey

Reveals the subsurface composition of a plot the party owns. After surveying, GET /world will include subsurface grades and available recipe_ids for that plot.
​
plot_id
string
required
The plot ID to survey.
​
party
string
The surveying party. Defaults to "player".
curl -X POST "http://localhost:8000/plots/p-3-5/survey?party=player"
​
ok
boolean
true on success.
​
terrain
string
The plot’s terrain type.
​
recipe_ids
array
Production recipe IDs now available on this plot.

​
POST /plots//produce

Starts a production run on a surveyed, owned plot using a specific recipe. The run completes after the recipe’s ticks_required ticks.
​
plot_id
string
required
The plot to produce on.
​
recipe_id
string
required
The recipe ID to run (must be valid for this plot’s terrain and subsurface).
​
party
string
The party initiating production. Defaults to "player".
curl -X POST "http://localhost:8000/plots/p-3-5/produce?recipe_id=iron_ore_basic&party=player"
​
ok
boolean
true on success.
​
run_id
string
ID of the active production run; appears in world.active_production.

​
POST /plots//build

Constructs a building on a plot. The building_id must be valid for the plot’s terrain. Use world.building_catalog from GET /world for available buildings.
​
plot_id
string
required
The plot to build on.
​
building_id
string
required
The ID of the building to construct.
​
party
string
The party building. Defaults to "player".
​
build_mode
string
Optional build mode modifier.
curl -X POST "http://localhost:8000/plots/p-3-5/build?building_id=sawmill&party=player"
​
ok
boolean
true on success.

​
POST /plots//maintain

Resets the decay counter on a building instance, keeping it operational.
​
plot_id
string
required
The plot containing the building.
​
instance_id
string
required
The building instance ID (from world.plot_buildings).
​
party
string
The maintaining party. Defaults to "player".
curl -X POST "http://localhost:8000/plots/p-3-5/maintain?instance_id=bld-001&party=player"
​
ok
boolean
true on success.

​
POST /plots//schematic/validate

Validates a proposed linear recipe chain against engine recipes and the party’s inventory. Returns whether the chain is feasible without executing it.
​
plot_id
string
required
The plot the chain would run on (must be owned and surveyed by the party).
​
party
string
The party proposing the chain. Defaults to "player".
curl -X POST "http://localhost:8000/plots/p-3-5/schematic/validate?party=player" \
  -H "Content-Type: application/json" \
  -d '{"recipe_ids": ["iron_ore_basic", "smelt_iron"]}'
​
ok
boolean
true if the chain is valid and feasible.
​
reason
string
Present when ok is false — explains why validation failed.

​
Market

​
POST /market/sell

Places a limit sell order (ask) on the order book for a material.
​
party
string
required
The selling party.
​
material
string
required
Material ID to sell (e.g. iron_ore, grain, timber).
​
qty
integer
required
Quantity to offer.
​
price_per_unit_cents
integer
required
Ask price per unit in cents.
​
iceberg_display_qty
integer
If set, only this quantity is visible on the book; the rest is hidden.
​
min_counterparty_honored
integer
Minimum reputation score required for a buyer to fill this order. Defaults to 0.
curl -X POST "http://localhost:8000/market/sell?party=player&material=iron_ore&qty=10&price_per_unit_cents=150"
​
ok
boolean
true on success.
​
order_id
string
The new order’s ID.

​
POST /market/bid

Places a limit buy order (bid) on the order book for a material.
​
party
string
required
The buying party.
​
material
string
required
Material ID to bid for.
​
qty
integer
required
Quantity to bid for.
​
max_price_per_unit_cents
integer
required
Maximum price per unit in cents.
​
iceberg_display_qty
integer
If set, only this quantity is visible on the book.
​
min_counterparty_honored
integer
Minimum reputation score required for a seller to fill this order. Defaults to 0.
curl -X POST "http://localhost:8000/market/bid?party=player&material=grain&qty=20&max_price_per_unit_cents=130"
​
ok
boolean
true on success.
​
order_id
string
The new bid order’s ID.

​
POST /market/buy

Market buy: immediately fills against the cheapest available asks up to max_qty. Does not place a resting order.
​
party
string
required
The buying party.
​
material
string
required
Material ID to buy.
​
max_qty
integer
required
Maximum quantity to buy.
​
min_seller_honored
integer
Minimum reputation score required for sellers. Defaults to 0.
curl -X POST "http://localhost:8000/market/buy?party=player&material=coal&max_qty=5"
​
ok
boolean
true on success.
​
filled_qty
integer
Total quantity filled across all matched asks.

​
POST /market/sell_fill

Market sell: immediately fills against the highest available bids up to max_qty. Does not place a resting order.
​
party
string
required
The selling party.
​
material
string
required
Material ID to sell.
​
max_qty
integer
required
Maximum quantity to sell.
​
min_buyer_honored
integer
Minimum reputation score required for buyers. Defaults to 0.
curl -X POST "http://localhost:8000/market/sell_fill?party=player&material=timber&max_qty=4"
​
ok
boolean
true on success.

​
POST /market/cancel

Cancels an open sell (ask) order by order ID.
​
party
string
required
The party that placed the order.
​
order_id
string
required
The order ID to cancel.
curl -X POST "http://localhost:8000/market/cancel?party=player&order_id=ask-00042"
​
ok
boolean
true on success.

​
POST /market/cancel_bid

Cancels an open buy (bid) order by order ID.
​
party
string
required
The party that placed the bid.
​
order_id
string
required
The bid order ID to cancel.
curl -X POST "http://localhost:8000/market/cancel_bid?party=player&order_id=bid-00017"
​
ok
boolean
true on success.

​
POST /market/intel

Purchases market intelligence for the requesting party. When active, GET /world returns the full market_history instead of the short free window.
​
party
string
The party purchasing intel. Defaults to "player".
curl -X POST "http://localhost:8000/market/intel?party=player"
​
ok
boolean
true on success.
​
expires_tick
integer
The tick at which the intel subscription expires.

​
Trade

​
POST /trade/p2p

Executes a direct party-to-party trade: transfers materials from seller to buyer and cash from buyer to seller atomically.
​
seller
string
required
The selling party.
​
buyer
string
required
The buying party.
​
material
string
required
Material ID to transfer.
​
qty
integer
required
Quantity to transfer.
​
total_price_cents
integer
required
Total price for the entire quantity in cents.
​
idempotency_key
string
Optional key to prevent duplicate trades on retry.
curl -X POST "http://localhost:8000/trade/p2p?seller=player&buyer=npc_grain_vendor&material=grain&qty=5&total_price_cents=600"
​
ok
boolean
true on success. On failure, also returns reason and code.

​
Contracts

​
POST /contracts/supply/propose

Proposes a supply contract: the supplier agrees to deliver qty of material to the buyer by due_in_ticks ticks from now, at total_price_cents.
​
supplier
string
required
The party supplying the material.
​
buyer
string
required
The party receiving the material.
​
material
string
required
Material ID to deliver.
​
qty
integer
required
Quantity to deliver.
​
total_price_cents
integer
required
Total contract price in cents.
​
due_in_ticks
integer
required
Number of ticks from now until delivery is due.
​
buyer_deposit_cents
integer
Upfront deposit from the buyer. Defaults to 0.
​
liquidated_damages_cents
integer
Penalty owed to the buyer if the supplier breaches. Defaults to 0.
curl -X POST "http://localhost:8000/contracts/supply/propose?supplier=player&buyer=t1_consumer&material=grain&qty=10&total_price_cents=1200&due_in_ticks=50"
​
ok
boolean
true on success.
​
contract_id
string
ID of the newly proposed contract.

​
POST /contracts/supply/accept

Accepts a pending supply contract. Must be called by the buyer.
​
buyer
string
required
The buying party accepting the contract.
​
contract_id
string
required
The contract ID to accept.
curl -X POST "http://localhost:8000/contracts/supply/accept?buyer=t1_consumer&contract_id=ctr-001"
​
ok
boolean
true on success.

​
POST /contracts/supply/fulfill

Fulfills an accepted supply contract by delivering the material. Must be called by the supplier.
​
supplier
string
required
The supplying party fulfilling the contract.
​
contract_id
string
required
The contract ID to fulfill.
curl -X POST "http://localhost:8000/contracts/supply/fulfill?supplier=player&contract_id=ctr-001"
​
ok
boolean
true on success.

​
POST /contracts/loan/propose

Proposes a loan contract: the lender transfers principal_cents to the borrower, who must repay repay_cents within due_in_ticks ticks.
​
lender
string
required
The lending party.
​
borrower
string
required
The borrowing party.
​
principal_cents
integer
required
Loan amount in cents.
​
repay_cents
integer
required
Total repayment amount (principal + interest) in cents.
​
due_in_ticks
integer
required
Number of ticks until the loan is due.
curl -X POST "http://localhost:8000/contracts/loan/propose?lender=player&borrower=t1_consumer&principal_cents=10000&repay_cents=11000&due_in_ticks=100"
​
ok
boolean
true on success.
​
contract_id
string
ID of the new loan contract.

​
POST /contracts/loan/accept

Accepts a pending loan contract and transfers the principal to the borrower.
​
borrower
string
required
The borrowing party accepting the loan.
​
contract_id
string
required
The loan contract ID to accept.
curl -X POST "http://localhost:8000/contracts/loan/accept?borrower=t1_consumer&contract_id=ctr-005"
​
ok
boolean
true on success.

​
POST /contracts/loan/repay

Repays an accepted loan contract.
​
borrower
string
required
The borrowing party making the repayment.
​
contract_id
string
required
The loan contract ID to repay.
curl -X POST "http://localhost:8000/contracts/loan/repay?borrower=t1_consumer&contract_id=ctr-005"
​
ok
boolean
true on success.

​
POST /contracts/equity/propose

Proposes an equity-style contract: the investor pays investment_cents upfront and receives dividend_per_tick_cents per tick for dividend_ticks ticks.
​
issuer
string
required
The party issuing equity (receives the investment).
​
investor
string
required
The investing party (receives dividends).
​
investment_cents
integer
required
Upfront investment amount in cents.
​
dividend_per_tick_cents
integer
required
Dividend paid per tick in cents.
​
dividend_ticks
integer
required
Number of ticks over which dividends are paid.
curl -X POST "http://localhost:8000/contracts/equity/propose?issuer=player&investor=t1_consumer&investment_cents=50000&dividend_per_tick_cents=600&dividend_ticks=100"
​
ok
boolean
true on success.
​
contract_id
string
ID of the new equity contract.

​
POST /contracts/equity/accept

Accepts an equity contract proposal. The investor’s payment transfers to the issuer.
​
investor
string
required
The investing party accepting the contract.
​
contract_id
string
required
The equity contract ID to accept.
curl -X POST "http://localhost:8000/contracts/equity/accept?investor=t1_consumer&contract_id=ctr-010"
​
ok
boolean
true on success.

​
POST /contracts/service/propose

Proposes a service subscription contract: the provider offers access for fee_cents over duration_ticks ticks.
​
provider
string
required
The party providing the service.
​
subscriber
string
required
The subscribing party.
​
fee_cents
integer
required
Total subscription fee in cents.
​
duration_ticks
integer
required
Subscription duration in ticks.
curl -X POST "http://localhost:8000/contracts/service/propose?provider=player&subscriber=t1_consumer&fee_cents=5000&duration_ticks=200"
​
ok
boolean
true on success.
​
contract_id
string
ID of the new service subscription contract.

​
POST /contracts/service/accept

Accepts a pending service subscription contract.
​
subscriber
string
required
The subscribing party accepting the contract.
​
contract_id
string
required
The service contract ID to accept.
curl -X POST "http://localhost:8000/contracts/service/accept?subscriber=t1_consumer&contract_id=ctr-012"
​
ok
boolean
true on success.

​
POST /contracts//honor

Marks a contract as honored by its ID. This is a general stub for contract resolution outside the type-specific endpoints.
​
contract_id
string
required
The contract to honor.
curl -X POST "http://localhost:8000/contracts/ctr-003/honor"
​
ok
boolean
true on success.

​
POST /contracts/propose

Generic contract proposal stub. Useful for proposing contracts by kind without the type-specific endpoints.
​
party_a
string
required
The proposing party.
​
party_b
string
required
The counterparty.
​
kind
string
Contract kind: supply, loan, equity, or service. Defaults to "supply".
curl -X POST "http://localhost:8000/contracts/propose?party_a=player&party_b=t1_consumer&kind=supply"

​
Labor

​
GET /hire/catalog

Returns the public catalog of available hire-able roles and labor types. 
curl http://localhost:8000/hire/catalog
​
roles
array
List of available labor roles.

​
POST /hire

Hires a worker (employee) for an employer, with a signing bonus and optional recurring wage.
​
employer
string
required
The hiring party.
​
employee
string
required
The party being hired.
​
signing_bonus_cents
integer
required
One-time signing bonus in cents paid immediately.
​
wage_per_tick_cents
integer
Recurring wage paid per tick. Defaults to 0.
​
wage_interval_ticks
integer
How often the wage is paid (in ticks). Defaults to 1.
curl -X POST "http://localhost:8000/hire?employer=player&employee=t1_timber_merchant&signing_bonus_cents=2000&wage_per_tick_cents=50&wage_interval_ticks=10"
​
ok
boolean
true on success.

​
Movement

​
POST /ship

Dispatches a shipment of materials from one plot to another. The shipment enters world.in_transit and arrives after a transit delay.
​
party
string
required
The party dispatching the shipment.
​
material
string
required
Material ID to ship.
​
qty
integer
required
Quantity to ship.
​
from_plot
string
required
Origin plot ID.
​
to_plot
string
required
Destination plot ID.
curl -X POST "http://localhost:8000/ship?party=player&material=iron_ore&qty=5&from_plot=p-3-5&to_plot=p-7-2"
​
ok
boolean
true on success.
​
shipment_id
string
ID of the in-transit shipment; visible in world.in_transit.

​
Persistence

​
POST /persistence/save

Saves the current world state to a SQLite file. Defaults to saves/realm_dev.sqlite in the repo root.
​
path
string
Absolute or repo-relative path for the save file. Omit to use the default.
# Save to default path
curl -X POST http://localhost:8000/persistence/save

# Save to a named file
curl -X POST "http://localhost:8000/persistence/save?path=saves/my_run.sqlite"
​
ok
boolean
true on success.
​
path
string
The absolute path where the save was written.

​
POST /persistence/load

Replaces the current in-memory world with one loaded from a SQLite save file.
​
path
string
Absolute or repo-relative path of the save file to load. Omit to use the default path.
# Load from default path
curl -X POST http://localhost:8000/persistence/load

# Load from a named file
curl -X POST "http://localhost:8000/persistence/load?path=saves/my_run.sqlite"
​
ok
boolean
true on success.
​
path
string
The path the save was loaded from.
​
tick
integer
The tick number from the loaded save.

​
User Code

​
GET /code/status

Returns the user-code layer capability advertisement. Use this to check whether Lua is available, what the size limits are, and what phase the sandbox is in. 
curl http://localhost:8000/code/status
​
phase
string
"stub" until the Phase 4 sandbox ships.
​
lua_runtime
boolean
Whether a Lua runtime (lupa) is available.
​
max_source_bytes
integer
Maximum deploy source size: 256,000 UTF-8 bytes.
​
eval_requires_env
string
The environment variable required to enable eval: "REALM_LUA_EVAL=1".
​
eval_max_bytes
integer
Maximum eval chunk size: 8,192 bytes.

​
POST /code/validate

Statically validates a Lua source string — checks size and shape only, does not execute the code. 
curl -X POST http://localhost:8000/code/validate \
  -H "Content-Type: application/json" \
  -d '{"source": "local x = 1 + 1\nreturn x"}'
​
ok
boolean
true if the source passes static validation.
​
bytes
integer
UTF-8 byte count of the source.
​
lines
integer
Line count of the source.
​
chars
integer
Character count of the source.

​
POST /code/deploy

Deploys a Lua source string for a party. Validates size first, then stores the source in world.deployed_lua_sources. This is a Phase 4 staging endpoint; execution is separate and gated. 
curl -X POST http://localhost:8000/code/deploy \
  -H "Content-Type: application/json" \
  -d '{"party": "player", "source": "local inv = realm.inventory(\"player\", \"iron\")\nif inv.qty < 50 then realm.market_bid(\"player\", \"iron\", 50, 1500) end"}'
​
ok
boolean
true on success.
​
party
string
The party the source was deployed for.

​
POST /code/eval

Runs a Lua chunk and returns the result. Requires REALM_LUA_EVAL=1 environment variable and the lupa Python package. 
REALM_LUA_EVAL=1 curl -X POST http://localhost:8000/code/eval \
  -H "Content-Type: application/json" \
  -d '{"source": "return 1 + 1", "tick": 42, "purpose": "api"}'
​
ok
boolean
true on success. false if the env var is missing, lupa is not installed, or the chunk errors.
​
result
any
The return value of the Lua chunk (present when ok is true).
​
reason
string
Error message (present when ok is false).

​
LLM Agents

​
GET /llm/status

Returns the LLM agent session status: model, spend, token counts, and per-agent summaries. 
curl http://localhost:8000/llm/status
​
client_ready
boolean
Whether an Anthropic API client is configured.
​
model
string
The default model in use (e.g. claude-haiku-4-5).
​
session_cap_micro_usd
integer
Session spend cap in micro-dollars (1 = $0.000001).
​
session_spend_micro_usd
integer
Cumulative session spend in micro-dollars.
​
session_remaining_micro_usd
integer | null
Remaining budget in micro-dollars, or null if no cap is set.
​
agents
array
Per-agent summaries: party, display_name, last_plan_tick, memory_preview.

​
POST /llm/step

Runs one planning step for a named Tier 3 LLM agent. The agent reads the current world state, decides on actions, and executes them. Requires ANTHROPIC_API_KEY to be set.
​
party
string
required
The party ID of the LLM agent to step.
curl -X POST "http://localhost:8000/llm/step?party=elara_voss"
​
ok
boolean
true on success. Returns HTTP 503 if no Anthropic client is configured.

​
Dev

​
POST /dev/reset

Destroys the current in-memory world and bootstraps a fresh one from a named scenario and seed. For development use only — this is irreversible for the current session.
​
scenario
string
Scenario name. One of: frontier, cartel, bootstrapper, speculator, millrace, archive, genesis. Defaults to "frontier".
​
seed
integer
RNG seed for world generation. Defaults to 42.
# Reset to default frontier scenario
curl -X POST http://localhost:8000/dev/reset

# Reset to cartel scenario with a specific seed
curl -X POST "http://localhost:8000/dev/reset?scenario=cartel&seed=99"
​
ok
boolean
true on success.
​
seed
integer
The seed used to generate the new world.
​
scenario_id
string
The active scenario name after reset.

Build docs developers (and LLMs) love

Get started for freeTalk to us