# markets/actions
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.

Markdown source of https://develop.atlas-kit-docs.pages.dev/reference/markets/actions/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="plancancellocalmarketordersoptions"></a>

### PlanCancelLocalMarketOrdersOptions

Defined in: [packages/sage/src/markets/actions/index.ts:84](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L84)

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

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

#### Properties

<a id="authorization"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/markets/actions/index.ts:85](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L85)

<a id="orderids"></a>

##### orderIds

```ts
readonly orderIds: readonly bigint[];
```

Defined in: [packages/sage/src/markets/actions/index.ts:86](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L86)

***

<a id="planplacelocalmarketorderoptions"></a>

### PlanPlaceLocalMarketOrderOptions

Defined in: [packages/sage/src/markets/actions/index.ts:62](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L62)

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

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

#### Properties

<a id="authorization-1"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/markets/actions/index.ts:63](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L63)

<a id="priceraw"></a>

##### priceRaw

```ts
readonly priceRaw: bigint;
```

Defined in: [packages/sage/src/markets/actions/index.ts:65](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L65)

<a id="quantity"></a>

##### quantity

```ts
readonly quantity: bigint;
```

Defined in: [packages/sage/src/markets/actions/index.ts:66](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L66)

<a id="side"></a>

##### side

```ts
readonly side: "bid" | "ask";
```

Defined in: [packages/sage/src/markets/actions/index.ts:64](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L64)

***

<a id="plantradefactionmarketoptions"></a>

### PlanTradeFactionMarketOptions

Defined in: [packages/sage/src/markets/actions/trade-faction-market.ts:63](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/trade-faction-market.ts#L63)

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

#### Example

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

#### Properties

<a id="authorization-2"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/markets/actions/trade-faction-market.ts:64](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/trade-faction-market.ts#L64)

<a id="direction"></a>

##### direction

```ts
readonly direction: "buy" | "sell";
```

Defined in: [packages/sage/src/markets/actions/trade-faction-market.ts:65](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/trade-faction-market.ts#L65)

<a id="offerindex"></a>

##### offerIndex

```ts
readonly offerIndex: number;
```

Defined in: [packages/sage/src/markets/actions/trade-faction-market.ts:66](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/trade-faction-market.ts#L66)

<a id="quantityraw"></a>

##### quantityRaw

```ts
readonly quantityRaw: bigint;
```

Defined in: [packages/sage/src/markets/actions/trade-faction-market.ts:67](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/trade-faction-market.ts#L67)

## Type Aliases

<a id="localmarketorderdebitbounds"></a>

### LocalMarketOrderDebitBounds

```ts
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](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L797)

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

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

## Functions

<a id="getlocalmarketorderdebitbounds"></a>

### getLocalMarketOrderDebitBounds()

```ts
function getLocalMarketOrderDebitBounds(plan): LocalMarketOrderDebitBounds;
```

Defined in: [packages/sage/src/markets/actions/index.ts:838](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L838)

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`](/reference/planning/#plan) |

#### Returns

[`LocalMarketOrderDebitBounds`](/reference/markets/actions/#localmarketorderdebitbounds)

#### Example

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

***

<a id="plancancellocalmarketorders"></a>

### planCancelLocalMarketOrders()

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

Defined in: [packages/sage/src/markets/actions/index.ts:647](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L647)

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`](/reference/#sagecontext) |
| `market` | [`LocalMarketSnapshot`](/reference/markets/#localmarketsnapshot) |
| `player` | `StarbasePlayerSnapshot` |
| `input` | [`PlanCancelLocalMarketOrdersOptions`](/reference/markets/actions/#plancancellocalmarketordersoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
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());
```

***

<a id="planplacelocalmarketorder"></a>

### planPlaceLocalMarketOrder()

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

Defined in: [packages/sage/src/markets/actions/index.ts:457](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/index.ts#L457)

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`](/reference/#sagecontext) |
| `market` | [`LocalMarketSnapshot`](/reference/markets/#localmarketsnapshot) |
| `player` | `StarbasePlayerSnapshot` |
| `input` | [`PlanPlaceLocalMarketOrderOptions`](/reference/markets/actions/#planplacelocalmarketorderoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
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());
```

***

<a id="plantradefactionmarket"></a>

### planTradeFactionMarket()

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

Defined in: [packages/sage/src/markets/actions/trade-faction-market.ts:167](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/markets/actions/trade-faction-market.ts#L167)

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`](/reference/#sagecontext) |
| `fleet` | `FleetSnapshot` |
| `market` | [`FactionMarketSnapshot`](/reference/markets/#factionmarketsnapshot) |
| `input` | [`PlanTradeFactionMarketOptions`](/reference/markets/actions/#plantradefactionmarketoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

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

<a id="planauthorization"></a>

### PlanAuthorization

Re-exports [PlanAuthorization](/reference/cargo/actions/#planauthorization)