markets

Interfaces

FactionMarketOfferSnapshot

Defined in: packages/sage/src/markets/index.ts:243

One cargo offer in a Faction Market.

Example

declare const offer: FactionMarketOfferSnapshot;
console.log(offer.name, offer.priceAtlas);

Extends

• CargoDefinitionSummary

Properties

canBuyFromFaction

readonly canBuyFromFaction: boolean;

Defined in: packages/sage/src/markets/index.ts:244

canSellToFaction

readonly canSellToFaction: boolean;

Defined in: packages/sage/src/markets/index.ts:245

categoryId

readonly categoryId: number;

Defined in: packages/sage/src/registry/index.ts:119

Inherited from

CargoDefinitionSummary.categoryId

id

readonly id: number;

Defined in: packages/sage/src/registry/index.ts:120

Inherited from

CargoDefinitionSummary.id

mint

readonly mint: Address;

Defined in: packages/sage/src/registry/index.ts:121

Inherited from

CargoDefinitionSummary.mint

name

readonly name: string;

Defined in: packages/sage/src/registry/index.ts:122

Inherited from

CargoDefinitionSummary.name

priceAtlas

readonly priceAtlas: number;

Defined in: packages/sage/src/markets/index.ts:247

priceRaw

readonly priceRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:246

remainingQuantityRaw

readonly remainingQuantityRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:248

storageCost

readonly storageCost: number;

Defined in: packages/sage/src/registry/index.ts:127

Encoded storage cost with 8 fractional bits: 256 means one whole storage unit. For a nonnegative bigint quantity, use (quantity * BigInt(storageCost) + 255n) / 256n. Round each transfer row up before summing; Fleet capacities and pod usage are whole units.

Inherited from

CargoDefinitionSummary.storageCost

---

FactionMarketSnapshot

Defined in: packages/sage/src/markets/index.ts:258

Immutable Faction Market configuration, lifecycle, and offers snapshot.

Example

declare const market: FactionMarketSnapshot;
console.log(market.status, market.offers);

Extends

• Omit<FactionMarketAccountData, "game" | "offers" | "system">

Extended by

• FactionMarketView

Properties

address

readonly address: Address;

Defined in: packages/sage/src/markets/index.ts:263

atlasBurnBasisPoints

readonly atlasBurnBasisPoints: number;

Defined in: packages/sage/src/internal/c4/market.ts:123

Inherited from

Omit.atlasBurnBasisPoints

authoredTargetQuantityRaw

readonly authoredTargetQuantityRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:120

Inherited from

Omit.authoredTargetQuantityRaw

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/market.ts:111

Inherited from

Omit.bump

factionId

readonly factionId: number;

Defined in: packages/sage/src/internal/c4/market.ts:113

Inherited from

Omit.factionId

faucetEnabled

readonly faucetEnabled: boolean;

Defined in: packages/sage/src/internal/c4/market.ts:125

Inherited from

Omit.faucetEnabled

game

readonly game: EntityRef<"game">;

Defined in: packages/sage/src/markets/index.ts:264

kind

readonly kind: "factionMarket";

Defined in: packages/sage/src/markets/index.ts:262

lastRestockedAtUnixSeconds

readonly lastRestockedAtUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:122

Inherited from

Omit.lastRestockedAtUnixSeconds

minimumStandingToBuy

readonly minimumStandingToBuy: number;

Defined in: packages/sage/src/internal/c4/market.ts:117

Inherited from

Omit.minimumStandingToBuy

minimumStandingToSell

readonly minimumStandingToSell: number;

Defined in: packages/sage/src/internal/c4/market.ts:118

Inherited from

Omit.minimumStandingToSell

offers

readonly offers: readonly FactionMarketOfferSnapshot[];

Defined in: packages/sage/src/markets/index.ts:266

priceTierBasisPoints

readonly priceTierBasisPoints: readonly number[];

Defined in: packages/sage/src/internal/c4/market.ts:119

Inherited from

Omit.priceTierBasisPoints

restockPeriodSeconds

readonly restockPeriodSeconds: number;

Defined in: packages/sage/src/internal/c4/market.ts:121

Inherited from

Omit.restockPeriodSeconds

standingBasisPoints

readonly standingBasisPoints: number;

Defined in: packages/sage/src/internal/c4/market.ts:124

Inherited from

Omit.standingBasisPoints

starbaseSequenceId

readonly starbaseSequenceId: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:115

Inherited from

Omit.starbaseSequenceId

status

readonly status: "active" | "draft" | "removed";

Defined in: packages/sage/src/internal/c4/market.ts:116

Inherited from

Omit.status

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/markets/index.ts:265

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/market.ts:110

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/markets/index.ts:267

Returns

unknown

---

LocalMarketMakerAssets

Defined in: packages/sage/src/markets/index.ts:115

Observed locked principal and released proceeds for one Local Market maker row.

These values classify the row’s stored amounts. Released amounts do not establish withdrawal availability or predict a future transfer.

Example

declare const assets: LocalMarketMakerAssets;
console.log(assets.lockedAtlasRaw, assets.releasedCargoRaw);

Properties

lockedAtlasRaw

readonly lockedAtlasRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:116

lockedCargoRaw

readonly lockedCargoRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:117

releasedAtlasRaw

readonly releasedAtlasRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:118

releasedCargoRaw

readonly releasedCargoRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:119

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/markets/index.ts:120

Returns

unknown

---

LocalMarketMakerStateSnapshot

Defined in: packages/sage/src/markets/index.ts:100

One Profile’s maker state on one order-book side.

escrowedOrReleasedAtlas is escrowed ATLAS for bids and ATLAS released from completed sales for asks. It does not establish that either amount is currently withdrawable.

Example

declare const makerState: LocalMarketMakerStateSnapshot;
console.log(makerState.escrowedOrReleasedAtlas);

Extends

• LocalMarketMakerData

Properties

cargoRaw

readonly cargoRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:78

Inherited from

LocalMarketMakerData.cargoRaw

escrowedOrReleasedAtlas

readonly escrowedOrReleasedAtlas: number;

Defined in: packages/sage/src/internal/c4/market.ts:77

Inherited from

LocalMarketMakerData.escrowedOrReleasedAtlas

escrowedOrReleasedAtlasRaw

readonly escrowedOrReleasedAtlasRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:76

Inherited from

LocalMarketMakerData.escrowedOrReleasedAtlasRaw

openOrderCount

readonly openOrderCount: number;

Defined in: packages/sage/src/internal/c4/market.ts:74

Inherited from

LocalMarketMakerData.openOrderCount

profile

readonly profile: Address;

Defined in: packages/sage/src/internal/c4/market.ts:73

Inherited from

LocalMarketMakerData.profile

profileRef

readonly profileRef: EntityRef<"profile">;

Defined in: packages/sage/src/markets/index.ts:101

rentBytesOwnedRaw

readonly rentBytesOwnedRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:75

Inherited from

LocalMarketMakerData.rentBytesOwnedRaw

---

LocalMarketOrderBookSnapshot

Defined in: packages/sage/src/markets/index.ts:209

One translated side of a Local Market order book.

Example

declare const book: LocalMarketOrderBookSnapshot;
console.log(book.orders.length);

Properties

makers

readonly makers: readonly LocalMarketMakerStateSnapshot[];

Defined in: packages/sage/src/markets/index.ts:211

nextOrderIdRaw

readonly nextOrderIdRaw: bigint;

Defined in: packages/sage/src/markets/index.ts:210

orders

readonly orders: readonly LocalMarketOrderSnapshot[];

Defined in: packages/sage/src/markets/index.ts:212

---

LocalMarketOrderSnapshot

Defined in: packages/sage/src/markets/index.ts:84

One translated Local Market order.

Example

declare const order: LocalMarketOrderSnapshot;
console.log(order.side, order.priceAtlas);

Extends

• LocalMarketOrderData

Properties

maker

readonly maker: Address;

Defined in: packages/sage/src/internal/c4/market.ts:65

Inherited from

LocalMarketOrderData.maker

makerRef

readonly makerRef: EntityRef<"profile">;

Defined in: packages/sage/src/markets/index.ts:85

orderId

readonly orderId: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:64

Inherited from

LocalMarketOrderData.orderId

priceAtlas

readonly priceAtlas: number;

Defined in: packages/sage/src/internal/c4/market.ts:67

Inherited from

LocalMarketOrderData.priceAtlas

priceRaw

readonly priceRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:66

Inherited from

LocalMarketOrderData.priceRaw

quantityRaw

readonly quantityRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:68

Inherited from

LocalMarketOrderData.quantityRaw

side

readonly side: "bid" | "ask";

Defined in: packages/sage/src/internal/c4/market.ts:69

Inherited from

LocalMarketOrderData.side

---

LocalMarketSnapshot

Defined in: packages/sage/src/markets/index.ts:222

Immutable Local Market, order book, escrow, and maker-state snapshot.

Example

declare const market: LocalMarketSnapshot;
console.log(market.cargo.name, market.asks.orders);

Extends

• Omit<LocalMarketAccountData, "asks" | "bids" | "cargo" | "initializerProfile" | "system">

Extended by

• LocalMarketView

Properties

address

readonly address: Address;

Defined in: packages/sage/src/markets/index.ts:227

asks

readonly asks: LocalMarketOrderBookSnapshot;

Defined in: packages/sage/src/markets/index.ts:232

bids

readonly bids: LocalMarketOrderBookSnapshot;

Defined in: packages/sage/src/markets/index.ts:231

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/market.ts:91

Inherited from

Omit.bump

cargo

readonly cargo: CargoDefinitionSummary & {
  amountRaw: bigint;
};

Defined in: packages/sage/src/markets/index.ts:230

Type Declaration

amountRaw

readonly amountRaw: bigint;

initializerProfile

readonly initializerProfile: EntityRef<"profile">;

Defined in: packages/sage/src/markets/index.ts:229

kind

readonly kind: "localMarket";

Defined in: packages/sage/src/markets/index.ts:226

starbaseSequenceId

readonly starbaseSequenceId: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:90

Inherited from

Omit.starbaseSequenceId

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/markets/index.ts:228

vaultAtlas

readonly vaultAtlas: number;

Defined in: packages/sage/src/internal/c4/market.ts:95

Inherited from

Omit.vaultAtlas

vaultRaw

readonly vaultRaw: bigint;

Defined in: packages/sage/src/internal/c4/market.ts:94

Inherited from

Omit.vaultRaw

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/market.ts:88

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/markets/index.ts:233

Returns

unknown

---

MarketDiscoveryOptions

Defined in: packages/sage/src/markets/index.ts:73

Discovery controls for Local Market finders.

Example

const options: MarketDiscoveryOptions = { commitment: 'confirmed' };

Extends

• ReadOptions

Properties

commitment?

readonly optional commitment?: Commitment;

Defined in: packages/sage/src/client/contracts.ts:194

Inherited from

ReadOptions.commitment

maxAgeMs?

readonly optional maxAgeMs?: number;

Defined in: packages/sage/src/client/contracts.ts:496

Maximum age of a completed cache entry in milliseconds.

Overrides the context’s defaultMaxAgeMs. Use 0 to always revalidate or Infinity to reuse completed cache entries until explicit invalidation.

Inherited from

ReadOptions.maxAgeMs

policy?

readonly optional policy?: "cache-first" | "no-store";

Defined in: packages/sage/src/client/contracts.ts:497

Inherited from

ReadOptions.policy

refresh?

readonly optional refresh?: boolean;

Defined in: packages/sage/src/client/contracts.ts:490

Bypasses a completed cache entry.

A refresh may share a compatible provider request that is already in flight, because that request has not yet produced cached state.

Inherited from

ReadOptions.refresh

signal?

readonly optional signal?: AbortSignal;

Defined in: packages/sage/src/markets/index.ts:74

Overrides

ReadOptions.signal

Functions

deriveFactionMarketAddress()

function deriveFactionMarketAddress(
   game,
   system,
starbaseSequenceId): Promise<Address>;

Defined in: packages/sage/src/markets/index.ts:59

Derives a Faction Market PDA from its verified generated seeds.

Parameters

Parameter	Type
game	Address
system	Address
starbaseSequenceId	bigint

Returns

Promise<Address>

Example

declare const game: Address;
declare const system: Address;
const address = await deriveFactionMarketAddress(game, system, 0n);

---

deriveLocalMarketAddress()

function deriveLocalMarketAddress(
   system,
   cargoId,
starbaseSequenceId): Promise<Address>;

Defined in: packages/sage/src/markets/index.ts:43

Derives a Local Market PDA from its verified generated seeds.

Parameters

Parameter	Type
system	Address
cargoId	number
starbaseSequenceId	bigint

Returns

Promise<Address>

Example

declare const system: Address;
const address = await deriveLocalMarketAddress(system, 1, 0n);

---

deriveLocalMarketMakerAssets()

function deriveLocalMarketMakerAssets(side, maker): LocalMarketMakerAssets;

Defined in: packages/sage/src/markets/index.ts:161

Projects one observed maker row into side-aware locked principal and released proceeds.

The helper performs no network or signing work and does not infer fill state, fees, refunds, freshness, or whether released assets can be withdrawn.

Parameters

Parameter	Type
side	"bid" | "ask"
maker	Pick<LocalMarketMakerStateSnapshot, "cargoRaw" | "escrowedOrReleasedAtlasRaw">

Returns

LocalMarketMakerAssets

Example

declare const maker: LocalMarketMakerStateSnapshot;
const assets = deriveLocalMarketMakerAssets('bid', maker);
console.log(assets.lockedAtlasRaw, assets.releasedCargoRaw);

---

getFactionMarket()

function getFactionMarket(
   context,
   address,
options?): Promise<FactionMarketSnapshot>;

Defined in: packages/sage/src/markets/index.ts:557

Reads one required Faction Market by address.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise<FactionMarketSnapshot>

Example

declare const ctx: SageContext;
declare const address: Address;
const market = await getFactionMarket(ctx, address);

---

getFactionMarketForSystem()

function getFactionMarketForSystem(
   context,
   system,
   starbaseSequenceId,
options?): Promise<FactionMarketSnapshot>;

Defined in: packages/sage/src/markets/index.ts:601

Derives and reads the configured Game’s Faction Market at one Starbase incarnation.

Parameters

Parameter	Type
context	SageContext
system	Address
starbaseSequenceId	bigint
options?	ReadOptions

Returns

Promise<FactionMarketSnapshot>

Example

declare const ctx: SageContext;
declare const system: Address;
const market = await getFactionMarketForSystem(ctx, system, 0n);

---

getLocalMarket()

function getLocalMarket(
   context,
   address,
options?): Promise<LocalMarketSnapshot>;

Defined in: packages/sage/src/markets/index.ts:418

Reads one required Local Market by address.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise<LocalMarketSnapshot>

Example

declare const ctx: SageContext;
declare const address: Address;
const market = await getLocalMarket(ctx, address);

---

getLocalMarketForCargo()

function getLocalMarketForCargo(
   context,
   system,
   cargoId,
   starbaseSequenceId,
options?): Promise<LocalMarketSnapshot>;

Defined in: packages/sage/src/markets/index.ts:460

Derives and reads a Local Market for cargo at one Starbase incarnation.

Parameters

Parameter	Type
context	SageContext
system	Address
cargoId	number
starbaseSequenceId	bigint
options?	ReadOptions

Returns

Promise<LocalMarketSnapshot>

Example

declare const ctx: SageContext;
declare const system: Address;
const market = await getLocalMarketForCargo(ctx, system, 1, 0n);

---

getLocalMarketOrdersByProfile()

function getLocalMarketOrdersByProfile(
   context,
   market,
   profile,
   options?): Promise<readonly LocalMarketOrderSnapshot & {
  makerState: LocalMarketMakerStateSnapshot;
}[]>;

Defined in: packages/sage/src/markets/index.ts:516

Returns one Profile’s open orders with that side’s maker state.

Bid-side ATLAS is escrowed for buy orders. Ask-side ATLAS was released from completed sell orders. Neither interpretation promises withdrawability.

Parameters

Parameter	Type
context	SageContext
market	Address
profile	Address
options?	ReadOptions

Returns

Promise<readonly LocalMarketOrderSnapshot & { makerState: LocalMarketMakerStateSnapshot; }[]>

Example

declare const ctx: SageContext;
declare const market: Address;
declare const profile: Address;
const orders = await getLocalMarketOrdersByProfile(ctx, market, profile);

---

getLocalMarketsBySystem()

function getLocalMarketsBySystem(
   context,
   system,
options?): Promise<readonly LocalMarketSnapshot[]>;

Defined in: packages/sage/src/markets/index.ts:482

Discovers all Local Markets stored for one Star System.

Parameters

Parameter	Type
context	SageContext
system	Address
options?	MarketDiscoveryOptions

Returns

Promise<readonly LocalMarketSnapshot[]>

Example

declare const ctx: SageContext;
declare const system: Address;
const markets = await getLocalMarketsBySystem(ctx, system);

---

maybeGetFactionMarket()

function maybeGetFactionMarket(
   context,
   address,
   options?): Promise<
  | FactionMarketSnapshot
| undefined>;

Defined in: packages/sage/src/markets/index.ts:577

Reads one optional Faction Market by address.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise< | FactionMarketSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const address: Address;
const market = await maybeGetFactionMarket(ctx, address);

---

maybeGetLocalMarket()

function maybeGetLocalMarket(
   context,
   address,
   options?): Promise<
  | LocalMarketSnapshot
| undefined>;

Defined in: packages/sage/src/markets/index.ts:437

Reads one optional Local Market by address.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise< | LocalMarketSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const address: Address;
const market = await maybeGetLocalMarket(ctx, address);