@ostium/builder-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1449 @@
+import { Hex, Address } from 'viem';
+
+declare enum OrderType$1 {
+    Market = "market",
+    Limit = "limit",
+    Stop = "stop"
+}
+declare enum CancelOrderType {
+    Limit = "limit",
+    PendingOpen = "pendingOpen",
+    PendingClose = "pendingClose"
+}
+interface OpenTradeParams {
+    /** Trading pair index (e.g. 0 for BTC/USD). */
+    pairIndex: number;
+    /** true = long, false = short. */
+    buy: boolean;
+    /** Entry price as a decimal string (e.g. "65000.50"). */
+    price: string;
+    /** Collateral in USD as a decimal string (e.g. "100.00", minimum $5). */
+    collateral: string;
+    /** Leverage as a decimal string (e.g. "10" for 10×, max 100×). */
+    leverage: string;
+    /** Order type. */
+    type: OrderType$1;
+    /** Take profit price as a decimal string. Optional. */
+    takeProfit?: string;
+    /** Stop loss price as a decimal string. Optional. */
+    stopLoss?: string;
+    /** Per-trade slippage override in basis points. Overrides client default. */
+    slippage?: number;
+    /**
+     * Mark the trade as a day trade. Must be `true` when the desired leverage
+     * exceeds `pair.overnightMaxLeverage` (and `overnightMaxLeverage > 0`).
+     * Day trades are automatically closed before market close if not manually
+     * closed beforehand. Defaults to `false`.
+     */
+    isDayTrade?: boolean;
+}
+interface CloseTradeParams {
+    /**
+     * Trading pair id — same value as `Position.pairId` returned by `getOpenPositions`.
+     * Accepts both the numeric string (e.g. `"0"`) and a plain `number` for ergonomics.
+     */
+    pairId: string | number;
+    /**
+     * Position index within the pair — same value as `Position.idx` returned by
+     * `getOpenPositions`. Identifies which of the trader's open positions to close.
+     */
+    idx: number;
+    /** Current market price as a decimal string. */
+    price: string;
+    /** Percentage to close (1–100). */
+    closePercent: number;
+    /** Per-trade slippage override in basis points. */
+    slippage?: number;
+    /**
+     * When true, verifies USDC allowance covers the oracle fee before submitting.
+     * Skip by default if you know allowance is sufficient.
+     */
+    checkAllowance?: boolean;
+}
+/**
+ * Cancel a pending limit order.
+ */
+interface CancelLimitOrderParams {
+    type: CancelOrderType.Limit;
+    /**
+     * Trading pair id — same value as `OpenOrder.pairId` returned by `getOpenOrders`.
+     * Accepts both the numeric string (e.g. `"0"`) and a plain `number`.
+     */
+    pairId: string | number;
+    /**
+     * Limit order index within the pair — same value as `OpenOrder.idx` returned
+     * by `getOpenOrders`. Identifies which limit order to cancel.
+     */
+    idx: number;
+}
+/**
+ * Cancel a timed-out market open order.
+ */
+interface CancelPendingOpenParams {
+    type: CancelOrderType.PendingOpen;
+    /** Market order ID from the original openTrade submission. */
+    orderId: number;
+}
+/**
+ * Cancel a timed-out market close order.
+ */
+interface CancelPendingCloseParams {
+    type: CancelOrderType.PendingClose;
+    /** Market order ID from the original closeTrade submission. */
+    orderId: number;
+    /**
+     * If true, re-submits the close order after cancelling the timed-out one.
+     * Defaults to false (cancel only, trade remains open).
+     */
+    retry?: boolean;
+}
+type CancelOrderParams = CancelLimitOrderParams | CancelPendingOpenParams | CancelPendingCloseParams;
+interface ModifyOrderParams {
+    /**
+     * Trading pair id.
+     * - Updating TP/SL on an open position → use `Position.pairId` from `getOpenPositions`.
+     * - Updating a limit order's trigger price → use `OpenOrder.pairId` from `getOpenOrders`.
+     * Accepts both the numeric string (e.g. `"0"`) and a plain `number`.
+     */
+    pairId: string | number;
+    /**
+     * Slot index within the pair.
+     * - Updating TP/SL on an open position → use `Position.idx`.
+     * - Updating a limit order → use `OpenOrder.idx`.
+     */
+    idx: number;
+    /** New limit-order trigger price. Required when modifying a limit order's price. */
+    price?: string;
+    /** New take profit price. */
+    takeProfit?: string;
+    /** New stop loss price. */
+    stopLoss?: string;
+}
+interface UpdateCollateralParams {
+    /**
+     * Trading pair id — same value as `Position.pairId` returned by `getOpenPositions`.
+     * Accepts both the numeric string (e.g. `"0"`) and a plain `number`.
+     */
+    pairId: string | number;
+    /**
+     * Position index within the pair — same value as `Position.idx` returned by
+     * `getOpenPositions`. Identifies which position to top up or partially withdraw from.
+     */
+    idx: number;
+    /**
+     * Amount in USD as a decimal string.
+     * Positive → add collateral (topUpCollateral).
+     * Negative → remove collateral (removeCollateral).
+     */
+    amount: string;
+}
+interface Balances {
+    /** USDC balance as a decimal string (e.g. `"1234.567890"`). */
+    usdc: string;
+    /** ETH balance as a decimal string (e.g. `"0.001234567890123456789"`). */
+    eth: string;
+    /** USDC allowance granted to the TradingStorage contract as a decimal string. Max approval is preserved exactly. */
+    allowance: string;
+}
+interface AllowanceStatus {
+    /** Current USDC allowance (6 decimals, raw bigint). */
+    current: bigint;
+    /** Required USDC allowance (6 decimals, raw bigint). */
+    required: bigint;
+    /** true if current >= required. */
+    sufficient: boolean;
+}
+interface SubmissionResult {
+    txHash: Hex;
+    /** Set for gasless submissions — the Safe smart account address that sent the UserOp. */
+    smartAccountAddress?: Address;
+}
+
+/** Shared optional settings available in every mode. */
+interface CommonParams {
+    /** Use Arbitrum Sepolia testnet. Defaults to false (mainnet). */
+    testnet?: boolean;
+    /** Default slippage tolerance in basis points (e.g. 25 = 0.25%). Defaults to 25. */
+    slippageBps?: number;
+    /**
+     * Optional builder fee sharing.
+     * `feeBps` is in basis points — max 50 (0.5%).
+     */
+    builder?: {
+        address: Address;
+        feeBps: number;
+    };
+    /**
+     * Override the Ostium subgraph endpoint used by built-in read methods
+     * (`getPairs`, `getOpenPositions`, etc.). Defaults to the mainnet or testnet
+     * subgraph based on `testnet`.
+     */
+    subgraphUrl?: string;
+    /**
+     * Override the builder API base URL used for live prices, OHLC candles, and
+     * the WebSocket stream. Defaults to `https://builder.ostium.io`.
+     */
+    builderApiUrl?: string;
+}
+/**
+ * **Self + Self** — simplest mode.
+ *
+ * Your EOA is the trader: it holds USDC, owns all positions, and pays gas
+ * for every transaction directly.
+ *
+ * ```ts
+ * const client = await OstiumClient.createSelfAndSelf({
+ *   traderPrivateKey: '0x...',
+ *   rpcUrl: 'https://arb-mainnet.g.alchemy.com/v2/...',
+ * });
+ * await client.openTrade({ ... });
+ * ```
+ */
+interface SelfSelfParams extends CommonParams {
+    /** Private key of the trader's EOA. This account holds USDC, owns all positions, and pays gas. */
+    traderPrivateKey: Hex;
+    /** Arbitrum One (or Sepolia) RPC URL. */
+    rpcUrl: string;
+}
+/**
+ * **Self + Gasless** — your EOA owns everything; a Safe acts as a transparent gasless relay.
+ *
+ * Your EOA holds USDC and owns all positions. A Safe smart account is derived
+ * deterministically from your private key and registered as your delegate.
+ * After a one-time setup (approve USDC + register Safe via `setupGaslessDelegation()`),
+ * all subsequent trades are submitted as sponsored UserOperations — no ETH needed.
+ *
+ * ```ts
+ * const client = await OstiumClient.createSelfAndGasless({
+ *   traderPrivateKey: '0x...',
+ *   pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161',
+ * });
+ * // One-time setup (EOA pays gas once for each):
+ * await client.approveUsdc('max');
+ * await client.setupGaslessDelegation();
+ * // All subsequent trading is free:
+ * await client.openTrade({ ... });
+ * ```
+ */
+interface SelfGaslessParams extends CommonParams {
+    /** Private key of the trader's EOA. This account holds USDC and owns all positions. A Safe is derived from this key to relay trades gaslessly. */
+    traderPrivateKey: Hex;
+    /** Pimlico-compatible bundler/paymaster RPC URL. Defaults to `https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161`. */
+    pimlicoUrl?: string;
+    /** Arbitrum RPC URL for reads/simulation. Defaults to public Arbitrum RPC when omitted. */
+    rpcUrl?: string;
+    /** Pimlico sponsorship policy ID. */
+    sponsorshipPolicyId?: string;
+}
+/**
+ * **Delegated + Self** — a dedicated delegate EOA signs and pays gas on behalf of a separate trader address.
+ *
+ * The trader account keeps custody of USDC and positions. The delegate account
+ * only needs ETH for gas. The trader must have called `setDelegate(delegateAddress)`
+ * on the trading contract before this client can submit trades.
+ *
+ * ```ts
+ * const client = await OstiumClient.createDelegatedAndSelf({
+ *   delegatePrivateKey: '0xDelegateKey',
+ *   traderAddress: '0xTraderAddress',
+ *   rpcUrl: 'https://arb-mainnet.g.alchemy.com/v2/...',
+ * });
+ * await client.openTrade({ ... }); // submitted as delegatedAction(traderAddress, ...)
+ * ```
+ */
+interface DelegatedSelfParams extends CommonParams {
+    /** Private key of the delegate EOA. This account signs and pays gas for all transactions. */
+    delegatePrivateKey: Hex;
+    /**
+     * Address of the trader this delegate acts for.
+     * The trader must have called `setDelegate(delegateAddress)` on the trading contract.
+     */
+    traderAddress: Address;
+    /** Arbitrum One (or Sepolia) RPC URL. */
+    rpcUrl: string;
+}
+/**
+ * **Delegated + Gasless** — a Safe derived from the delegate key submits sponsored UserOperations on behalf of the trader.
+ *
+ * The trader keeps custody of USDC and positions. The delegate's Safe submits
+ * trades as UserOperations via Pimlico — no ETH needed after the trader calls
+ * `setDelegate(safeAddress)` once.
+ *
+ * ```ts
+ * const client = await OstiumClient.createDelegatedAndGasless({
+ *   delegatePrivateKey: '0xDelegateKey',
+ *   traderAddress: '0xTraderAddress',
+ *   pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161',
+ * });
+ * await client.openTrade({ ... }); // submitted as sponsored delegatedAction UserOp
+ * ```
+ */
+interface DelegatedGaslessParams extends CommonParams {
+    /** Private key of the delegate EOA. A Safe smart account is derived from this key and submits UserOperations via Pimlico. */
+    delegatePrivateKey: Hex;
+    /**
+     * Address of the trader this delegate acts for.
+     * The trader must have called `setDelegate(safeAddress)` on the trading contract,
+     * where `safeAddress` is the Safe derived from `delegatePrivateKey`.
+     * Use `client.getSmartAccountAddress()` to retrieve this address.
+     */
+    traderAddress: Address;
+    /** Pimlico-compatible bundler/paymaster RPC URL. Defaults to `https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161`. */
+    pimlicoUrl?: string;
+    /** Arbitrum RPC URL for reads/simulation. Defaults to public Arbitrum RPC when omitted. */
+    rpcUrl?: string;
+    /** Pimlico sponsorship policy ID. */
+    sponsorshipPolicyId?: string;
+}
+/**
+ * Generic config object used by the legacy `OstiumClient.create()` method.
+ * Prefer the named constructors (`createSelfAndSelf`, `createSelfAndGasless`,
+ * `createDelegatedAndSelf`, `createDelegatedAndGasless`) for clearer intent.
+ *
+ * The SDK infers the operational mode from the shape of this object:
+ *
+ * | `traderAddress` | `pimlicoUrl` | Mode                |
+ * |:---:|:---:|:---|
+ * | ✓ | ✓ | Delegated + Gasless |
+ * | ✓ | — | Delegated + Self    |
+ * | — | ✓ | Self + Gasless      |
+ * | — | — | Self + Self         |
+ */
+interface OstiumClientConfig {
+    privateKey: Hex;
+    traderAddress?: Address;
+    rpcUrl?: string;
+    pimlicoUrl?: string;
+    sponsorshipPolicyId?: string;
+    testnet?: boolean;
+    builder?: {
+        address: Address;
+        feeBps: number;
+    };
+    slippageBps?: number;
+    subgraphUrl?: string;
+    builderApiUrl?: string;
+}
+
+/** Mainnet (Arbitrum One) Ostium subgraph endpoint. */
+declare const DEFAULT_SUBGRAPH_ENDPOINT = "https://api.subgraph.ormilabs.com/api/public/67a599d5-c8d2-4cc4-9c4d-2975a97bc5d8/subgraphs/ost-prod/live/gn";
+/** Testnet (Arbitrum Sepolia) Ostium subgraph endpoint. */
+declare const DEFAULT_SUBGRAPH_ENDPOINT_TESTNET = "https://api.subgraph.ormilabs.com/api/public/67a599d5-c8d2-4cc4-9c4d-2975a97bc5d8/subgraphs/ost-sep/live/gn";
+/** Default Ostium builder API base URL (prices, OHLC, WebSocket stream). */
+declare const DEFAULT_BUILDER_API_URL = "https://builder.ostium.io";
+/**
+ * Configuration for {@link OstiumSubgraphClient}.
+ *
+ * All fields are optional — calling `OstiumSubgraphClient.create()` with no
+ * arguments connects to the mainnet subgraph.
+ *
+ * ```ts
+ * // Mainnet (default)
+ * const client = OstiumSubgraphClient.create();
+ *
+ * // Testnet (Arbitrum Sepolia)
+ * const client = OstiumSubgraphClient.create({ testnet: true });
+ *
+ * // Custom endpoints
+ * const client = OstiumSubgraphClient.create({
+ *   endpoint:      'https://my-subgraph.example.com/graphql',
+ *   builderApiUrl: 'https://my-builder-api.example.com',
+ * });
+ * ```
+ */
+interface OstiumSubgraphClientConfig {
+    /**
+     * Subgraph GraphQL endpoint.
+     * When omitted, defaults to the mainnet or testnet subgraph based on `testnet`.
+     */
+    endpoint?: string;
+    /**
+     * Use the Arbitrum Sepolia testnet subgraph.
+     * Ignored when `endpoint` is set explicitly. Defaults to false (mainnet).
+     */
+    testnet?: boolean;
+    /**
+     * Override the builder API base URL used for live prices, OHLC candles, and the
+     * WebSocket stream. Defaults to `https://builder.ostium.io`.
+     */
+    builderApiUrl?: string;
+}
+
+interface Pair {
+    /** Numeric string pair identifier (e.g. `"0"` for BTC/USD). Use this as `pairId` everywhere in the SDK. */
+    pairId: string;
+    /** Normalized quote-asset display name (e.g. `"USD"`). */
+    pairTo: string;
+    /** Normalized base-asset display name (e.g. `"BTC"`, `"WTI"` for raw `"CL"`). */
+    pairFrom: string;
+    /** Minimum trade size in base-asset units (`5 / mid`). */
+    minSz: string;
+    /** Max long size in base-asset units = `(maxOI − buyOI) / mid`. Zero when the long side is at capacity. */
+    maxBSz: string;
+    /** Max short size in base-asset units = `(maxOI − sellOI) / mid`. Zero when the short side is at capacity. */
+    maxSSz: string;
+    /** Minimum notional in USD — currently `"5.0"`. */
+    minNtl: string;
+    /** Maximum leverage for this pair (takes the tighter of pair-level and group-level caps). */
+    maxLeverage: number;
+    /**
+     * Max leverage allowed for overnight positions. `0` means no overnight restriction.
+     * When `overnightMaxLeverage > 0` and `trade.leverage > overnightMaxLeverage`,
+     * the trade must set `isDayTrade: true` and will be auto-closed before market close.
+     */
+    overnightMaxLeverage: number;
+    /** Per-block rollover fee for this pair (formatted from `lastRolloverLongPure`). */
+    rolloverFeePerBlock: string;
+    /** `buyOpenInterest + sellOpenInterest` (USD). */
+    openInterest: string;
+    /** Current long open interest in USD. */
+    buyOpenInterest: string;
+    /** Current short open interest in USD. */
+    sellOpenInterest: string;
+    /** Maximum total open interest allowed for this pair in USD. */
+    maxOpenInterest: string;
+    /** Group name (e.g. `"crypto"`, `"forex"`). */
+    category: string;
+    /** 8-hour rollover rate as a percentage, separated by side. Negative = trader earns, positive = trader pays. */
+    rolloverRate: {
+        long: string;
+        short: string;
+    };
+    /** Current mid price (average of bid and ask). */
+    midPx: string;
+    /** Current ask price (long entries execute at or above this). */
+    askPx: string;
+    /** Current bid price (short entries execute at or below this). */
+    bidPx: string;
+    /** Whether the market is currently open for trading. */
+    isMarketOpen: boolean;
+    /** Whether intra-day trading is currently closed for this pair. */
+    isDayTradingClosed: boolean;
+    /** Seconds until `isDayTradingClosed` flips. `-1` when not applicable. */
+    secondsToToggleIsDayTradingClosed: number;
+}
+interface PairsResponse {
+    pairs: Pair[];
+}
+/** Live price snapshot for a pair (bid/mid/ask as plain numbers). */
+interface PriceData {
+    mid: number;
+    bid: number;
+    ask: number;
+    isMarketOpen: boolean;
+    isDayTradingClosed: boolean;
+    /** Seconds until `isDayTradingClosed` flips. `-1` when not applicable. */
+    secondsToToggleIsDayTradingClosed: number;
+}
+interface AllPricesResponse {
+    /** Live prices keyed by pair id (string). */
+    prices: Record<string, {
+        ask: string;
+        bid: string;
+        mid: string;
+    }>;
+}
+interface Position {
+    pairTo: string;
+    pairFrom: string;
+    pairId: string;
+    /** Position id from the subgraph (numeric string — same as `Fill.pid`). */
+    pid: string;
+    /** Position index — the trader's per-pair slot for this position. */
+    idx: number;
+    /** `"B"` for LONG, `"S"` for SHORT. */
+    side: 'B' | 'S';
+    /** Position size in base-asset units (use `side` for direction). */
+    szi: string;
+    /** Price at which the position was opened (USD). */
+    entryPx: string;
+    /** Current effective leverage as a decimal string (e.g. `"10"`). */
+    leverage: string;
+    /** Current notional in USD (`size × midPrice`). */
+    ntl: string;
+    /** Net PnL after rollover, in USD. */
+    unrealizedPnl: string;
+    /** `unrealizedPnl / collateralUsed`. */
+    returnOnEquity: string;
+    /** Estimated price at which this position would be liquidated given current rollover. */
+    liquidationPx: string;
+    /** Collateral locked in this position (USD). */
+    collateralUsed: string;
+    /** Rollover fee accrued for this trade since it was opened, in USD. */
+    cumRollover: string;
+    /** Take-profit price, when set on this position. */
+    tpPx?: string;
+    /** Stop-loss price, when set on this position. */
+    slPx?: string;
+    /** Open timestamp (Unix milliseconds). */
+    openTimestamp: number;
+    /** Whether this position was opened as a day trade (auto-closes before market close). */
+    isDayTrade: boolean;
+    /** Max leverage for the trade/pair/group **/
+    maxLeverage: string;
+}
+interface PairPosition {
+    position: Position;
+    /** Max collateral removable from this position without breaching min leverage, in USD. */
+    maxWithdrawable: string;
+}
+interface MarginSummary {
+    /** Sum of `(collateral + netPnl)` across all open positions (USD). */
+    accountValue: string;
+    /** Sum of collateral deposited across all open positions (USD). */
+    totalCollateralUsed: string;
+    /** Sum of current notional values across all open positions (USD). */
+    totalNtlPos: string;
+    /** Sum of unrealized PnL (after rollover) across all open positions (USD). */
+    totalRawPnlUsd: string;
+}
+interface OpenPositionsResponse {
+    /** All open positions for the requested trader, sorted newest first. */
+    pairPositions: PairPosition[];
+    /** Aggregated margin metrics across all open positions. */
+    marginSummary: MarginSummary;
+    /**
+     * Sum of per-position max-removable collateral, computed from the leverage
+     * constraint: `collateral × (1 − currentLeverage / maxLeverage)`.
+     */
+    withdrawable: string;
+    /** Server time (Unix milliseconds). */
+    time: number;
+}
+/** Possible `orderAction` values returned by the subgraph for a fill. */
+type OrderAction = 'Open' | 'Close' | 'Liquidation' | 'StopLoss' | 'TakeProfit' | 'RemoveCollateral' | 'CloseDayTrade';
+/** Possible `orderType` values returned by the subgraph for a fill. */
+type OrderType = 'Market' | 'Limit' | 'REMOVE_COLLATERAL';
+interface FillFees {
+    /** Opening fee (devFee + vaultFee) — only on `Open` actions, else `"0"`. */
+    opening: string;
+    /** Rollover fee — on `Close`, `StopLoss`, `TakeProfit`, and `CloseDayTrade` actions, else `"0"`. */
+    rollover: string;
+    /** Liquidation fee — only on `Liquidation` actions, else `"0"`. */
+    liquidation: string;
+    /** Builder fee — when the order was routed via a builder. */
+    builder: string;
+    /** Estimated price impact cost. */
+    priceImpact: string;
+}
+interface Fill {
+    /** Normalized quote-asset display name (e.g. `"USD"`). */
+    pairTo: string;
+    /** Normalized base-asset display name (e.g. `"BTC"`). */
+    pairFrom: string;
+    /** Numeric string pair identifier — same as `Pair.pairId`. */
+    pairId: string;
+    /** Order id from the subgraph (composite, hex). */
+    oid: string;
+    /** Position id from the subgraph (numeric string — same as `Position.pid`). */
+    pid: string;
+    /** `"B"` for LONG, `"S"` for SHORT. */
+    side: 'B' | 'S';
+    /**
+     * Subgraph `orderAction` — passes through verbatim. Examples: `"Open"`, `"Close"`,
+     * `"Liquidation"`, `"StopLoss"`, `"TakeProfit"`, `"RemoveCollateral"`, `"CloseDayTrade"`.
+     */
+    action: OrderAction;
+    /** Subgraph `orderType` — passes through verbatim. Examples: `"Market"`, `"Limit"`, `"REMOVE_COLLATERAL"`. */
+    type: OrderType;
+    /** Execution price after dynamic spread impact. */
+    px: string;
+    /** Trade size in base-asset units at the time of execution. */
+    szi: string;
+    /** Collateral on the underlying position at the time of the fill (USD). */
+    collateralUsed: string;
+    fees: FillFees;
+    /**
+     * Net realized PnL in USD for close actions (`Close`, `StopLoss`, `TakeProfit`,
+     * `CloseDayTrade`, `Liquidation`) after subtracting opening fee, oracle fee, and
+     * rollover. `"0"` for `Open` and `RemoveCollateral` actions.
+     */
+    closedPnl: string;
+    /** Execution transaction hash. Empty string for pending orders. */
+    hash: string;
+    /** Execution time (Unix milliseconds). */
+    time: number;
+}
+/**
+ * An order at any stage — pending, executed, or cancelled. Extends `Fill` with
+ * initiation metadata and status flags. Poll with `getOrders({ initiatedTxHashes:
+ * [txHash] })` using the hash from `SubmissionResult.txHash`, or with `orderIds`.
+ */
+interface Order extends Fill {
+    /** Transaction that initiated this order. */
+    initiatedTx: string;
+    /** Initiation time (Unix milliseconds). */
+    initiatedTime: number;
+    /** True while the oracle callback has not yet been processed. */
+    isPending: boolean;
+    /** True when the order was cancelled (timeout, slippage, or manual cancel). */
+    isCancelled: boolean;
+    /** Reason for cancellation, when `isCancelled` is true. */
+    cancelReason?: string;
+}
+interface OpenOrder {
+    /** Normalized quote-asset display name (e.g. `"USD"`). */
+    pairTo: string;
+    /** Normalized base-asset display name (e.g. `"BTC"`). */
+    pairFrom: string;
+    /** Numeric string pair identifier — same as `Pair.pairId`. */
+    pairId: string;
+    /**
+     * Limit-order slot index within the pair. Pass to `cancelOrder` /
+     * `modifyOrder` together with `pairId` to target this limit on-chain.
+     */
+    idx: number;
+    /** `"B"` for LONG, `"S"` for SHORT. */
+    side: 'B' | 'S';
+    /** Trigger price — the order executes when the market reaches this level. */
+    limitPx: string;
+    /** Order size in base-asset units. */
+    szi: string;
+    /** Normalized order type: `"Limit"` | `"Stop"`. */
+    orderType: string;
+    /** Take-profit price, when set on this limit order. */
+    tpPx?: string;
+    /** Stop-loss price, when set on this limit order. */
+    slPx?: string;
+    /** Initiation time (Unix milliseconds). */
+    timestamp: number;
+}
+interface GetOrdersParams {
+    /**
+     * On-chain order ids to fetch. When provided, fetches
+     * those specific orders regardless of pending/cancelled status.
+     * Mutually exclusive with `initiatedTxHashes`.
+     */
+    orderIds?: Array<string | number>;
+    /**
+     * Initiating transaction hashes (`orders.initiatedTx` on the subgraph). Use with
+     * `SubmissionResult.txHash` to poll a trade you just submitted. Mutually exclusive
+     * with `orderIds`.
+     */
+    initiatedTxHashes?: readonly Hex[];
+    /** Trader address. On `OstiumClient`, defaults to the connected trader. */
+    user?: Address;
+    /** Max orders to return. Defaults to `100`. */
+    limit?: number;
+}
+interface GetPairsParams {
+    /** Optional list of pair ids to return. Accepts numeric strings or numbers. When omitted, all pairs are returned. */
+    pairIds?: Array<string | number>;
+}
+interface GetUserParams {
+    user: Address;
+}
+interface GetOpenPositionsParams extends GetUserParams {
+    /** Current Arbitrum block number — required for live PnL. Auto-fetched on `OstiumClient`. */
+    blockNumber?: bigint;
+}
+/** Sentinel value for `getFills` / `getFillsByTime` to fetch every trader's fills. */
+type AllTraders = 'ALL';
+interface GetFillsParams {
+    /**
+     * Trader address — pass `'ALL'` to fetch fills across every trader (no
+     * trader filter).
+     */
+    user: Address | AllTraders;
+    /**
+     * Optional pair filter — if provided, only fills on this pair are returned.
+     * Accepts the numeric string (e.g. `"0"`) or a plain `number`.
+     */
+    pairId?: string | number;
+    /**
+     * Maximum number of fills to return. Defaults to `1000`.
+     * Pass `Infinity` (or any large number) to fetch every matching fill.
+     */
+    limit?: number;
+}
+interface GetFillsByTimeParams extends GetFillsParams {
+    /** Inclusive lower bound (Unix milliseconds). */
+    startTime: number;
+    /** Inclusive upper bound (Unix milliseconds). Defaults to `Date.now()`. */
+    endTime?: number;
+}
+/** One simulated slippage row for a (pair, side, notional) tuple. */
+interface SimSlippageRow {
+    /** Notional echoed from the input (USD). */
+    ntl: string;
+    /** Slippage as a percentage (e.g. `"0.5"` = 0.5 %). */
+    slippage: string;
+}
+/** Per-side simulated slippage for a single pair. */
+interface SimSlippageForPair {
+    /** Slippage for long entries — capped to the long side's remaining OI capacity. */
+    long: SimSlippageRow[];
+    /** Slippage for short entries — capped to the short side's remaining OI capacity. */
+    short: SimSlippageRow[];
+}
+/** Simulated slippage results keyed by `pairId`. */
+type SimSlippageByPairId = Record<string, SimSlippageForPair>;
+interface GetSimSlippageParams {
+    /** Pair ids to simulate (e.g. `[0, "1", "10"]`). Strings or numbers — both accepted. */
+    pairIds: Array<string | number>;
+    /** Notional amounts in USD as strings (e.g. `["1000", "5000"]`). */
+    ntls: string[];
+}
+/** One synthetic orderbook level — matches Hyperliquid's L2 book level shape. */
+interface SimOrderbookLevel {
+    /** Fill price after dynamic spread impact. */
+    px: string;
+    /** Size in base-asset units (`notional / px`). */
+    sz: string;
+    /** Number of orders at this level — always `1` for simulated levels. */
+    n: number;
+}
+/**
+ * Synthetic bid/ask orderbook — matches Hyperliquid's `L2Book` response shape.
+ *
+ * - `levels[0]` — bids (short entries), best bid first (highest px → lowest impact).
+ * - `levels[1]` — asks (long entries), best ask first (lowest px → lowest impact).
+ */
+interface SimOrderbookResponse {
+    pairId: string;
+    pairFrom: string;
+    pairTo: string;
+    levels: [SimOrderbookLevel[], SimOrderbookLevel[]];
+    /** Response timestamp (Unix milliseconds). */
+    time: number;
+}
+interface GetSimOrderbookParams {
+    /** Pair id to simulate. Accepts the numeric string (e.g. `"0"`) or a plain `number`. */
+    pairId: string | number;
+    /**
+     * Maximum number of levels per side. Capped at 20. Defaults to 20.
+     * Notionals follow the `[1, 2, 3, 5] × 10ⁿ` exponential scale, stopping at
+     * the side's remaining OI capacity.
+     */
+    levels?: number;
+}
+/** Live price tick received from the builder API price stream. */
+interface PriceTick {
+    /** Upstream feed identifier. */
+    feedId: string;
+    /** Pair in `"BASE-QUOTE"` format (e.g. `"BTC-USD"`). */
+    pair: string;
+    /** Base asset symbol (e.g. `"BTC"`). */
+    from: string;
+    /** Quote asset symbol (e.g. `"USD"`). */
+    to: string;
+    /** Best bid price (short entries execute at or below this). */
+    bid: number;
+    /** Mid price (average of bid and ask). */
+    mid: number;
+    /** Best ask price (long entries execute at or above this). */
+    ask: number;
+    /** Whether the market is currently open for trading. */
+    isMarketOpen: boolean;
+    /** Whether intra-day trading is currently closed for this pair. */
+    isDayTradingClosed: boolean;
+    /** Seconds until `isDayTradingClosed` flips. `-1` when not applicable. */
+    secondsToToggleIsDayTradingClosed: number;
+    /** Tick timestamp (Unix seconds). */
+    timestampSeconds: number;
+}
+/**
+ * Candle resolution for `getCandles`.
+ * `"1"` = 1 min, `"5"` = 5 min, `"15"` = 15 min, `"60"` = 1 hr, `"240"` = 4 hr, `"1D"` = daily.
+ */
+type CandleResolution = '1' | '5' | '15' | '60' | '240' | '1D';
+/** One OHLC candle returned by `getCandles`. */
+interface Candle {
+    /** Normalized base-asset display name (e.g. `"WTI"` for raw `"CL"`). */
+    pairFrom: string;
+    /** Normalized quote-asset display name (e.g. `"USD"`). */
+    pairTo: string;
+    /** Candle open time (Unix milliseconds). */
+    time: number;
+    /** Opening price for the candle period (USD). */
+    open: number;
+    /** Highest price reached during the candle period (USD). */
+    high: number;
+    /** Lowest price reached during the candle period (USD). */
+    low: number;
+    /** Closing price at the end of the candle period (USD). */
+    close: number;
+}
+interface GetCandlesParams {
+    /**
+     * Pair id — same as `Pair.pairId` from `getPairs()`.
+     * Accepts both the numeric string (e.g. `"0"`) and a plain `number`.
+     */
+    pairId: string | number;
+    /** Start time (Unix milliseconds). */
+    from: number;
+    /** End time (Unix milliseconds). Defaults to `Date.now()`. */
+    to?: number;
+    /** Candle width — `"1"` (1 min) through `"1D"` (daily). See {@link CandleResolution}. */
+    resolution: CandleResolution;
+}
+
+type TickHandler = (tick: PriceTick) => void;
+type SnapshotHandler = (ticks: PriceTick[]) => void;
+/**
+ * WebSocket client for the Ostium live price stream.
+ *
+ * ```ts
+ * // Via OstiumClient / OstiumSubgraphClient (recommended — pairIds resolved automatically):
+ * const stream = client.streamPrices([0, 1]);  // BTC and ETH by pairId
+ *
+ * stream.onSnapshot(ticks => console.log('snapshot:', ticks.length));
+ * stream.onTick(tick => console.log(tick.pair, tick.mid));
+ *
+ * stream.subscribe([2]);      // add pair 2
+ * stream.unsubscribe([0]);    // remove pair 0
+ * stream.close();
+ * ```
+ *
+ * The socket connects to `{builderApiUrl}/v1/prices/stream` — `https://` is
+ * automatically rewritten to `wss://` (and `http://` to `ws://`). When
+ * `streamPrices(pairIds)` is called with ids, the SDK sends
+ * `{ type: "subscribe", pairs: ["FROM-TO", ...] }` on `open` (same wire format
+ * as {@link OstiumPriceStream.subscribe}).
+ *
+ * `subscribe` / `unsubscribe` accept the same `pairId` values used everywhere
+ * else in the SDK. `PriceTick.pair` / `.from` / `.to` use normalized display
+ * names (e.g. `"UK100"` not `"FTSE"`).
+ */
+declare class OstiumPriceStream {
+    private readonly ws;
+    private readonly tickHandlers;
+    private readonly snapshotHandlers;
+    /** pairId (string) → raw "FROM-TO" name for the WS API. */
+    private readonly pairRawNameCache;
+    private constructor();
+    /**
+     * Open a WebSocket connection to the live price stream.
+     *
+     * Uses the `ws` package which correctly handles case-insensitive `Connection`
+     * header values (required for Cloudflare-proxied endpoints).
+     *
+     * @param builderApiUrl    - Base URL (e.g. `"https://builder.ostium.io"`). The `http`/`https`
+     *                           scheme is automatically converted to `ws`/`wss`.
+     * @param rawPairs         - Optional raw `"FROM-TO"` names (from
+     *                           `OstiumSubgraphClient.streamPrices` pairIds). Sent as
+     *                           `{ type: "subscribe", pairs }` after the socket opens.
+     * @param pairRawNameCache - pairId → raw name map; passed in by the subgraph client so
+     *                           `subscribe` / `unsubscribe` can accept pairIds.
+     */
+    static connect(builderApiUrl: string, rawPairs?: string[], pairRawNameCache?: Map<string, string>): OstiumPriceStream;
+    /**
+     * Register a callback that fires on every incoming price tick.
+     * Returns an unsubscribe function.
+     */
+    onTick(handler: TickHandler): () => void;
+    /**
+     * Register a callback that fires once with the full snapshot sent on connect.
+     * Returns an unsubscribe function.
+     */
+    onSnapshot(handler: SnapshotHandler): () => void;
+    /** Register a one-time callback that fires when the connection is established. */
+    onOpen(handler: () => void): this;
+    /** Register an error callback. */
+    onError(handler: (event: Error) => void): this;
+    /** Register a callback that fires when the connection closes. */
+    onClose(handler: (code: number, reason: string) => void): this;
+    /**
+     * Add pairs to the active filter. Accepts the same `pairId` values used
+     * throughout the SDK (numeric string or number).
+     * Sends `{ type: "subscribe", pairs: [...rawNames] }` to the server.
+     */
+    subscribe(pairIds: Array<string | number>): this;
+    /**
+     * Remove pairs from the active filter. Accepts the same `pairId` values used
+     * throughout the SDK.
+     * Sends `{ type: "unsubscribe", pairs: [...rawNames] }` to the server.
+     */
+    unsubscribe(pairIds: Array<string | number>): this;
+    /** Close the WebSocket connection. */
+    close(): void;
+    /** Underlying WebSocket ready state (`0=CONNECTING`, `1=OPEN`, `2=CLOSING`, `3=CLOSED`). */
+    get readyState(): number;
+    private resolveRawNames;
+    private send;
+}
+
+declare class OstiumSubgraphClient {
+    private readonly gql;
+    private readonly builderApiUrl;
+    /** Cached pair-name (`${from}/${to}`) → `pairId` map. Refreshed lazily. */
+    private pairIdCache;
+    /** Cached `pairId` → `"FROM-TO"` in raw subgraph dash format (used for OHLC API). */
+    private pairRawNameCache;
+    private constructor();
+    /**
+     * Create a client connected to the Ostium subgraph.
+     *
+     * Fetches the full pair list at startup so that `streamPrices`, `getCandles`,
+     * and `getAllPrices` can resolve pair ids to raw names without an extra round-trip.
+     *
+     * ```ts
+     * // Mainnet (default)
+     * const client = await OstiumSubgraphClient.create();
+     *
+     * // Testnet (Arbitrum Sepolia)
+     * const client = await OstiumSubgraphClient.create({ testnet: true });
+     * ```
+     */
+    static create(config?: OstiumSubgraphClientConfig): Promise<OstiumSubgraphClient>;
+    private initPairCache;
+    /**
+     * All trading pairs with computed `minSz`/`maxBSz`/`maxSSz`, live prices, and
+     * market-status flags. Pass `pairIds` to restrict to a subset.
+     */
+    getPairs(params?: GetPairsParams): Promise<PairsResponse>;
+    /** Live mid/bid/ask prices keyed by `pairId`. */
+    getAllPrices(): Promise<AllPricesResponse>;
+    /**
+     * Open positions for a trader, sorted newest first, with margin summary.
+     *
+     * - Fetches live prices automatically.
+     * - `blockNumber` is required for live PnL (rollover projection). When omitted,
+     *   PnL fields are zeroed.
+     */
+    getOpenPositions(params: GetOpenPositionsParams): Promise<OpenPositionsResponse>;
+    /**
+     * Executed fills, sorted by `executedAt desc`.
+     *
+     * - `user`: pass an address to scope to a single trader, or `'ALL'` to fetch
+     *   fills across every trader (no trader filter).
+     * - `pairId`: optional pair filter — when set, only fills on this pair are returned.
+     */
+    getFills(params: GetFillsParams): Promise<Fill[]>;
+    /** Executed fills within an inclusive time range (Unix ms). Same filters as `getFills`. */
+    getFillsByTime(params: GetFillsByTimeParams): Promise<Fill[]>;
+    private fetchFills;
+    /** Active limit orders for a trader, sorted by `updatedAt desc`. */
+    getOpenOrders({ user }: GetUserParams): Promise<OpenOrder[]>;
+    /**
+     * Fetch orders at any status — pending, executed, or cancelled.
+     *
+     * - Pass `initiatedTxHashes` (e.g. `[result.txHash]` from `openTrade` / `closeTrade`)
+     *   to poll by the subgraph `initiatedTx` field.
+     * - Pass `orderIds` to look up by on-chain order id (mutually exclusive with
+     *   `initiatedTxHashes`).
+     * - Pass only `user` (or omit on `OstiumClient`) to get recent orders for
+     *   a trader regardless of status.
+     */
+    getOrders(params?: GetOrdersParams): Promise<Order[]>;
+    /**
+     * Simulate the dynamic-spread slippage a long and a short entry of each
+     * notional would experience on the given pairs. Notionals exceeding the
+     * side's remaining open-interest capacity (`maxOI − sideOI`) are dropped.
+     *
+     * Computed via `CalculateDynamicPriceImpact` from `@ostium/formulae` using
+     * the pair's live OI / decay / threshold params + the current bid/mid/ask
+     * from the live-prices feed (collateral = `ntl`, leverage = 1).
+     *
+     * ```ts
+     * const sim = await client.getSimSlippage({
+     *   pairIds: ['0', '1'],
+     *   ntls:    ['10000', '100000', '1000000'],
+     * });
+     * // → { '0': { long: [{ ntl, slippage }...], short: [...] }, '1': ... }
+     * ```
+     */
+    getSimSlippage(params: GetSimSlippageParams): Promise<SimSlippageByPairId>;
+    /**
+     * Build a synthetic bid/ask orderbook for a single pair using the on-chain
+     * dynamic-spread params. Each side gets up to `levels` (capped at 20)
+     * exponentially-spaced notional levels (`[1, 2, 3, 5] × 10ⁿ`), stopping at
+     * the side's remaining open-interest capacity.
+     *
+     * ```ts
+     * const ob = await client.getSimOrderbook({ pairId: '0', levels: 20 });
+     * // ob.asks: long-entry levels (you'd buy at `px`)
+     * // ob.bids: short-entry levels (you'd sell at `px`)
+     * ```
+     */
+    getSimOrderbook(params: GetSimOrderbookParams): Promise<SimOrderbookResponse>;
+    /**
+     * Fetch OHLC candles for a pair.
+     *
+     * `pairId` maps to the raw subgraph pair name internally (e.g. pair `0` →
+     * `"BTC-USD"`). `from` / `to` are Unix milliseconds; `resolution` is one of
+     * `"1"`, `"5"`, `"15"`, `"60"`, `"240"`, `"1D"`.
+     *
+     * ```ts
+     * const candles = await client.getCandles({
+     *   pairId: 0,
+     *   from: Date.now() - 7 * 86_400_000,
+     *   resolution: '1D',
+     * });
+     * ```
+     */
+    getCandles(params: GetCandlesParams): Promise<Candle[]>;
+    /**
+     * Open a WebSocket connection to the live price stream.
+     *
+     * Optionally filter to a subset of pairs by `pairId` — same values as returned by
+     * `getPairs()`. When provided, the client sends `{ type: "subscribe", pairs }` on
+     * `open` (no `?pairs=` query on the URL). Omit `pairIds` to receive the full feed.
+     *
+     * The returned `OstiumPriceStream` fires an initial `snapshot` event with all
+     * cached ticks, then a `tick` event on every update. `PriceTick.from` / `.to`
+     * are normalized display names (e.g. `"WTI"` not `"CL"`).
+     *
+     * ```ts
+     * const stream = client.streamPrices([0, 1]);  // BTC and ETH by pairId
+     *
+     * stream.onOpen(() => console.log('connected'));
+     * stream.onSnapshot(ticks => console.log('snapshot', ticks.length));
+     * stream.onTick(tick => console.log(tick.pair, tick.mid));
+     *
+     * // Dynamically add / remove by pairId:
+     * stream.subscribe([2]);
+     * stream.unsubscribe([0]);
+     * stream.close();
+     * ```
+     *
+     * Requires a runtime with native `WebSocket` (Node.js 18+, Bun, browsers). Bun’s
+     * `WebSocket` may fail some `https://` upgrades (e.g. CloudFront); use Node if so.
+     */
+    streamPrices(pairIds?: Array<string | number>): OstiumPriceStream;
+    private fetchRawPairs;
+    private refreshPairIdCache;
+    private ensurePairIdCache;
+    private ensurePairRawName;
+    /** Wrapped `fetchLivePrices` that swallows network errors and returns `{}`. */
+    private fetchLivePricesSafe;
+    private query;
+}
+
+declare class OstiumClient {
+    private readonly signer?;
+    private readonly submitter?;
+    private readonly contracts;
+    private readonly publicClient;
+    private readonly defaultSlippageBps;
+    private readonly delegated;
+    private readonly gasless;
+    private readonly selfGasless;
+    private readonly eoaSubmit?;
+    private readonly builderAddress?;
+    private readonly builderFeeBps?;
+    /** Internal subgraph client backing all read methods (`getPairs`, `getOpenPositions`, …). */
+    readonly subgraph: OstiumSubgraphClient;
+    private constructor();
+    /**
+     * **Self + Self** — your EOA signs every transaction and pays gas directly.
+     *
+     * Use this when you want the simplest possible setup: one key, no smart accounts,
+     * no delegation. Your EOA holds USDC and owns all positions.
+     *
+     * ```ts
+     * const client = await OstiumClient.createSelfAndSelf({
+     *   traderPrivateKey: '0x...',
+     *   rpcUrl: 'https://arb-mainnet.g.alchemy.com/v2/...',
+     * });
+     * await client.openTrade({ ... });
+     * ```
+     */
+    static createSelfAndSelf(params: SelfSelfParams): Promise<OstiumClient>;
+    /**
+     * **Self + Gasless** — your EOA owns everything; a Safe relays trades for free.
+     *
+     * Your EOA holds USDC and owns all positions. A Safe smart account is derived
+     * deterministically from your private key and registered as your on-chain delegate.
+     * After a one-time setup (approve USDC + `setupGaslessDelegation()`), all trades
+     * are submitted as sponsored UserOperations — no ETH required.
+     *
+     * ```ts
+     * const client = await OstiumClient.createSelfAndGasless({
+     *   traderPrivateKey: '0x...',
+     *   pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161',
+     * });
+     * // One-time setup — EOA pays gas once for each:
+     * await client.approveUsdc('max');
+     * await client.setupGaslessDelegation();
+     * // All subsequent trading is gasless:
+     * await client.openTrade({ ... });
+     * ```
+     */
+    static createSelfAndGasless(params: SelfGaslessParams): Promise<OstiumClient>;
+    /**
+     * **Delegated + Self** — a delegate EOA signs and pays gas on behalf of a trader address.
+     *
+     * The trader retains custody of USDC and positions. The delegate only needs ETH
+     * for gas. Every trade is wrapped in `delegatedAction(traderAddress, callData)`.
+     * The trader must call `setDelegate(delegateAddress)` once before this client
+     * can submit trades.
+     *
+     * ```ts
+     * const client = await OstiumClient.createDelegatedAndSelf({
+     *   delegatePrivateKey: '0xDelegateKey',
+     *   traderAddress: '0xTraderAddress',
+     *   rpcUrl: 'https://arb-mainnet.g.alchemy.com/v2/...',
+     * });
+     * await client.openTrade({ ... });
+     * ```
+     */
+    static createDelegatedAndSelf(params: DelegatedSelfParams): Promise<OstiumClient>;
+    /**
+     * **Delegated + Gasless** — a Safe derived from the delegate key submits sponsored
+     * UserOperations on behalf of the trader. No ETH needed after setup.
+     *
+     * The trader retains custody of USDC and positions. The delegate's Safe submits
+     * trades as UserOperations via Pimlico. The trader must call `setDelegate(safeAddress)`
+     * once — use `client.getSmartAccountAddress()` to retrieve the Safe address.
+     *
+     * ```ts
+     * const client = await OstiumClient.createDelegatedAndGasless({
+     *   delegatePrivateKey: '0xDelegateKey',
+     *   traderAddress: '0xTraderAddress',
+     *   pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161',
+     * });
+     * await client.openTrade({ ... }); // gasless delegatedAction UserOp
+     * ```
+     */
+    static createDelegatedAndGasless(params: DelegatedGaslessParams): Promise<OstiumClient>;
+    /**
+     * **Read-only client** — no signer, no submitter, no privateKey required.
+     *
+     * All read methods (`getPairs`, `getOpenPositions`, `getFills`, `getBalances`, …)
+     * are available. Methods that take an optional `user` argument require it to be
+     * passed explicitly. Calling any write method throws `INVALID_CONFIG`.
+     *
+     * ```ts
+     * const reader = await OstiumClient.createReadOnly();
+     * const { pairs } = await reader.getPairs();
+     * const balances = await reader.getBalances('0xTrader...');
+     * const positions = await reader.getOpenPositions({ user: '0xTrader...' });
+     * ```
+     */
+    static createReadOnly(params?: {
+        /** Arbitrum RPC URL. Defaults to the chain's public RPC. */
+        rpcUrl?: string;
+        /** Use Arbitrum Sepolia testnet. Defaults to false (mainnet). */
+        testnet?: boolean;
+        /** Override the subgraph endpoint. */
+        subgraphUrl?: string;
+        /** Override the builder API base URL (prices, OHLC, WebSocket stream). */
+        builderApiUrl?: string;
+    }): Promise<OstiumClient>;
+    /** Internal factory shared by all public constructors. */
+    private static _fromConfig;
+    /**
+     * The on-chain address that owns trades and USDC allowances.
+     *
+     * - Self + Self / Delegated modes: trader's EOA or configured traderAddress.
+     * - Self + Gasless: EOA derived from privateKey (NOT the Safe — USDC lives here).
+     */
+    getTraderAddress(): Address;
+    /** True when the client was created via `createReadOnly` and cannot submit transactions. */
+    isReadOnly(): boolean;
+    /**
+     * Returns the Safe smart-account address used for gasless submission.
+     * Returns undefined when not in gasless mode.
+     *
+     * - Self + Gasless:      Safe that submits on behalf of the EOA (the delegate).
+     *                        Pass this address to setupGaslessDelegation().
+     * - Delegated + Gasless: delegate's Safe address.
+     * - Self + Self / Delegated + Self: returns undefined.
+     */
+    getSmartAccountAddress(): Address | undefined;
+    /**
+     * One-time setup for Self + Gasless mode.
+     *
+     * Registers the Safe smart account as a delegate on the trading contract so
+     * the Safe can submit gasless trades on behalf of your EOA. The EOA pays gas
+     * for this single transaction; all subsequent trading is gasless.
+     *
+     * Only callable in Self + Gasless mode. Throws INVALID_CONFIG otherwise.
+     *
+     * @example
+     * ```ts
+     * const client = await OstiumClient.create({ privateKey: '0x...', pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161' });
+     * await client.approveUsdc('max');         // EOA approves USDC (gas, one-time)
+     * await client.setupGaslessDelegation();   // EOA sets Safe as delegate (gas, one-time)
+     * // From here: all trading is gasless
+     * await client.openTrade({ ... });
+     * ```
+     */
+    setupGaslessDelegation(): Promise<SubmissionResult>;
+    /**
+     * Check whether the trader's USDC allowance covers the required amount.
+     * The allowance is always checked against signer.traderAddress (the EOA in
+     * Self + Gasless mode, the Safe in Delegated + Gasless).
+     */
+    checkUsdcAllowance(requiredUsd: string): Promise<AllowanceStatus>;
+    /**
+     * USDC and ETH balances plus the USDC allowance to TradingStorage.
+     * All three values are decimal strings so large values (e.g. max USDC approval)
+     * are preserved exactly. Parse with `parseFloat` / `Number` only for display.
+     *
+     * In read-only mode, pass `user` explicitly. With a connected trader, omit it
+     * to read the connected address.
+     */
+    getBalances(user?: Address): Promise<Balances>;
+    /**
+     * Approve USDC spending by the TradingStorage contract.
+     *
+     * - Self + Self: submitted gaslessly from EOA.
+     * - Self + Gasless: submitted directly from EOA (the delegate cannot approve
+     *   on behalf of the trader). The EOA pays gas for this one-time operation.
+     * - Delegated modes: throws — the trader must approve from their own account.
+     *
+     * @param amount USD amount as decimal string (e.g. "1000"), or "max" for MaxUint256.
+     */
+    approveUsdc(amount: string): Promise<SubmissionResult>;
+    /**
+     * Set a delegate on the trading contract.
+     *
+     * - Self + Self: EOA directly registers a delegate.
+     * - Self + Gasless: NOT recommended — use setupGaslessDelegation() instead.
+     * - Delegated modes: wrapped in delegatedAction so the existing delegate can
+     *   update the trader's delegation on their behalf.
+     */
+    setDelegate(delegateAddress: Address): Promise<SubmissionResult>;
+    /**
+     * Remove the current delegate on the trading contract.
+     * Follows the same delegation-wrapping rules as setDelegate().
+     */
+    removeDelegate(): Promise<SubmissionResult>;
+    /**
+     * Open a new trade position.
+     *
+     * Call `approveUsdc()` (once) before the first trade — the contract will revert
+     * on-chain if the USDC allowance is insufficient. Use `getBalances()` to check
+     * the current allowance.
+     */
+    openTrade(params: OpenTradeParams): Promise<SubmissionResult>;
+    /**
+     * Close an open position (full or partial).
+     *
+     * `pairId` and `idx` come straight from a `Position` returned by
+     * `getOpenPositions` — pass them through directly:
+     *
+     * ```ts
+     * const { pairPositions } = await client.getOpenPositions();
+     * const { pairId, idx } = pairPositions[0].position;
+     * await client.closeTrade({ pairId, idx, price: '...', closePercent: 100 });
+     * ```
+     */
+    closeTrade(params: CloseTradeParams): Promise<SubmissionResult>;
+    /**
+     * Cancel a pending order.
+     *
+     * TypeScript discriminates the params shape by `type` — required fields are
+     * enforced at compile time.
+     *
+     * @example Cancel a pending limit order
+     * ```ts
+     * const [order] = await client.getOpenOrders();
+     * await client.cancelOrder({ type: CancelOrderType.Limit, pairId: order.pairId, idx: order.idx });
+     * ```
+     * @example Cancel a timed-out market open
+     * ```ts
+     * await client.cancelOrder({ type: CancelOrderType.PendingOpen, orderId: 123 });
+     * ```
+     * @example Cancel a timed-out market close (retry: true re-submits the close)
+     * ```ts
+     * await client.cancelOrder({ type: CancelOrderType.PendingClose, orderId: 456, retry: true });
+     * ```
+     */
+    cancelOrder(params: CancelOrderParams): Promise<SubmissionResult>;
+    /**
+     * Modify an open trade or a pending limit order.
+     *
+     * `pairId` and `idx` come straight from `getOpenPositions` (for TP/SL on open
+     * positions) or `getOpenOrders` (for limit-order edits):
+     *
+     * ```ts
+     * // Update TP/SL on an open position
+     * const { pairPositions } = await client.getOpenPositions();
+     * const { pairId, idx } = pairPositions[0].position;
+     * await client.modifyOrder({ pairId, idx, takeProfit: '...', stopLoss: '...' });
+     *
+     * // Re-price a pending limit order
+     * const [order] = await client.getOpenOrders();
+     * await client.modifyOrder({ pairId: order.pairId, idx: order.idx, price: '...' });
+     * ```
+     *
+     * - `price` provided → updates limit-order trigger price (with optional TP/SL).
+     * - `takeProfit` only → calls updateTp on an open trade.
+     * - `stopLoss` only → calls updateSl on an open trade.
+     * - Both `takeProfit` and `stopLoss` without `price` → throws (send two calls).
+     */
+    modifyOrder(params: ModifyOrderParams): Promise<SubmissionResult>;
+    /**
+     * Update collateral on an open position (isolated margin).
+     *
+     * `pairId` and `idx` come straight from a `Position` returned by `getOpenPositions`:
+     *
+     * ```ts
+     * const { pairPositions } = await client.getOpenPositions();
+     * const { pairId, idx } = pairPositions[0].position;
+     * await client.updateCollateral({ pairId, idx, amount: '50' });   // top up
+     * await client.updateCollateral({ pairId, idx, amount: '-25' });  // remove
+     * ```
+     *
+     * Positive amount → topUpCollateral (adds margin, reduces effective leverage).
+     * Negative amount → removeCollateral (removes margin, increases effective leverage).
+     *
+     * Checks USDC allowance before top-up operations.
+     */
+    updateCollateral(params: UpdateCollateralParams): Promise<SubmissionResult>;
+    /**
+     * All trading pairs with computed `minSz`/`maxBSz`/`maxSSz`, live prices, and
+     * market-status flags. Pass `pairIds` to restrict to a subset.
+     */
+    getPairs(params?: GetPairsParams): Promise<PairsResponse>;
+    /** Live mid/bid/ask prices keyed by `pairId`. */
+    getAllPrices(): Promise<AllPricesResponse>;
+    /**
+     * Open positions + margin summary for a user. Defaults to the connected
+     * trader. Live prices and the current block number are fetched automatically.
+     */
+    getOpenPositions(params?: Partial<GetOpenPositionsParams>): Promise<OpenPositionsResponse>;
+    /**
+     * Executed fills, newest first.
+     *
+     * - `user` defaults to the connected trader. Pass `'ALL'` to fetch fills
+     *   across every trader (no trader filter).
+     * - `pairId` (optional) — restricts to a single pair.
+     * - `limit` (optional, default `1000`) — caps the result. Pass `Infinity` to
+     *   fetch every matching fill.
+     */
+    getFills(params?: Partial<GetFillsParams>): Promise<Fill[]>;
+    /**
+     * Executed fills within a time range (Unix ms). Same filters as `getFills`,
+     * including the default `limit: 1000`.
+     */
+    getFillsByTime(params: Partial<GetFillsByTimeParams> & {
+        startTime: number;
+    }): Promise<Fill[]>;
+    /** Active limit orders for a user. Defaults to the connected trader. */
+    getOpenOrders(params?: Partial<GetUserParams>): Promise<OpenOrder[]>;
+    /**
+     * Fetch orders at any status — pending, executed, or cancelled.
+     *
+     * Pass `initiatedTxHashes: [result.txHash]` to poll by the submission hash, or
+     * `orderIds` by on-chain id. Without either, returns recent orders for the
+     * connected trader.
+     */
+    getOrders(params?: Omit<GetOrdersParams, 'user'> & {
+        user?: Address;
+    }): Promise<Order[]>;
+    /**
+     * Simulate per-side slippage for a list of pairs and notionals.
+     * See {@link OstiumSubgraphClient.getSimSlippage} for full semantics.
+     */
+    getSimSlippage(params: GetSimSlippageParams): Promise<SimSlippageByPairId>;
+    /**
+     * Build a synthetic bid/ask orderbook for one pair using exponentially-spaced
+     * notional levels capped at each side's remaining OI capacity.
+     * See {@link OstiumSubgraphClient.getSimOrderbook} for full semantics.
+     */
+    getSimOrderbook(params: GetSimOrderbookParams): Promise<SimOrderbookResponse>;
+    /**
+     * Fetch OHLC candles for a pair from the builder API.
+     *
+     * `from` / `to` are Unix milliseconds; `resolution` is one of
+     * `"1"`, `"5"`, `"15"`, `"60"`, `"240"`, `"1D"`.
+     *
+     * ```ts
+     * const candles = await client.getCandles({
+     *   pairId: 0,
+     *   from: Date.now() - 30 * 86_400_000,
+     *   resolution: '1D',
+     * });
+     * ```
+     */
+    getCandles(params: GetCandlesParams): Promise<Candle[]>;
+    /**
+     * Open a WebSocket connection to the live price stream.
+     *
+     * Optionally filter to a subset of pairs by `pairId` — same values as returned by
+     * `getPairs()`. When provided, the client sends `{ type: "subscribe", pairs }` on
+     * `open` (no `?pairs=` query on the URL). Omit `pairIds` to receive the full feed.
+     *
+     * ```ts
+     * const stream = client.streamPrices([0, 1]);  // BTC and ETH by pairId
+     * stream.onSnapshot(ticks => console.log(ticks));
+     * stream.onTick(tick => console.log(tick.pair, tick.mid));
+     * stream.subscribe([2]);    // add pair
+     * stream.unsubscribe([0]);  // remove pair
+     * stream.close();
+     * ```
+     *
+     * Requires Node.js 18+, Bun, or a browser environment. Bun’s `WebSocket` may fail
+     * some `https://` upgrades; use Node if the connection never reaches `open`.
+     */
+    streamPrices(pairIds?: Array<string | number>): OstiumPriceStream;
+    /**
+     * Core execution pipeline:
+     * 1. signer.prepare()  — optionally wraps in delegatedAction.
+     * 2. submitter.submit() — sends via EOA walletClient or Pimlico UserOp.
+     */
+    private execute;
+    /** Throws if the client is read-only; otherwise returns the signer + submitter. */
+    private requireWriter;
+    /** Direct EOA submission — used only in Self + Gasless for approveUsdc and setupGaslessDelegation. */
+    private submitDirectFromEoa;
+    private resolveSlippage;
+}
+
+declare enum OstiumErrorCode {
+    INVALID_CONFIG = "INVALID_CONFIG",
+    VALIDATION_FAILED = "VALIDATION_FAILED",
+    ALLOWANCE_INSUFFICIENT = "ALLOWANCE_INSUFFICIENT",
+    SUBMISSION_FAILED = "SUBMISSION_FAILED",
+    DELEGATION_FAILED = "DELEGATION_FAILED",
+    CONTRACT_ERROR = "CONTRACT_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR"
+}
+declare class OstiumError extends Error {
+    readonly code: OstiumErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: OstiumErrorCode, cause?: unknown | undefined);
+}
+
+/**
+ * Decimal conversion utilities for trading precision
+ * Critical: All values must be scaled correctly for smart contract calls
+ */
+/**
+ * Parse a USDC amount string to bigint with 6 decimals
+ * @param amount - Amount in USDC (e.g., "100.50" = 100.50 USDC)
+ * @returns Bigint representation with 6 decimal precision
+ */
+declare function parseUsdc(amount: string | number): bigint;
+/**
+ * Parse a price string to bigint with 18 decimals.
+ * Uses string manipulation to avoid floating-point precision loss.
+ * @param price - Price as string (e.g., "1900.50")
+ * @returns Bigint representation with 18 decimal precision
+ */
+declare function parsePrice(price: string | number): bigint;
+/**
+ * Parse leverage to contract format (leverage × 100).
+ * @param leverage - Leverage as number (e.g., 20 for 20x)
+ * @returns Bigint (e.g., 2000 for 20x)
+ */
+declare function parseLeverage(leverage: number): bigint;
+
+/**
+ * Precision constants for decimal conversions
+ * Critical for trading calculations - all values must be scaled correctly
+ */
+declare const PRECISION_6 = 1000000n;
+declare const PRECISION_18 = 1000000000000000000n;
+declare const DEFAULT_SLIPPAGE_PERCENTAGE = 0.25;
+declare const MIN_COLLATERAL_USD = 5;
+declare const MAX_COLLATERAL_USD = 2000000;
+
+declare enum OstiumSubgraphErrorCode {
+    INVALID_CONFIG = "INVALID_CONFIG",
+    INVALID_PARAMS = "INVALID_PARAMS",
+    FETCH_FAILED = "FETCH_FAILED",
+    NOT_FOUND = "NOT_FOUND",
+    PARSE_ERROR = "PARSE_ERROR"
+}
+declare class OstiumSubgraphError extends Error {
+    readonly code: OstiumSubgraphErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: OstiumSubgraphErrorCode, cause?: unknown | undefined);
+}
+
+export { type AllPricesResponse, type AllTraders, type AllowanceStatus, type Balances, type CancelLimitOrderParams, type CancelOrderParams, CancelOrderType, type CancelPendingCloseParams, type CancelPendingOpenParams, type Candle, type CandleResolution, type CloseTradeParams, DEFAULT_BUILDER_API_URL, DEFAULT_SLIPPAGE_PERCENTAGE, DEFAULT_SUBGRAPH_ENDPOINT, DEFAULT_SUBGRAPH_ENDPOINT_TESTNET, type DelegatedGaslessParams, type DelegatedSelfParams, type Fill, type FillFees, type OrderType as FillOrderType, type GetCandlesParams, type GetFillsByTimeParams, type GetFillsParams, type GetOpenPositionsParams, type GetOrdersParams, type GetPairsParams, type GetSimOrderbookParams, type GetSimSlippageParams, type GetUserParams, MAX_COLLATERAL_USD, MIN_COLLATERAL_USD, type MarginSummary, type ModifyOrderParams, type OpenOrder, type OpenPositionsResponse, type OpenTradeParams, type Order, type OrderAction, OrderType$1 as OrderType, OstiumClient, type OstiumClientConfig, OstiumError, OstiumErrorCode, OstiumPriceStream, OstiumSubgraphClient, type OstiumSubgraphClientConfig, OstiumSubgraphError, OstiumSubgraphErrorCode, PRECISION_18, PRECISION_6, type Pair, type PairPosition, type PairsResponse, type Position, type PriceData, type PriceTick, type SelfGaslessParams, type SelfSelfParams, type SimOrderbookLevel, type SimOrderbookResponse, type SimSlippageByPairId, type SimSlippageForPair, type SimSlippageRow, type SubmissionResult, type UpdateCollateralParams, parseLeverage, parsePrice, parseUsdc };