# Markets
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

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

Markdown source of https://develop.atlas-kit-docs.pages.dev/guides/markets/ — see https://develop.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://develop.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.

## Placing an order

Joining an order book is a write: you post what you will buy or sell, at your
price, from your own state at that market's starbase. If this would be your
first write, read [How Atlas Kit changes the
game](/start-here/how-it-acts/) first.

`planPlaceLocalMarketOrder` takes the market, your state at its starbase, and
the order itself — the side, a price per unit, and a quantity, both as the
same raw `bigint` amounts you read:

```ts
import type { PlanAuthorization } from '@aephia/atlas-kit/markets/actions';
import { planPlaceLocalMarketOrder } from '@aephia/atlas-kit/markets/actions';

const authorization = {
  profile: character.profile.address,
  authority: authoritySigner.address,
  keyIndex: 0,
} satisfies PlanAuthorization;

const held = base.cargo.items.find((item) => item.id === market.cargo.id);
if (held !== undefined && held.quantityRaw > 0n) {
  const plan = await planPlaceLocalMarketOrder(ctx, market, base, {
    authorization,
    side: 'ask',
    priceRaw: 25_000_000n,
    quantity: 1n,
  });
  console.table(plan.describe());
}
```

Selling requires holding what you sell — the snippet checks the starbase
storage for the market's resource first, which is also why placing an order
starts from your starbase state rather than from the market alone. If you
have no state at that starbase yet, [register
there](/guides/starbases/#registering-at-a-starbase) first.

The planner proves what it can from current state — the market matches the
starbase, the order's numbers are valid — and the order book itself decides
matching when the Plan executes. Remember the caution above: this is the one
surface where other players are actively racing you, so plan against fresh
reads and expect the book to have moved. Signing and executing works exactly
as in [Warp & subwarp](/guides/moving-a-fleet/#sign-and-execute-once).

:::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
- [`markets/actions`](/reference/markets/actions/) — the order planner
- [`world`](/guides/world/) — markets belong to systems
- [`cargo`](/guides/cargo/) — what is being traded