perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/options-interface.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Options market data — venue-agnostic model (READ-ONLY).
+ *
+ * An options venue implements `OptionsVenue`; the CLI (`perp options`) and the MCP tools
+ * (`get_option_*`) only see these types. The first implementation is Derive
+ * (`src/exchanges/derive/options.ts`).
+ *
+ * Contract (same rules as the perp JSON):
+ *  - decimals are strings, passed through as the venue printed them (never re-rounded);
+ *  - unknown is `null`, never `0` — an empty book side is `bid: null` / `ask: null`, an IV the venue
+ *    could not compute is `null`, greeks are `null` when the venue publishes none;
+ *  - every top-level object carries `schema: 1` (bumped on any breaking change of these types).
+ *
+ * Nothing here places orders or needs a key.
+ */
+/** Version of the options JSON shapes below. */
+export declare const OPTIONS_SCHEMA: 1;
+export type OptionKind = "call" | "put";
+/** One side of the top of book. */
+export interface OptionBookSide {
+    /** Premium per contract, in `quoteCurrency`. */
+    price: string;
+    /** Contracts available at `price`. */
+    size: string;
+}
+export interface OptionGreeks {
+    delta: string;
+    gamma: string;
+    /** Units as published by the venue (Derive documents none; magnitudes match theta per day, vega per 1 vol point). */
+    theta: string;
+    vega: string;
+    rho: string;
+}
+export interface OptionIv {
+    /** Implied volatility of the mark price (fraction: "0.55" = 55%). */
+    mark: string | null;
+    /** IV of the best bid; null when there is no bid or the venue could not compute it. */
+    bid: string | null;
+    /** IV of the best ask; null when there is no ask or the venue could not compute it. */
+    ask: string | null;
+}
+export interface OptionStats24h {
+    /** Contracts traded in the last 24 h. */
+    contracts: string;
+    /** Notional (underlying) volume in `quoteCurrency`. */
+    notional: string;
+    /** Premium volume in `quoteCurrency`. */
+    premium: string;
+    trades: number;
+    /** null when there were no trades (the venue sends a "0" placeholder). */
+    high: string | null;
+    low: string | null;
+}
+/** A single option's quote: instrument facts + live market data. */
+export interface OptionQuote {
+    schema: typeof OPTIONS_SCHEMA;
+    venue: string;
+    /** Venue instrument name, e.g. "ETH-20261225-3500-P". */
+    instrument: string;
+    underlying: string;
+    quoteCurrency: string;
+    kind: OptionKind;
+    strike: string;
+    /** Expiry date (UTC, YYYY-MM-DD). */
+    expiry: string;
+    expiryMs: number;
+    bid: OptionBookSide | null;
+    ask: OptionBookSide | null;
+    mark: string;
+    /** Underlying index price. */
+    index: string;
+    /** Forward price used by the venue's pricer; null when the venue publishes no pricing. */
+    forward: string | null;
+    discountFactor: string | null;
+    iv: OptionIv;
+    greeks: OptionGreeks | null;
+    /** Open interest in contracts. */
+    openInterest: string;
+    stats24h: OptionStats24h;
+    /** Venue snapshot time (ms epoch). */
+    timestampMs: number;
+}
+export interface OptionExpiry {
+    /** UTC date, YYYY-MM-DD (the key for `chain --expiry`). */
+    expiry: string;
+    expiryMs: number;
+    /** Distinct strikes listed for this expiry. */
+    strikes: number;
+    /** Listed instruments (calls + puts). */
+    instruments: number;
+}
+export interface OptionExpiries {
+    schema: typeof OPTIONS_SCHEMA;
+    venue: string;
+    underlying: string;
+    /** Active (tradable) expiries, soonest first. */
+    expiries: OptionExpiry[];
+}
+export interface OptionChainRow {
+    strike: string;
+    call: OptionQuote | null;
+    put: OptionQuote | null;
+}
+export interface OptionChain {
+    schema: typeof OPTIONS_SCHEMA;
+    venue: string;
+    underlying: string;
+    expiry: string;
+    expiryMs: number;
+    /** "requested" = --expiry; "nearest" = the soonest active expiry (no --expiry given). */
+    expirySelection: "requested" | "nearest";
+    /** Underlying index of the newest ticker of the expiry (largest timestampMs); null when no ticker was returned. */
+    index: string | null;
+    /** Forward of the newest ticker of the expiry (one ticker's value, not an average); null when it carried no pricing. */
+    forward: string | null;
+    /**
+     * At-the-money strike: the listed strike closest to `price` — the expiry's forward when the venue
+     * publishes one (`reference: "forward"`), the index otherwise. null when neither is known.
+     * `--strikes N` keeps the N strikes closest to `price`.
+     */
+    atm: {
+        strike: string;
+        reference: "forward" | "index";
+        price: string;
+    } | null;
+    /** Total strikes listed for the expiry (before --strikes). */
+    strikesListed: number;
+    /** Rows sorted by strike ascending. */
+    rows: OptionChainRow[];
+    /** Listed instruments for which the venue returned no ticker (their side is null). */
+    missingTickers: string[];
+}
+export interface OptionUnderlying {
+    underlying: string;
+    /** Venue spot price of the underlying; null when the venue publishes none. */
+    spotPrice: string | null;
+}
+export interface OptionUnderlyings {
+    schema: typeof OPTIONS_SCHEMA;
+    venue: string;
+    underlyings: OptionUnderlying[];
+}
+export interface OptionChainQuery {
+    underlying: string;
+    /** YYYY-MM-DD; null = the nearest active expiry. */
+    expiry: string | null;
+    /** Keep only the N strikes closest to the ATM reference; null = every strike. */
+    strikesAroundAtm: number | null;
+}
+/** A read-only options venue. Every method throws a PerpError on failure. */
+export interface OptionsVenue {
+    readonly id: string;
+    readonly displayName: string;
+    listUnderlyings(): Promise<OptionUnderlyings>;
+    listExpiries(underlying: string): Promise<OptionExpiries>;
+    getChain(q: OptionChainQuery): Promise<OptionChain>;
+    getQuote(instrument: string): Promise<OptionQuote>;
+}

package/dist/exchanges/options-interface.js

@@ -0,0 +1,17 @@
+/**
+ * Options market data — venue-agnostic model (READ-ONLY).
+ *
+ * An options venue implements `OptionsVenue`; the CLI (`perp options`) and the MCP tools
+ * (`get_option_*`) only see these types. The first implementation is Derive
+ * (`src/exchanges/derive/options.ts`).
+ *
+ * Contract (same rules as the perp JSON):
+ *  - decimals are strings, passed through as the venue printed them (never re-rounded);
+ *  - unknown is `null`, never `0` — an empty book side is `bid: null` / `ask: null`, an IV the venue
+ *    could not compute is `null`, greeks are `null` when the venue publishes none;
+ *  - every top-level object carries `schema: 1` (bumped on any breaking change of these types).
+ *
+ * Nothing here places orders or needs a key.
+ */
+/** Version of the options JSON shapes below. */
+export const OPTIONS_SCHEMA = 1;

package/dist/exchanges/options-venues.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Options venues (read-only market data). Separate from the perp venue registry (`venue.ts`):
+ * an options venue is not a perp venue, so it never appears in `perp health`, arb scans or the
+ * perp market commands. `perp options` and the MCP `get_option_*` tools resolve venues here only.
+ */
+import type { OptionsVenue } from "./options-interface.js";
+import type { Network } from "./venue-types.js";
+/** Option venue ids and aliases (for argv classification). */
+export declare function optionsVenueWords(): string[];
+export declare function listOptionsVenueIds(): string[];
+/** The options venue `input` names (id or alias, case-insensitive) — CAPABILITY_UNSUPPORTED otherwise. */
+export declare function getOptionsVenue(input: string, network: Network): Promise<OptionsVenue>;

package/dist/exchanges/options-venues.js

@@ -0,0 +1,35 @@
+/**
+ * Options venues (read-only market data). Separate from the perp venue registry (`venue.ts`):
+ * an options venue is not a perp venue, so it never appears in `perp health`, arb scans or the
+ * perp market commands. `perp options` and the MCP `get_option_*` tools resolve venues here only.
+ */
+import { PerpError } from "../errors.js";
+const OPTIONS_VENUES = [
+    {
+        id: "derive",
+        aliases: ["drv"],
+        displayName: "Derive",
+        async create(network) {
+            const { DeriveOptionsVenue } = await import("./derive/options.js");
+            return DeriveOptionsVenue.forNetwork(network);
+        },
+    },
+];
+/** Option venue ids and aliases (for argv classification). */
+export function optionsVenueWords() {
+    return OPTIONS_VENUES.flatMap(v => [v.id, ...v.aliases]);
+}
+export function listOptionsVenueIds() {
+    return OPTIONS_VENUES.map(v => v.id);
+}
+/** The options venue `input` names (id or alias, case-insensitive) — CAPABILITY_UNSUPPORTED otherwise. */
+export async function getOptionsVenue(input, network) {
+    const want = input.trim().toLowerCase();
+    const entry = OPTIONS_VENUES.find(v => v.id === want || v.aliases.includes(want));
+    if (entry === undefined) {
+        throw new PerpError("CAPABILITY_UNSUPPORTED", `"${input}" has no options market data in perp-cli; options venues: ${listOptionsVenueIds().join(", ")}`, {
+            remediation: `Use -e ${OPTIONS_VENUES[0].id} (e.g. perp -e ${OPTIONS_VENUES[0].id} options expiries ETH)`,
+        });
+    }
+    return entry.create(network);
+}

package/dist/exchanges/outcome-interface.d.ts

@@ -80,6 +80,10 @@ export interface OutcomeViewSide extends OutcomeSideInfo {
     bestAsk?: string;
     /** Implied probability of THIS side winning, derived from mid */
     impliedProb?: number;
+    /** Side name without a "template:" prefix ("template:Yes" → "Yes"). */
+    label?: string;
+    /** true = bid–ask wider than OUTCOME_WIDE_SPREAD: the mid is a weak probability estimate; null = one side empty. */
+    wideSpread?: boolean | null;
 }
 export interface OutcomeViewUnderlying {
     /** Underlying symbol from description (e.g. "BTC") */

package/dist/exchanges/pacifica-atomic.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Pacifica Atomic order: a weighted basket of market orders across several markets, sent in ONE
+ * POST /api/v1/orders/batch request.
+ *
+ * Docs (read 2026-10-19):
+ *  - trading-on-pacifica/order-types/strategies/atomic: "Each leg is signed as a market order with
+ *    your Max Slippage, and all legs are sent to the exchange in a single batch request. Each leg
+ *    can fill or fail independently." Up to 5 legs per side, a market appears once in the basket,
+ *    weights are relative, the total size is USD converted to a token amount at each leg's mark
+ *    price, Reduce Only applies to every leg. "Atomic does not guarantee an all-or-nothing fill."
+ *  - api-documentation/api/rest-api/orders/batch-order: action `type` "CreateMarket"; `data` = the
+ *    signed request payload of create-market-order (signing type "create_market_order"); max 10
+ *    actions; "If one action fails, subsequent actions are still attempted"; response
+ *    `{ success, data: { results: [{ success, order_id, error }] } }`; Status 400 = bad request.
+ *  - There is no Atomic endpoint, signing type or order type code: legs are ordinary market
+ *    orders (`/orders` and `account_order_updates` show them as `order_type` / `ot` "market").
+ *
+ * Money safety: every leg is validated (lot, venue minimum, slippage bound, unique market) before
+ * anything is signed; the whole basket is signed before the single POST; an unreadable or
+ * ambiguous answer is ORDER_PENDING (never resubmitted); a per-leg fill is read back from
+ * history_by_id and never assumed.
+ */
+import { PerpError } from "../errors.js";
+import type { MarketInfo, PriceInfo } from "../pacifica/types/market.js";
+import type { BatchAction } from "../pacifica/types/order.js";
+import { type RiskAssessment } from "../risk.js";
+import type { PacificaAdapter, PacificaOrderOutcome } from "./pacifica.js";
+/** "Up to 5 markets per side" (atomic docs). */
+export declare const ATOMIC_MAX_LEGS_PER_SIDE = 5;
+/** "Maximum 10 actions per batch request" (batch-order docs). */
+export declare const PACIFICA_BATCH_MAX_ACTIONS = 10;
+/** Signing operation type of each leg (create-market-order docs). */
+export declare const ATOMIC_LEG_SIGNING_TYPE = "create_market_order";
+/** Batch action type of each leg (batch-order docs, case sensitive). */
+export declare const ATOMIC_LEG_ACTION_TYPE = "CreateMarket";
+/** Placeholder for the signature in a dry-run plan (nothing is signed in a dry run). */
+export declare const DRY_RUN_SIGNATURE = "<not signed: dry-run>";
+export interface AtomicLegSpec {
+    /** As given by the user (resolved against /info, case-insensitively). */
+    symbol: string;
+    side: "buy" | "sell";
+    /** Relative weight (> 0). */
+    weight: number;
+}
+export interface AtomicMarket {
+    symbol: string;
+    lotSize: string;
+    /** /info `min_order_size` — "Minimum order size (denominated in USD)". */
+    minOrderUsd: string;
+    /** /info/prices `mark`. */
+    mark: string;
+}
+export interface AtomicLeg {
+    symbol: string;
+    side: "buy" | "sell";
+    weight: number;
+    /** weight / sum of weights. */
+    share: number;
+    /** total × share, before lot flooring. */
+    targetUsd: number;
+    mark: string;
+    lotSize: string;
+    /** Token amount sent: floor(targetUsd / mark) to the lot. */
+    size: string;
+    /** size × mark. */
+    notionalUsd: number;
+}
+/** --long / --short leg lists → leg specs (≤ 5 per side, ≥ 1 leg, each market once). */
+export declare function parseAtomicLegs(longs: readonly string[], shorts: readonly string[]): AtomicLegSpec[];
+/**
+ * The basket's markets from GET /info + GET /info/prices (public reads). Perp rows only; every
+ * requested symbol must be listed, with a positive lot_size / min_order_size and a positive mark
+ * (PRICE_STALE otherwise — nothing sent). Resolved to the venue's own spelling (e.g. kBONK).
+ */
+export declare function atomicMarketsOf(specs: readonly AtomicLegSpec[], info: readonly MarketInfo[], prices: readonly PriceInfo[]): Map<string, AtomicMarket>;
+/**
+ * Size every leg: total × weight / Σweights in USD → token amount at the mark, floored to the
+ * lot. A leg under one lot → SIZE_TOO_SMALL (nothing sent). Its notional at the mark must be at
+ * least the market's USD minimum × (1 + slippage bound), so a sell leg still meets the minimum when
+ * it fills at the worst price the bound allows. Reduce-only legs are held to it too (no exemption is
+ * documented).
+ */
+export declare function sizeAtomicLegs(specs: readonly AtomicLegSpec[], totalUsd: string, markets: ReadonlyMap<string, AtomicMarket>, slippageBps: number): AtomicLeg[];
+/**
+ * Reduce-only basket check (read only): every leg must reduce an existing position — a buy needs
+ * a short, a sell a long — by no more than its size. Otherwise INVALID_PARAMS, nothing sent.
+ */
+export declare function requireAtomicReduceOnly(legs: readonly AtomicLeg[], positions: ReadonlyArray<{
+    symbol: string;
+    side: "long" | "short";
+    size: string;
+}>): void;
+/** A client_order_id for one leg: a UUID v4 outside the reserved TIF-encoding prefix (5ac1f). */
+export declare function atomicLegClientOrderId(): string;
+/**
+ * Basis points → Pacifica `slippage_percent` as an exact decimal string (1.1 bps → "0.011", not
+ * the float "0.011000000000000001"; 50 → "0.5").
+ */
+export declare function bpsToPercent(bps: number): string;
+/**
+ * Basket-level risk gate (on top of the per-leg enforceOrderRisk, which checks each leg against
+ * the max position size): the WHOLE basket's notional against the total-exposure limit and the
+ * number of legs that open a new market against max positions — preTradeCheck's rules applied
+ * to the basket as one order. Violations → RISK_VIOLATION (nothing sent). --force skips it.
+ */
+export declare function atomicBasketRiskCheck(assessment: RiskAssessment, legs: readonly AtomicLeg[], positions: ReadonlyArray<{
+    symbol: string;
+    size: string;
+}>): void;
+/**
+ * The create_market_order payload of one leg (create-market-order docs: symbol, amount, side,
+ * slippage_percent, reduce_only, client_order_id, optional builder_code). Signed as-is.
+ */
+export declare function atomicLegPayload(leg: AtomicLeg, o: {
+    reduceOnly: boolean;
+    slippageBps: number;
+    clientOrderId: string;
+    builderCode: string | null;
+}): Record<string, unknown>;
+/**
+ * Dry-run plan: the exact POST /orders/batch body the live run would send, with the signature
+ * replaced by a placeholder, plus each leg's canonical message (recursively key-sorted compact JSON,
+ * `{data, expiry_window, timestamp, type}`) that the live run signs. Nothing is signed.
+ */
+export declare function atomicDryRunPlan(payloads: ReadonlyArray<Record<string, unknown>>, o: {
+    account: string | null;
+    agentWallet: string | null;
+    timestamp: number;
+    expiryWindow?: number;
+}): {
+    endpoint: string;
+    body: {
+        actions: BatchAction[];
+    };
+    signedMessages: string[];
+};
+/**
+ * Error thrown by POST /orders/batch → typed. Already-typed errors (ORDER_PENDING after a send,
+ * ORDER_REJECTED when nothing could be sent) are kept. HTTP 400 is the documented whole-request
+ * refusal (batch-order: "Status 400: Bad request"; "All signatures must be valid for the batch to
+ * process") → ORDER_REJECTED. HTTP 429 → RATE_LIMITED, nothing processed. Any other answer →
+ * ORDER_PENDING (undocumented for this endpoint: legs may have executed).
+ */
+export declare function atomicBatchError(e: unknown): PerpError;
+export type AtomicAck = {
+    kind: "accepted";
+    orderId: string | null;
+} | {
+    kind: "rejected";
+    error: string;
+} | {
+    kind: "unknown";
+    reason: string;
+};
+/**
+ * Per-leg acks of a 200 batch response, in leg order. The body must carry `data.results` with one
+ * row per action; otherwise the batch's effect is unknown → ORDER_PENDING. A row with
+ * `success: true` was accepted (its `order_id` may be null — the docs' own example has one); a row
+ * with `success: false` and an error string was refused; anything else is unknown.
+ */
+export declare function parseAtomicBatchResponse(raw: unknown, legCount: number): AtomicAck[];
+export interface AtomicLegOutcome {
+    symbol: string;
+    side: "buy" | "sell";
+    size: string;
+    clientOrderId: string;
+    orderId: string | null;
+    /** filled / partiallyFilled = venue-final; notFilled = cancelled with nothing filled; unknown = not proven. */
+    status: "filled" | "partiallyFilled" | "notFilled" | "rejected" | "unknown";
+    filledSize: string | null;
+    detail: string | null;
+}
+/**
+ * Leg outcome from its ack, the order id it was traced to (the ack's, or one resolved from the
+ * leg's client_order_id; null = never traced) and that order's history_by_id outcome (null = not
+ * resolved).
+ */
+export declare function atomicLegOutcome(leg: AtomicLeg, clientOrderId: string, ack: AtomicAck, orderId: string | null, history: PacificaOrderOutcome | null): AtomicLegOutcome;
+/**
+ * The failure an Atomic basket reports unless every leg filled completely: any unknown leg →
+ * ORDER_PENDING (do not resubmit); nothing filled at all → ORDER_REJECTED; otherwise
+ * ORDER_PARTIAL. details carry every leg.
+ */
+export declare function atomicIncompleteError(legs: readonly AtomicLegOutcome[]): PerpError | null;
+/** Safety margin under the signature expiry: the batch is not sent when less than this is left. */
+export declare const ATOMIC_EXPIRY_MARGIN_MS = 1500;
+/** client_order_id → order_id lookups for a leg accepted without an order_id. */
+export declare const ATOMIC_CLOID_POLLS = 6;
+export declare const ATOMIC_CLOID_POLL_MS = 500;
+export interface AtomicDeps {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * order_id of a leg accepted without one (the batch docs' CreateMarket result carries
+ * `order_id: null`), found by its client_order_id in open orders / order history
+ * (PacificaAdapter.orderByClientId). Bounded: ATOMIC_CLOID_POLLS reads ATOMIC_CLOID_POLL_MS apart;
+ * read errors poll again. null = never found (the leg stays unknown).
+ */
+export declare function resolveAtomicLegOrderId(adapter: Pick<PacificaAdapter, "orderByClientId">, clientOrderId: string, deps?: AtomicDeps): Promise<string | null>;
+/**
+ * Wait for rate-limit capacity, sign every leg (create_market_order) with ONE shared timestamp,
+ * send them in ONE batch (the post-sign throttle wait bounded by the signature deadline), then
+ * read each accepted leg's fill back (in parallel — reads only). Signing failures and a signature
+ * that would expire within ATOMIC_EXPIRY_MARGIN_MS (a slow signer) stop before anything is sent
+ * (ORDER_REJECTED). Returns the per-leg outcomes; the caller decides with atomicIncompleteError.
+ */
+export declare function executeAtomic(adapter: PacificaAdapter, legs: readonly AtomicLeg[], payloads: ReadonlyArray<Record<string, unknown>>, deps?: AtomicDeps): Promise<{
+    outcomes: AtomicLegOutcome[];
+    venueRaw: unknown;
+}>;