Markets

Every territory capital has a market where villages buy and sell goods for gold. Prices follow the market's stock: sell a lot of something and its price drops, buy a lot and it climbs, and over time stocks drift back towards their normal level. Trades travel by cart, so the price is locked in when you send them, and the gold or goods arrive when the carts get home. The same carts carry caravans between villages, yours or another lord's (see Caravans).

Lords also trade with each other: standing orders at every market (Lords' orders), delivery contracts (Delivery contracts), and carts that lords at war can rob on the road unless an escort beats the raiders off (Carts on the road). The Trade ledger tab of the inbox sums up what you bought and sold over the last 7 days (Trade ledger).

Times on this page are game time at world speed 1. Faster worlds shorten cart trips and stock recovery in real time.

The basics

• You can trade at your own territory's capital and at any other capital within 30 cells of your village.
• Every good has a base price. When the market's stock is at its target the price is the base price; below target it is higher, above target lower, between a quarter and four times base.
• Buyers pay 8 percent over the curve and sellers get 8 percent under it.
• The territory holder takes a market tax on each trade (3 percent by default, up to 10).
• Each cart carries 100 units at first and up to 1,000 with Commerce research. A village has 2 carts at first, more with rank and with staffed trade posts.
• Carts travel at 48 cells per game hour (a capital 12 cells away is a quarter hour each way), faster with Roads and Riders research and cart cards. They make the round trip, and the trade completes when they are home.
• Severe weather slows carts crossing affected territories. See Weather.

Goods and base prices

Good	Base price (gold)	Good	Base price (gold)
Wood	1	Apples	1
Stone	1.5	Cheese	1.4
Iron	4	Meat	1.5
Pitch	3	Vegetables	1.2
Charcoal	2.5	Fish	1.2
Salt	3.5	Bread	1.8
Wheat	0.8	Ale	3
Flour	1.6	Wine	6
Hops	1.5

Gold, weapons and anything else not in this table cannot be traded at markets.

Target stock and local prices

Each market has a target stock for every good, set by the territory's biome (its most common biome, see Lands and territories):

target = round(1500 * clamp(productivity, 0.4, 2.5))

productivity is the biome's multiplier for that good from Biomes, 1 when the biome lists none. A new market starts with every good at its target.

Example	Productivity	Target
Iron at a Mountain Foothills market	1.9	2,850
Iron at a Highlands market	1.3	1,950
Iron at a Greenvale Plains market	0.5	750
Wine at a Sunlit Vinelands market	1.9	2,850
Wine at a Highlands market	0.5	750
Wine at a Mountain Foothills market	0.4	600
Wood at a Greenvale Plains market	none listed, so 1	1,500

An important detail: at rest, when stock equals target, every market quotes the base price. The biome does not make a good cheaper at a resting market. It sets how deep the market is. A market with a high target absorbs big trades with less price movement, so selling 400 iron in the mountains pays more than selling it on the plains, and buying 300 iron costs less in the mountains (worked out below).

The price curve

The mid price of one unit at the current stock:

price = base * clamp((target / max(1, stock)) ^ 0.8, 0.25, 4)

With an elasticity of 0.8, halving the stock raises the price by 2^0.8 = 1.74 times. The 4x ceiling is reached when stock falls to target / 4^(1/0.8) = target / 5.66, about 265 for a 1,500 target. The 0.25x floor is reached at target * 5.66, about 8,485 for a 1,500 target.

Worked example: wood at a plains market with stock 1,100 against a target of 1,500. (1500 / 1100)^0.8 = 1.3636^0.8 = 1.282, so the mid price is 1 * 1.282 = 1.28 gold.

What a trade pays

A trade does not use one price. It pays the area under the curve from the stock before the trade to the stock after it (computed with Simpson's rule in 16 steps), so every unit in a big trade is priced at the stock level it moves through.

sale value    = floor(area(stock, stock + amount) * (1 - spread))
purchase cost = ceil(area(stock - amount, stock) * (1 + spread))
spread        = 0.08 x (1 - market cut research)

The market cut research comes from the Commerce branch and reaches 70% with all of it, so the spread falls from 8% to 2.4% (research.md).

Then the holder's market tax:

seller receives = saleValue - round(saleValue * marketTax)
buyer pays      = purchaseCost + ceil(purchaseCost * marketTax)

Worked example 1, selling 100 wood at a resting plains market (target 1,500, stock 1,500, base 1, default 3 percent tax):

1. The area from stock 1,500 to 1,600 is 97.44 (prices slide from 1.00 down to 0.95).
2. Sale value: floor(97.44 * 0.92) = floor(89.64) = 89.
3. Tax: round(89 * 0.03) = round(2.67) = 3.
4. You receive 86 gold, and the market's wood stock is now 1,600.

Worked example 2, buying 100 wood at the same resting market:

1. The area from stock 1,400 to 1,500 is 102.78 (prices from 1.06 down to 1.00).
2. Purchase cost: ceil(102.78 * 1.08) = ceil(111.0) = 112.
3. Tax: ceil(112 * 0.03) = ceil(3.36) = 4.
4. You pay 116 gold.

So a round trip of 100 wood at a resting market loses you 30 gold: 116 out, 86 back.

Worked example 3, market depth. Buying 300 iron at a resting market, before tax:

Market	Target	Area	Cost ceil(area * 1.08)	Mid price afterwards
Greenvale Plains	750	1,456.79	1,574	6.02
Mountain Foothills	2,850	1,253.97	1,355	4.37

Selling 400 iron at a resting market, before tax, gets 1,231 gold on the plains and 1,395 in the mountains. Iron is worth hauling to the mountains to sell and buying there, even though both markets quote 4 gold at rest.

Splitting a trade into smaller lots back to back does not help: the tests check that one sale of 200 equals two sales of 100 in a row, within 1 gold of rounding. Waiting between lots does help, because the stock drifts back in between.

Stock recovery

Stocks drift back towards their target over time:

stock(t) = target + (stock - target) * e^(-gameHours / 18)

After 18 game hours, e^-1 = 0.368 of the gap remains, so about 63 percent has closed. The code comments describe this as "two thirds", which is a rounding of the real figure.

Worked example: you sold 400 wood into a plains market, taking it from 1,500 to 1,900.

Time after the sale	Stock	Mid price
0 h	1,900	0.83
6 h	1,787	about 0.87
18 h	1,647	about 0.93

Stock never overshoots the target in either direction. A market is only created when someone first opens or trades at it. After that it keeps recording one price sample per game hour, keeping the last 48 for the price chart.

Carts

How many

carts = cartsByRank[min(rank, 12)] + 2 * (staffed trade posts) + carts from research

Rank	0	1	2	3	4	5	6	7	8	9	10	11	12+
Carts	2	2	3	3	4	4	5	5	6	6	7	7	8

A Trade Post (rank 3, needs the Trade Routes research, at most 2 per village, costs 150 wood, 50 stone and 200 gold) adds 2 carts while it is finished and has a worker. A village at rank 12 with two staffed trade posts has 8 + 4 = 12 carts. Commerce research adds up to 5 more carts in every village. Carts are counted per village. Carts on the road count against the village until they are home, whether they went to market or out with a caravan.

Capacity

Each cart carries 100 units, round(100 x (1 + cart load research)) with Commerce research: Wagon Wrights +50, Ox Wains +100, Great Wains +150, Caravan Masters +200 and Wagon Trains +400, so 1,000 with all of them. A trade needs ceil(amount / load) carts, so at 100 a cart 101 units take 2 carts and 200 units also take 2. Trade in multiples of the load to waste no capacity. The trade fails if you do not have enough free carts.

The market and Caravans panels share one amount picker: preset amounts (10, 100, 500, 1,000 and 5,000), a box to type any amount, a cart count with - and + that loads whole carts, and Fill all carts, which loads every free cart. The cart count turns red when the amount needs more carts than are free.

Range

You may trade at:

• your own territory's capital, however far it is, and
• any capital within 30 cells, plus up to 20 more from Commerce research, measured in a straight line from your village's site to the capital.

Travel

Carts go from your village to the capital at their pace and come back by the same route in the same time. The pace is set when they set out, and rises for carts already on the road when a cart card is played or cart research finishes (cards-and-crowns.md):

pace = 48 x (1 + cart research) x cart card factors        (cells per game hour)

Cart research adds up to +400% across the Roads and Riders branch (research.md). Each cart speed card in play is its own factor, and copies stack. While Smugglers' Tunnels or The Wind Road runs, every trip takes the minimum of one game minute each way. Shepherd's Shortcut and All Roads Lead Home finish trips already on the road at once. See cards-and-crowns.md.

one way (real ms) = max(60 000, cells / pace * 3 600 000) / worldSpeed

Worked example: a capital 18 cells away is 22.5 game minutes each way at the base pace of 48, 45 minutes for the round trip. At the 30-cell limit the round trip is 1 hour 15 minutes. With the whole Roads and Riders cart line (pace 48 x 5 = 240), the same 18 cells take 4.5 game minutes each way.

Severe weather slows carts crossing affected territories; see Weather.

Order of events

When selling, the goods leave your village at once, the market's stock rises at once, and the price and tax are fixed then. The gold arrives in your treasury when the carts are home. The treasury has no cap, so nothing is lost.

When buying, you pay the full price plus tax at once and the market's stock falls at once. The goods arrive with the carts. You cannot buy more than the market holds minus 1 unit, and the server refuses a purchase that would not fit your storage, counting goods already on their way from earlier purchases. If storage has filled in the meantime, the excess is lost on arrival.

Market tax is paid to the territory holder when the carts set off, not when they return (see Lands and territories). After a capital is taken by force, its new owner is the holder and gets the tax (see Taking a capital). The market panel shows the rate you would pay.

Caravans

A caravan sends one good from the village you have open to any other village on the map: one of your own, or a gift to another lord. Open it with Send a caravan in the village panel, or with Send cart on a village's card on the World map.

Send cart shows on the card of every village except the one you have open: your other villages, and the villages of lords you are not at war with. It does not show on an enemy's village, meaning a lord on the far side of a war with you or your guild, order, house or kingdom, or one your Spymaster has marked (the same lords the map marks as enemies). Beside the button the card says which village the carts leave from, how many of its carts are free, the load per cart and the time each way. The button opens the Caravans panel with that village already chosen as the destination; pick the good, the amount and any escort there as usual.

• Any good the village stores can go, gold and weapons included.
• It uses the village's market carts, ceil(amount / 100) of them, and fails if not enough are free.
• There is no range limit. Carts travel at the same pace as market carts (48 cells per game hour before research and cards) in a straight line, slowed by severe weather like market carts.
• The goods leave the sending village at once.
• When the carts arrive, the goods are unloaded into the receiving village. Anything over its storage at that moment is lost.
• The send is refused if the receiver's store has no room for it, counting caravans of the same good already on their way there. Room can still fill up before they arrive.
• The carts then drive home empty and are free again once they are back, so a caravan ties up its carts for the round trip.
• When another lord's caravan is unloaded at one of your villages, you are told who sent what.
• On the map a caravan uses the wagon marker. Its tooltip says where it is going, or that the carts are coming home empty.

Worked example: you send 250 wood to your second village 24 cells away. That takes 3 carts. The wood leaves at once, arrives after 2 game hours, and the carts are free again after 4.

Nothing stops you sending goods to a lord you are at war with: the map card leaves Send cart off enemy villages, but the Caravans panel still lists them.

Caravans and market carts can take an escort: see Carts on the road. A caravan sent for a delivery contract is sent from the contract (see Delivery contracts).

Lords' orders

Below the market's own goods, the market panel shows the order book: standing offers and bids that lords have posted there, with the market's own price beside each good for comparison.

Posting an order

Pick Offer or Bid for, an amount, a good, a price per unit and a lifetime (3, 5 or 7 game days), then Post. You post from the village selected at the top of the panel, which must be able to reach the market, and the market must be open.

• An offer takes the goods from that village at once. They are held at the market while the order stands.
• A bid holds gold in escrow at once: ceil(amount x price) plus the holder's market tax on that, rounded up, at the rate in force when you post.
• Prices must lie between 0.2 and 5 times the good's base price (iron: 0.80 to 20 gold).
• A lord may have 8 orders open across all markets.

A new order first trades against any standing order it crosses, best price first and oldest first at one price, and always at the standing order's price. An offer at 4 meets bids at 4 or more; a bid at 5 meets offers at 5 or less. You never trade with your own orders. Whatever is left stands in the book.

Taking an order

Any other lord can take all or part of a standing order with the amount box and the Buy or Sell button next to it. This works like a trade with the market: it needs free carts at the selected village (ceil(amount / cart load)), and

• buying from an offer pays now and the goods come home with the carts, which needs room in your storage, counting goods already on their way;
• selling into a bid sends your goods now and the gold comes home with the carts.

Tax and payment

The territory holder's market tax is taken from both sides of every fill, the same way as a trade with the market: the seller pays it out of the value and the buyer pays it on top. A standing order pays at the rate in force when it was posted, a lord taking it at the rate in force now.

value      = round(amount x price)
seller gets = value - round(value x seller's rate)
buyer pays  = value + ceil(value x buyer's rate)

Worked example: Aldric offers 300 iron at 4.50 at a market with 3 percent tax. Berenga bids for 100 iron at 5.00. Her bid crosses his offer, so 100 iron trade at once at Aldric's 4.50:

1. Value round(100 x 4.5) = 450.
2. Aldric gets 450 - round(13.5) = 436 gold, paid into his treasury at once.
3. Berenga pays 450 + ceil(13.5) = 464 gold out of her escrow of 500 + 15 = 515. Her bid is filled, so the 51 gold left in escrow comes back to her treasury.
4. The holder is paid 28 gold.
5. Aldric's offer stands with 200 iron left.

Goods held at the market

Goods a standing bid receives, and goods left over when an offer is cancelled or expires, are held at the market for you. The panel shows them under Held for you here, with a Send carts button. The carts take as much as your free carts and storage allow and bring it home like a purchase. Held goods do not expire.

Cancelling and expiry

Cancel withdraws one of your orders at once. An order that reaches the end of its lifetime expires. Either way, the unsold goods of an offer stay at the market in your holdings and the unspent escrow of a bid goes back to the treasury of the village it was posted from. The inbox records every post, fill, cancellation and expiry.

The panel also lists the last trades between lords at that market, newest first.

Delivery contracts

A delivery contract offers gold for goods carried to one of your villages by a deadline. Post one from the market panel's Post a contract form: the good, the amount, the deadline (24, 48 or 72 game hours from acceptance) and the reward. The goods go to the village selected at the top of the panel.

• Leave the lord's name empty to post the contract publicly at that market; any lord who opens the market sees it. Or type a lord's name to address it to them alone.
• The reward is held in escrow at once. The smallest reward is 10 gold. A lord may have 5 contracts posted and unfinished, and carry 3 at a time.
• An unaccepted contract lapses after 3 game days and the reward comes back. You can withdraw it before anyone accepts.

The contractor accepts, and their deadline starts then. They send the goods by caravan from the Delivery contracts panel (open it from the market panel or the Caravans panel), from any of their villages, with an escort if they like. A contract caravan must carry the contracted good to the contracted village, and no more than is still due counting caravans already on the road.

When every unit has been unloaded at the poster's village before the deadline, the reward is paid to the treasury of the village that sent the last caravan. Goods that arrive after the deadline are still unloaded but do not count.

If the deadline passes before everything has arrived, or the contractor gives the contract up, the contract fails:

• the poster gets the whole reward back and keeps whatever was delivered;
• the contractor loses round(10 + 0.05 x reward) Renown, never more than they have.

Worked example: Berenga posts 200 stone to Berenholm within 48 hours for 450 gold. Aldric accepts and sends 200 stone. If it all arrives within 48 game hours of his accepting, he is paid 450 gold. If a raid on the road takes the stone and the deadline passes, Berenga gets her 450 gold back and Aldric loses round(10 + 22.5) = 33 Renown.

Contracts are not taxed. Both sides get an inbox entry at every step: posted, offered, accepted, each delivery, fulfilled, failed, lapsed or withdrawn.

Carts on the road

Escorts

Market carts, collections and caravans can take an escort: soldiers at home in the village and off the castle walls. Pick them in the Escort section of the market panel, the Caravans panel or the Delivery contracts panel. The escort leaves with the carts, still counts against the village's troop cap, defends the carts if they are attacked, and comes home with them. The carts slow to the slowest soldier's march speed if that is slower than the carts (most foot soldiers march at 11 or 12 cells per game hour, a quarter of an unresearched cart's 48, so an escort turns a quarter-hour trip into an hour).

Attacking carts

Another lord's carts and caravans are on the World map with the wagon marker. Clicking them opens a panel with a Send scout button. A scout heads for where the carts will be when it gets there and reports what they carry (goods, or gold on a purse or a sale coming home) and the escort. Everyone can see where carts are going; only a scout counts the escort.

If you are at war with the owner (the same rule as attacking their village, see Military) and they are out of peacetime, the panel then offers an attack like a merchant caravan: the army marches to where the carts will be when it arrives, and the escort fights as defenders around the wagons. Attacking carts ends your own peacetime.

• If the attackers win, they take as much of the cargo as the survivors can carry, plus 20 Renown. The rest is lost on the road. The carts turn round and come home empty, with any surviving escort. A sale's gold and a purchase's goods are lost, a caravan delivers nothing, and contract goods do not count.
• If the escort wins, the carts carry on with the survivors of the escort.

Both lords get a battle report in the inbox, and the owner gets a trade entry when an army sets out after the carts and when the carts are robbed.

Trade ledger

The Trade ledger tab of the inbox opens with a summary of the last 7 game days: per good, how much you bought and for how much gold, how much you sold and for how much, and the net gold (earned less spent, tax included). Trades with the market, fills of lords' orders and fulfilled contracts all count; robbed carts and caravans between villages do not.

Interactions

• Automation: premium lords can have villages sell surpluses here on a timer, as ordinary trades, and send caravans between their own villages to keep goods between levels (auto-transport).
• Realm events: the market of a capital sacked by an event's host or held by rebels is shut until the event ends.
• Lands and territories: who holds a capital and sets its market tax.
• Biomes: productivity values that set target stocks.
• Village: storage limits on what carts can bring home.
• Ranks and renown: carts by rank.
• Research: Trade Routes, which unlocks the Trade Post.
• World map: capitals and carts on the map.
• Weather: carts slowed by severe weather.
• Military: attacking carts on the road, and escorts.
• Guilds and Houses: wars, which decide whose carts you may attack.
• Inbox: the Trade ledger tab.

For maintainers

Source files:

• server/src/features/market/content.ts: marketContent (goods and base prices, targetStock 1500, elasticity 0.8, minFactor 0.25, maxFactor 4, spread 0.08, driftHours 18, cartLoad 100, cartsByRank, cartCellsPerHour 48, reach 30, historyPoints 48).
• server/src/features/market/index.ts: targetStock (productivity clamped to 0.4..2.5), market (drift and hourly history), canReach, trade, sendCaravan and deliver (caravans, cart kind send), moveCarts. Open markets are pushed to viewers every 30 s real time. Saved under meta key market.
• packages/protocol/src/features/market.ts: unitPrice, saleValue, purchaseCost (Simpson's rule, n = 16), driftStock, cartsAllowed.
• packages/protocol/src/index.ts: villageExtraCarts (counts buildings not queued or constructing with at least one worker).
• server/src/content/index.ts: biome productivity, trade_post building (carts: 2, maxCount: 2).
• server/src/features/world/travel.ts: travelMs.
• server/src/features/market/content.ts: exchange (maxOpenOrders 8, orderDays 3/5/7, priceBand 0.2..5, fillsKept 20, contracts: openDays 3, deadlineHours 24/48/72, maxPosted 5, maxTaken 3, minReward 10, failRenown 10 + 0.05 x reward, ledgerDays 7).
• server/src/features/market/book.ts: pure rules: crossing, settle, escrowFor, summarizeLedger.
• server/src/features/market/exchange.ts: orders, holdings, contracts and the ledger, saved under meta key market_exchange.
• server/src/features/market/index.ts: dispatchCart, checkEscort, cargoOf, cartFought; the cartApi seam (registry.ts) used by scouting (world/live.ts) and armies (military/index.ts, target type cart, layout convoyLayout in military/pieces.ts). Escorts are left out of the public tradeCarts list.
• clients/web/src/features/caravans/index.ts: the caravan panel, and the Send cart block it adds to village cards through vk:site-panel. vk:open-caravans takes an optional toVillageId to open the panel aimed at that village. Enemies come from the social feature's vk:enemies event.
• clients/web/src/features/trade/: the order book and contracts in the market panel (vk:market-panel), the Delivery contracts panel (vk:open-contracts), another lord's cart panel (vk:open-cart, then vk:cart-panel for the military Attack block) and the escort picker.
• Tests: server/src/features/market/market.test.ts, server/src/features/market/exchange.test.ts.