Documentation: 0.5.0 (source: v0.5.0).
# Markets

> Local and faction markets, order books, and why the same resource costs different amounts in different places.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/markets/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

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.

:::game[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

```ts
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.

> **Runnable example — Read the markets of a system.** List the local markets of a system and inspect one order book. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/markets/.

## 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:

```ts
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.

:::caution[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](/start-here/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`](/reference/markets/) — every export in this entry
- [`world`](/guides/world/) — markets belong to systems
- [`cargo`](/guides/cargo/) — what is being traded