markets/actions

Interfaces

PlanCancelLocalMarketOrdersOptions

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

Inputs for cancelling owned Local Market orders and withdrawing filled escrow.

orderIds is a dense, unique list of unsigned-u64 bigint integers. Pass an empty list to request withdrawal of filled escrow without cancelling an open order. The chain remains authoritative about whether escrow is available.

Example

declare const authorization: PlanAuthorization;
const options: PlanCancelLocalMarketOrdersOptions = {
  authorization,
  orderIds: [4n, 9n],
};

Properties

authorization

readonly authorization: PlanAuthorization;

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

orderIds

readonly orderIds: readonly bigint[];

Defined in: packages/sage/src/markets/actions/index.ts:86

---

PlanPlaceLocalMarketOrderOptions

Defined in: packages/sage/src/markets/actions/index.ts:62

Inputs for placing one exact Local Market order.

priceRaw is the positive raw ATLAS price per cargo unit and quantity is the positive raw cargo quantity. Both values are unsigned-u64 integers.

Example

declare const authorization: PlanAuthorization;
const options: PlanPlaceLocalMarketOrderOptions = {
  authorization,
  side: 'bid',
  priceRaw: 100_000_000n,
  quantity: 5n,
};

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/markets/actions/index.ts:63

priceRaw

readonly priceRaw: bigint;

Defined in: packages/sage/src/markets/actions/index.ts:65

quantity

readonly quantity: bigint;

Defined in: packages/sage/src/markets/actions/index.ts:66

side

readonly side: "bid" | "ask";

Defined in: packages/sage/src/markets/actions/index.ts:64

---

PlanTradeFactionMarketOptions

Defined in: packages/sage/src/markets/actions/trade-faction-market.ts:63

Exact intent for one directional Faction Market trade. No fill is guaranteed.

Example

declare const authorization: PlanAuthorization;
const options: PlanTradeFactionMarketOptions = { authorization, direction: 'buy', offerIndex: 0, quantityRaw: 5n };

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/markets/actions/trade-faction-market.ts:64

direction

readonly direction: "buy" | "sell";

Defined in: packages/sage/src/markets/actions/trade-faction-market.ts:65

offerIndex

readonly offerIndex: number;

Defined in: packages/sage/src/markets/actions/trade-faction-market.ts:66

quantityRaw

readonly quantityRaw: bigint;

Defined in: packages/sage/src/markets/actions/trade-faction-market.ts:67

Type Aliases

LocalMarketOrderDebitBounds

type LocalMarketOrderDebitBounds =
  | {
  reason:   | Extract<MarketOrderAmounts, {
     status: "unavailable";
   }>["reason"]
     | "not-local-market-order";
  status: "unavailable";
}
  | Extract<MarketOrderAmounts, {
  status: "available";
}> & {
  atlasUnit: "floyds";
  cargoId: number;
  cargoUnit: "raw";
  character: Address;
  characterVersion: 0;
  feePolicy: "default-zero";
  localMarket: Address;
  marketVersion: 0;
  maximumMarketGrowthBytes: number;
  priceRaw: bigint;
  profile: Address;
  profileUnit: "lamports";
  quantity: bigint;
  side: "bid" | "ask";
  starbasePlayer: Address;
  starbasePlayerVersion: 0;
  transactionFees: "excluded";
};

Defined in: packages/sage/src/markets/actions/index.ts:797

Qualified conservative debits for one standalone Local Market placement.

ATLAS uses Floyds, cargo uses raw units and Profile funding uses native lamports. Debits may become locked escrow; they do not predict fills or proceeds. Bounds are checked before signing and are not atomic limits in the chain instruction. Transaction fees are excluded. An unavailable result never implies zero cost.

Example

declare const bounds: LocalMarketOrderDebitBounds;
if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);

Functions

getLocalMarketOrderDebitBounds()

function getLocalMarketOrderDebitBounds(plan): LocalMarketOrderDebitBounds;

Defined in: packages/sage/src/markets/actions/index.ts:838

Reads the persisted debit qualification without network I/O.

Unsupported routes retain their existing execution behavior and return an explicit unavailable result, including a valid Profile below the conservative storage ceiling. Available bounds survive Plan persistence and fail closed before signing when their assumptions no longer hold.

Parameters

Parameter	Type
plan	Plan

Returns

LocalMarketOrderDebitBounds

Example

declare const plan: Plan;
const bounds = getLocalMarketOrderDebitBounds(plan);
if (bounds.status === 'available') console.log(bounds.maximumAtlasDebitRaw);

---

planCancelLocalMarketOrders()

function planCancelLocalMarketOrders(
   ctx,
   market,
   player,
input): Promise<Plan>;

Defined in: packages/sage/src/markets/actions/index.ts:647

Plans cancellation of owned Local Market orders and filled-escrow withdrawal.

The planner validates the loaded Local Market and Starbase Player, their canonical Profile/Character/System/Game graph, and each selected order’s ownership and price. An empty selection requests filled-escrow withdrawal. Final escrow availability and order races remain chain-authoritative.

Parameters

Parameter	Type
ctx	SageContext
market	LocalMarketSnapshot
player	StarbasePlayerSnapshot
input	PlanCancelLocalMarketOrdersOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const market: LocalMarketSnapshot;
declare const player: StarbasePlayerSnapshot;
declare const options: PlanCancelLocalMarketOrdersOptions;
const plan = await planCancelLocalMarketOrders(ctx, market, player, options);
console.log(plan.describe());

---

planPlaceLocalMarketOrder()

function planPlaceLocalMarketOrder(
   ctx,
   market,
   player,
input): Promise<Plan>;

Defined in: packages/sage/src/markets/actions/index.ts:457

Plans one Local Market bid or ask without signing, simulation, or writes.

The planner validates the loaded Local Market and Starbase Player, their canonical Character/System/Game graph, the current market-enabled Starbase incarnation, and the known bid ATLAS or ask cargo balance. Matching, rent, final capacity, permissions, and state races remain chain-authoritative. A valid Profile below the conservative storage ceiling still produces a Plan; its debit bounds are unavailable with reason profile-below-storage-ceiling.

Parameters

Parameter	Type
ctx	SageContext
market	LocalMarketSnapshot
player	StarbasePlayerSnapshot
input	PlanPlaceLocalMarketOrderOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const market: LocalMarketSnapshot;
declare const player: StarbasePlayerSnapshot;
declare const options: PlanPlaceLocalMarketOrderOptions;
const plan = await planPlaceLocalMarketOrder(ctx, market, player, options);
console.log(plan.describe());

---

planTradeFactionMarket()

function planTradeFactionMarket(
   ctx,
   fleet,
   market,
input): Promise<Plan>;

Defined in: packages/sage/src/markets/actions/trade-faction-market.ts:167

Plans one explicit buy or sell using fresh canonical prerequisites, without simulation or writes. Buy moves cargo Treasury→Fleet and ATLAS Character→Treasury; sell reverses both. Selling into a Market whose faucet is disabled, and a quantity above what the offer has left and that no restock could reach, are refused before signing. Partial fills, stock, floors, faucet caps/burn, fees, restock and final arithmetic remain chain-authoritative. Standing gates access and is credited on selling; it is not a local price adjustment. Offline construction is not live trade evidence.

Parameters

Parameter	Type
ctx	SageContext
fleet	FleetSnapshot
market	FactionMarketSnapshot
input	PlanTradeFactionMarketOptions

Returns

Promise<Plan>

Example

declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const market: FactionMarketSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planTradeFactionMarket(ctx, fleet, market, { authorization, direction: 'sell', offerIndex: 0, quantityRaw: 5n });
console.log(plan.describe());

References

PlanAuthorization

Re-exports PlanAuthorization