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.

Realm has two trading mechanisms, and they coexist in the same world at the same time. Direct peer-to-peer trades handle one-off or off-book deals between two players who’ve already agreed on terms. Order books emerge organically for any commodity that reaches sufficient trading volume. Neither is more “real” than the other — which one you use depends on what you’re trying to do and who you’re trading with.
Prices in Realm emerge entirely from player and AI agent activity. There is no “market price” set by the game designers. The numbers you see in the order book are what participants have chosen to bid and ask — and they move because Tier 1 and Tier 2 agents are actively trading in the background, even when you’re not.

​
P2P direct trades (Primitive 7a)

A P2P trade is atomic and mutual: seller delivers goods, buyer delivers money, in one indivisible operation. Use P2P when:
  • You’ve already negotiated a price out-of-band (via messages)
  • The commodity doesn’t have a thick enough order book to get a good fill
  • You want to set non-standard terms (e.g., bundle multiple materials)
  • You prefer to trade with a specific counterparty rather than whoever is on the book
P2P trades are idempotent when you include an idempotency_key: resubmitting the same key with the same parameters replays the stored outcome without double-settling. 
curl -X POST "http://localhost:8000/trade/p2p?seller=alice&buyer=bob&material=clay&qty=100&total_price_cents=5200&idempotency_key=alice-bob-clay-deal-001"
Both parties must be online and the buyer must have sufficient cash. The engine validates material availability on the seller’s side and cash availability on the buyer’s side before executing.

​
Order books (Primitive 7b)

An order book emerges automatically for any commodity that reaches the volume threshold: 5 or more distinct sellers posting orders in the past 30 game-days. Below that threshold, the commodity trades only via P2P. Above it, an open limit-order book is live and visible to all participants. Order books use price-time priority: at the same price level, older orders (lower order_id sequence numbers) fill first. Incoming orders cross against the best available resting orders immediately on submission.

​
Place a limit sell order (ask)

Your material is removed from inventory and placed on the book. It stays there until filled, cancelled, or you go bankrupt. 
curl -X POST "http://localhost:8000/market/sell?party=player&material=clay&qty=200&price_per_unit_cents=55&iceberg_display_qty=50&min_counterparty_honored=3"
iceberg_display_qty is optional — see iceberg orders below. min_counterparty_honored is optional — see reputation gating.

​
Place a limit buy order (bid)

Cash equal to qty × max_price_per_unit_cents is locked in market escrow immediately. Unused escrow is returned when the order cancels or when fills come in below your limit. 
curl -X POST "http://localhost:8000/market/bid?party=player&material=copper&qty=50&max_price_per_unit_cents=120"

​
Market buy (aggressive)

Walk the lowest-priced asks and buy up to max_qty. Fills at each ask price as it goes. Stops when your quantity is filled, you run out of cash, or the book is empty. 
curl -X POST "http://localhost:8000/market/buy?party=player&material=timber&max_qty=30&min_seller_honored=0"

​
Sell into bids (aggressive)

Walk the highest resting bids and sell up to max_qty. The mirror image of market buy — you receive bid prices, goods are removed from your inventory. 
curl -X POST "http://localhost:8000/market/sell_fill?party=player&material=clay&max_qty=100&min_buyer_honored=0"

​
Cancel a sell order

Returns the unsold material to your inventory. 
curl -X POST "http://localhost:8000/market/cancel?party=player&order_id=ord-142"

​
Cancel a bid order

Returns the escrowed cash to your account. 
curl -X POST "http://localhost:8000/market/cancel_bid?party=player&order_id=ord-143"

​
Iceberg orders

An iceberg order shows only a portion of your total quantity on the public book. When the visible portion (iceberg_display_qty, called the “peak”) fills completely, the hidden portion automatically replenishes the peak. This lets large players avoid moving the market by revealing their full size. To use icebergs, set iceberg_display_qty to any value between 1 and qty - 1 when placing an ask or bid. Example: you want to sell 1,000 clay but only want 100 visible at a time: 
curl -X POST "http://localhost:8000/market/sell?party=player&material=clay&qty=1000&price_per_unit_cents=54&iceberg_display_qty=100"
The public book shows 100 units. When those 100 fill, the next 100 from the hidden reserve appear at the same price. Counterparties can see qty_total_remaining in the full order book response if they query the API directly — the iceberg isn’t fully opaque — but casual market screen viewers will only see the peak size.

​
Reputation gating

Both asks and bids accept min_counterparty_honored, an integer threshold. If set, an order will only cross against counterparties whose cumulative honored reputation count meets or exceeds your minimum. Both sides’ minimums must be satisfied for a match to execute. This lets established players avoid trading with counterparties who have a history of breaches, while new players can still fill orders from anyone willing to trade with them (by setting min_counterparty_honored: 0). Reputation is incremented on both sides of every filled spot trade and every fulfilled contract. It is never decremented — but breach counts accumulate separately, and anyone can query your public reputation record.

​
Market intelligence

Historical price data beyond the most recent ticks costs in-game currency. If you’re building a trading strategy or advising a client, budget for intelligence purchases. The information advantage from longer historical series can be worth many times the purchase price.
The public order book shows current resting bids and asks. To query deeper history, purchase market intel: 
curl -X POST "http://localhost:8000/market/intel?party=player"
The fee ($250.00 in-game) is deducted from your account and market_intel_expires_tick is extended by 500 ticks. While intel is active, GET /world returns the full market_history array instead of the truncated 48-tick free window. Use this extended history to identify trends, calculate moving averages, or detect when a large player (like Rico the Speculator) is accumulating a position.

​
How the two mechanisms interact

P2P trades and order book fills both trigger the same reputation increment — every successful exchange, regardless of mechanism, adds to both parties’ honored count. This means P2P trading with trusted counterparties builds the same reputation score as open-market fills. If you’re a market-maker, you’ll primarily use the order book. If you’re a shipper negotiating a long-term delivery rate, you’ll combine P2P with supply contracts. If you’re a speculator watching for mispricings, you’ll use aggressive market buys and fills. All mechanisms are available simultaneously; you decide which fits the situation.

Contracts

Lock in prices and delivery schedules with supply, loan, and service contracts.

Building a business

See how market-making and trading fit into larger business archetypes.

AI agents

Understand how Tier 1 and Tier 2 agents interact with the order books.

Engine API reference

Full parameter documentation for every market endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us