Markets

There are two kinds of market, and they answer different questions.

A local market belongs to a star system and has an order book: people posting what they will buy or sell and at what price. A faction market offers goods on faction terms rather than through player orders.

Every starbase has its own market

Each starbase has its own market. Players choose what they are willing to pay or accept there, and trades happen when a buyer and seller agree. That means the game does not set one price for the whole galaxy. A resource can be cheap where it is plentiful and expensive where it is scarce, especially because moving goods between starbases takes time and fuel.

Reading a local market

const markets = await system.localMarkets.all();
const forOre = await system.localMarkets.forCargo(cargoId);

forCargo is the one you usually want: markets are per-resource, so asking “what is the market for this cargo in this system” is the natural question.

Order books have sides

An order book is not a price. It is a set of orders, each with a quantity and a price — and the two sides are separate reads rather than one list you filter:

const buying = market.bids;
const selling = market.asks;

They are modelled apart because the data available on an order depends on its side: maker state differs between buying and selling. Flattening them would mean a single shape with half its fields undefined at any time.

Prices are local

The same resource can trade at different prices in different systems, and that is a feature of the game rather than stale data. Moving goods between systems where prices differ is a strategy, not an arbitrage bug.

So there is no such thing as the price of a resource. There is a price at a market, at a moment.

Market data ages faster than most reads

Most SAGE state changes on a timescale of minutes. Market orders do not — they are the one place where another player is actively racing you.

If you are showing prices, use a short maxAge, and treat anything you read as a snapshot rather than a current quote. See setting up your RPC for how freshness is configured.

Gotchas

An empty order book is normal. A market with nobody trading in it exists and returns nothing. That is not a missing read.

Prices are raw integers. Like all amounts, they need the cargo definitions to render meaningfully, and they are bigint.

Faction markets are not order books. Do not expect the same shape. They offer goods rather than matching player orders.

Reference

• markets — every export in this entry
• world — markets belong to systems
• cargo — what is being traded