Class O2Client

Constructors

constructor

Properties

api

Accessors

session

Methods

[asyncDispose] batchActions cancelAllOrders cancelOrder close createOrder createSession disconnectWs getBalances getBars getDepth getMarket getMarkets getNonce getOrder getOrders getTicker getTrades refreshNonce setSession settleBalance setupAccount streamBalances streamDepth streamLifecycle streamNonce streamOrders streamTrades topUpFromFaucet withdraw generateEvmWallet generateWallet loadEvmWallet loadWallet

Constructors

constructor

Properties

Readonlyapi

api: O2Api

The underlying low-level REST API client.

Accessors

session

Methods

[asyncDispose]

  • "[asyncDispose]"(): Promise<void>

    Enables await using client = new O2Client(...).

    Returns Promise<void>

batchActions

  • batchActions(
        marketActions: MarketActionGroup[],
        collectOrders?: boolean,
    ): Promise<SessionActionsResponse>

    Submit a batch of type-safe actions grouped by market.

    This is the primary batch interface. Actions use the Action union with dual-mode Numeric values — string decimals are auto-scaled, bigint values pass through directly.

    Market resolution, price/quantity scaling, FractionalPrice adjustment, min_order validation, and accounts registry lookup are all handled internally.

    Parameters

    • marketActions: MarketActionGroup[]

      Groups of actions per market.

    • collectOrders: boolean = false

      Whether to return order details in response (default: false).

    Returns Promise<SessionActionsResponse>

    Example

    await client.batchActions([
      { market: "fFUEL/fUSDC", actions: [
        settleBalanceAction(),
        createOrderAction("buy", "0.02", "100"),
        createOrderAction("sell", "0.05", "50", "PostOnly"),
      ]}
    ], true);

cancelAllOrders

cancelOrder

close

  • close(): void

    Close all connections and release resources.

    Returns void

createOrder

  • createOrder(
        market: MarketRef,
        side: "buy" | "sell",
        price: Numeric,
        quantity: Numeric,
        options?: CreateOrderOptions,
    ): Promise<SessionActionsResponse>

    Create an order with automatic encoding, signing, and nonce management.

    Price and quantity accept dual-mode Numeric values:

    • string — human-readable decimal (e.g., "0.02", "100") — auto-scaled
    • bigint — raw chain integer (e.g., 20000000n) — pass-through

    Parameters

    • market: MarketRef

      Market pair string or Market object.

    • side: "buy" | "sell"

      Order side ("buy" or "sell").

    • price: Numeric

      Order price as decimal string or raw bigint.

    • quantity: Numeric

      Order quantity as decimal string or raw bigint.

    • Optionaloptions: CreateOrderOptions

      Optional order parameters.

    Returns Promise<SessionActionsResponse>

createSession

  • createSession(
        wallet: Signer,
        markets: MarketRef[],
        expiryDays?: number,
    ): Promise<SessionState>

    Create a trading session.

    The trade account ID is resolved automatically from the wallet address.

    Parameters

    • wallet: Signer

      The owner wallet.

    • markets: MarketRef[]

      Market pairs or Market objects to authorize.

    • expiryDays: number = 30

      Session expiry in days (default: 30).

    Returns Promise<SessionState>

disconnectWs

  • disconnectWs(): void

    Disconnect WebSocket if connected.

    Returns void

getBalances

getBars

  • getBars(
        market: MarketRef,
        resolution: string,
        from: number,
        to: number,
    ): Promise<Bar[]>

    Fetch OHLCV candlestick bars.

    Parameters

    • market: MarketRef

      Market pair string or Market object.

    • resolution: string

      Bar resolution (e.g., "1m", "1h", "1d").

    • from: number

      Start time in milliseconds (not seconds).

    • to: number

      End time in milliseconds (not seconds).

    Returns Promise<Bar[]>

getDepth

  • getDepth(
        market: MarketRef,
        precision?: number,
        limit?: number,
    ): Promise<DepthSnapshot>

    Fetch the order book depth snapshot.

    Parameters

    • market: MarketRef

      Market pair string or Market object.

    • precision: number = 1

      Price grouping level, from 1 (most precise) to 18 (most grouped). Default 1. At level 1, prices are at or near their exact values. Higher levels round prices into larger buckets — useful for a visual depth chart but too coarse for trading. Same scale as streamDepth.

    • Optionallimit: number

      Maximum number of price levels per side (bids/asks). undefined (default) returns the full order book.

    Returns Promise<DepthSnapshot>

    Throws

    If precision is outside the valid range 1--18.

getMarket

  • getMarket(symbolPair: string): Promise<Market>

    Resolve a market by symbol pair (e.g., "fFUEL/fUSDC") or hex market ID.

    Parameters

    • symbolPair: string

      The market pair or hex ID.

    Returns Promise<Market>

    Throws

    O2Error if the market is not found.

getMarkets

  • getMarkets(): Promise<Market[]>

    Fetch all available markets. Results are cached with stale-while-revalidate.

    Returns Promise<Market[]>

getNonce

  • getNonce(tradeAccountId: TradeAccountId): Promise<bigint>

    Fetch the current on-chain nonce for a trading account.

    Parameters

    Returns Promise<bigint>

getOrder

getOrders

  • getOrders(
        market: MarketRef,
        tradeAccountId: TradeAccountId,
        isOpen?: boolean,
        count?: number,
        cursor?: { startOrderId: string; startTimestamp: number },
    ): Promise<Order[]>

    Fetch orders for an account on a market.

    Parameters

    • market: MarketRef

      Market pair string or Market object.

    • tradeAccountId: TradeAccountId

      The trade account contract ID.

    • OptionalisOpen: boolean

      Filter by open/closed status.

    • count: number = 20

      Number of orders (default: 20, max 200).

    • Optionalcursor: { startOrderId: string; startTimestamp: number }

      Optional pagination cursor. Pass the timestamp and order_id from the last order of the previous page.

    Returns Promise<Order[]>

getTicker

getTrades

  • getTrades(
        market: MarketRef,
        count?: number,
        account?: string | TradeAccountId,
        cursor?: { startTimestamp: number; startTradeId: string },
    ): Promise<Trade[]>

    Fetch recent trades for a market.

    Parameters

    • market: MarketRef

      Market pair string or Market object.

    • count: number = 50

      Number of trades to return (default: 50, max 50).

    • Optionalaccount: string | TradeAccountId

      Optional trade account ID to filter trades for a specific account.

    • Optionalcursor: { startTimestamp: number; startTradeId: string }

      Optional pagination cursor. Pass the timestamp and trade_id from the last trade of the previous page.

    Returns Promise<Trade[]>

refreshNonce

  • refreshNonce(): Promise<bigint>

    Re-fetch the nonce from the API and update the stored session state.

    Returns Promise<bigint>

    The fresh nonce value.

    Remarks

    Call this after errors to re-sync the nonce (it increments on-chain even on reverts).

setSession

settleBalance

setupAccount

  • setupAccount(
        wallet: Signer,
    ): Promise<{ nonce: bigint; tradeAccountId: TradeAccountId }>

    Idempotent account setup. Safe to call on every bot startup.

    1. Check if account exists
    2. Create if needed
    3. Mint via faucet (testnet/devnet) - non-fatal on cooldown
    4. Whitelist account
    5. Return trade_account_id and nonce

    Parameters

    Returns Promise<{ nonce: bigint; tradeAccountId: TradeAccountId }>

streamBalances

streamDepth

  • streamDepth(
        market: MarketRef,
        precision?: number,
    ): Promise<AsyncGenerator<DepthUpdate, any, any>>

    Stream real-time order book depth updates.

    Parameters

    • market: MarketRef

      Market pair string or Market object.

    • precision: number = 1

      Price grouping level, from 1 (most precise) to 18 (most grouped). Default 1. At level 1, prices are at or near their exact values. Higher levels round prices into larger buckets. Same scale as getDepth.

    Returns Promise<AsyncGenerator<DepthUpdate, any, any>>

    An async generator yielding DepthUpdate messages.

    Throws

    If precision is outside the valid range 1--18.

streamLifecycle

  • streamLifecycle(): Promise<AsyncGenerator<ConnectionEvent, any, any>>

    Stream WebSocket connection lifecycle events.

    Yields ConnectionEvent objects whenever the connection state changes (connected, disconnected, reconnecting, reconnected, closed).

    Use this to detect reconnects and re-sync critical state from the REST API — messages during the disconnect window are lost.

    Returns Promise<AsyncGenerator<ConnectionEvent, any, any>>

    Example

    for await (const event of client.streamLifecycle()) {
      if (event.state === "reconnected") {
        const balances = await client.getBalances(account);
      } else if (event.state === "closed") {
        break;
      }
    }

streamNonce

streamOrders

streamTrades

topUpFromFaucet

  • topUpFromFaucet(wallet: Signer): Promise<FaucetResponse>

    Mint test assets from faucet directly to the owner's trading account contract.

    This is useful for explicit testnet/devnet top-ups after account setup.

    Parameters

    • wallet: Signer

      The owner wallet.

    Returns Promise<FaucetResponse>

    Faucet mint response.

    Throws

    O2Error if no trade account exists or faucet is unavailable.

withdraw

  • withdraw(
        wallet: Signer,
        asset: string,
        amount: Numeric,
        to?: string,
    ): Promise<WithdrawResponse>

    Withdraw funds from trading account to owner wallet.

    Parameters

    • wallet: Signer

      The owner wallet (not session key).

    • asset: string

      Asset symbol (e.g., "fUSDC") or hex asset ID.

    • amount: Numeric

      Amount as human-readable string or raw bigint.

    • Optionalto: string

      Destination address (defaults to wallet address).

    Returns Promise<WithdrawResponse>

StaticgenerateEvmWallet

StaticgenerateWallet

  • generateWallet(): WalletState

    Generate a new Fuel-native secp256k1 wallet.

    Returns WalletState

    A new wallet state with a random private key.

    Example

    const wallet = O2Client.generateWallet();
    console.log(wallet.b256Address); // "0x..."

StaticloadEvmWallet

  • loadEvmWallet(privateKeyHex: string): WalletState

    Load an EVM-compatible wallet from a private key hex string.

    Parameters

    • privateKeyHex: string

      The private key as a 0x-prefixed hex string.

    Returns WalletState

    The loaded wallet state with EVM address.

StaticloadWallet

  • loadWallet(privateKeyHex: string): WalletState

    Load a Fuel-native wallet from a private key hex string.

    Parameters

    • privateKeyHex: string

      The private key as a 0x-prefixed hex string.

    Returns WalletState

    The loaded wallet state.

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods