Class O2Api

Low-level REST API client for the O2 Exchange.

Provides typed methods for every REST endpoint. Automatically retries on rate limit errors with exponential backoff and jitter.

Example

import { O2Api, TESTNET } from "@o2exchange/sdk";

const api = new O2Api({ config: TESTNET });
const markets = await api.getMarkets();
console.log(markets.markets.length);

Constructors

constructor

new O2Api(options: O2ApiOptions): O2Api
Parameters
- options: O2ApiOptions
Returns O2Api
- Defined in src/api.ts:94

Properties

`Static` `Readonly`VALID_RESOLUTIONS

VALID_RESOLUTIONS: Set<string> = ...

Valid bar resolutions accepted by the API.

Methods

createAccount

createAccount(identity: Identity): Promise<CreateAccountResponse>
Create a new trading account.
Parameters
- identity: Identity
  The owner identity for the new account.
Returns Promise<CreateAccountResponse>
- Defined in src/api.ts:365

createSession

createSession(
ownerId: string,
request: SessionRequest,
): Promise<SessionResponse>
Create a new trading session.
Parameters
- ownerId: string
  The owner's b256 address.
- request: SessionRequest
  The session creation request.
Returns Promise<SessionResponse>
- Defined in src/api.ts:460

getAccount

getAccount(
    params: {
        owner?: string;
        ownerContract?: string;
        tradeAccountId?: TradeAccountId;
    },
): Promise<AccountInfo>
Fetch account information by owner address, contract, or trade account ID.
Parameters
- params: { owner?: string; ownerContract?: string; tradeAccountId?: TradeAccountId }
  Lookup parameters (provide one of owner, ownerContract, or tradeAccountId).
Returns Promise<AccountInfo>
- Defined in src/api.ts:373

getAggregatedAssets

getAggregatedAssets(): Promise<AggregatedAsset[]>
Fetch all aggregated assets (CoinGecko-compatible).

Returns Promise<AggregatedAsset[]>
- Defined in src/api.ts:535

getAggregatedOrderbook

getAggregatedOrderbook(
    marketPair: string,
    depth?: number,
    level?: number,
): Promise<AggregatedOrderbook>
Fetch aggregated order book (CoinGecko-compatible).
Parameters
- marketPair: string
  The market pair (e.g., "fFUEL_fUSDC").
- depth: number = 500
  Number of levels (default: 500).
- level: number = 2
  Aggregation level (default: 2).
Returns Promise<AggregatedOrderbook>
- Defined in src/api.ts:545

getAggregatedSummary

getAggregatedSummary(): Promise<PairSummary[]>
Fetch aggregated pair summaries (CoinGecko-compatible).

Returns Promise<PairSummary[]>
- Defined in src/api.ts:558

getAggregatedTicker

getAggregatedTicker(): Promise<PairTicker[]>
Fetch aggregated pair tickers (CoinGecko-compatible).

Returns Promise<PairTicker[]>
- Defined in src/api.ts:563

getAggregatedTrades

getAggregatedTrades(marketPair: string): Promise<Trade[]>
Fetch aggregated trades for a pair (CoinGecko-compatible).
Parameters
- marketPair: string
  The market pair (e.g., "fFUEL_fUSDC").
Returns Promise<Trade[]>
- Defined in src/api.ts:571

getBalance

getBalance(
assetId: AssetId,
params: { address?: string; contract?: TradeAccountId },
): Promise<BalanceResponse>
Fetch balance for a specific asset and account.
Parameters
- assetId: AssetId
  The asset ID.
- params: { address?: string; contract?: TradeAccountId }
  Account lookup parameters.
Returns Promise<BalanceResponse>
- Defined in src/api.ts:391

getBars

getBars(
    marketId: MarketId,
    from: number,
    to: number,
    resolution: string,
): Promise<Bar[]>
Fetch OHLCV candlestick bars.
Parameters
- marketId: MarketId
  The market identifier.
- from: number
  Start time in milliseconds (not seconds).
- to: number
  End time in milliseconds (not seconds).
- resolution: string
  Bar resolution. Valid values: 1s, 1m, 2m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M, 3M.
Returns Promise<Bar[]>
Throws
If resolution is not valid.
- Defined in src/api.ts:343

getDepth

getDepth(
    marketId: MarketId,
    precision?: number,
    limit?: number,
): Promise<DepthSnapshot>
Fetch the order book depth snapshot.
Parameters
- marketId: MarketId
  The market identifier.
- precision: number = 10
  Price aggregation precision (default: 10).
- Optionallimit: number
  Maximum number of price levels per side. undefined returns the full book.
Returns Promise<DepthSnapshot>
- Defined in src/api.ts:228

getMarkets

getMarkets(): Promise<MarketsResponse>
Fetch all markets and global registry configuration.

Returns Promise<MarketsResponse>
- Defined in src/api.ts:189

getMarketSummary

getMarketSummary(marketId: MarketId): Promise<MarketSummary>
Fetch 24-hour market summary statistics.
Parameters
- marketId: MarketId
  The market identifier.
Returns Promise<MarketSummary>
- Defined in src/api.ts:206

getMarketTicker

getMarketTicker(marketId: MarketId): Promise<MarketTicker>
Fetch real-time ticker data for a market.
Parameters
- marketId: MarketId
  The market identifier.
Returns Promise<MarketTicker>
- Defined in src/api.ts:216

getOrder

getOrder(marketId: MarketId, orderId: OrderId): Promise<Order>
Fetch a single order by ID.
Parameters
- marketId: MarketId
  The market identifier.
- orderId: OrderId
  The order identifier.
Returns Promise<Order>
- Defined in src/api.ts:443

getOrders

getOrders(
    marketId: MarketId,
    contract: TradeAccountId,
    direction?: "desc" | "asc",
    count?: number,
    isOpen?: boolean,
    startTimestamp?: number,
    startOrderId?: OrderId,
): Promise<OrdersResponse>
Fetch orders for an account on a specific market.
Parameters
- marketId: MarketId
  The market identifier.
- contract: TradeAccountId
  The trade account contract ID.
- direction: "desc" | "asc" = "desc"
  Sort direction (default: "desc").
- count: number = 20
  Number of orders to return (default: 20).
- OptionalisOpen: boolean
  Filter by open/closed status.
- OptionalstartTimestamp: number
- OptionalstartOrderId: OrderId
Returns Promise<OrdersResponse>
- Defined in src/api.ts:413

getReferralInfo

getReferralInfo(code: string): Promise<ReferralInfo>
Fetch referral code information.
Parameters
- code: string
  The referral code.
Returns Promise<ReferralInfo>
- Defined in src/api.ts:528

getTrades

getTrades(
    marketId: MarketId,
    direction?: "desc" | "asc",
    count?: number,
    startTimestamp?: number,
    startTradeId?: string,
    contract?: string,
): Promise<Trade[]>
Fetch recent trades for a market.
Parameters
- marketId: MarketId
  The market identifier.
- direction: "desc" | "asc" = "desc"
  Sort direction (default: "desc").
- count: number = 50
  Number of trades to return (default: 50).
- OptionalstartTimestamp: number
  Optional starting timestamp for pagination.
- OptionalstartTradeId: string
  Optional starting trade ID for pagination.
- Optionalcontract: string
Returns Promise<Trade[]>
- Defined in src/api.ts:263

getTradesByAccount

getTradesByAccount(
    marketId: MarketId,
    contract: TradeAccountId,
    direction?: "desc" | "asc",
    count?: number,
    startTimestamp?: number,
    startTradeId?: string,
): Promise<Trade[]>
Fetch trades for a specific account.
Parameters
- marketId: MarketId
  The market identifier.
- contract: TradeAccountId
  The trade account contract ID.
- direction: "desc" | "asc" = "desc"
  Sort direction (default: "desc").
- count: number = 50
  Number of trades to return (default: 50).
- OptionalstartTimestamp: number
- OptionalstartTradeId: string
Returns Promise<Trade[]>
- Defined in src/api.ts:290

mintToAddress

mintToAddress(address: string): Promise<FaucetResponse>
Mint test tokens to an address (testnet/devnet only).
Parameters
- address: string
  The destination address.
Returns Promise<FaucetResponse>
Throws
O2Error if faucet is not available on this network.
- Defined in src/api.ts:586

mintToContract

mintToContract(contractId: TradeAccountId): Promise<FaucetResponse>
Mint test tokens to a contract (testnet/devnet only).
Parameters
- contractId: TradeAccountId
  The destination contract ID.
Returns Promise<FaucetResponse>
Throws
O2Error if faucet is not available on this network.
- Defined in src/api.ts:610

submitActions

submitActions(
ownerId: string,
request: SessionActionsRequest,
): Promise<SessionActionsResponse>
Submit session actions (create/cancel orders, settle balances).
Parameters
- ownerId: string
  The owner's b256 address.
- request: SessionActionsRequest
  The signed session actions request.
  
  Preflight validation errors (e.g., invalid nonce, insufficient balance) are returned as a SessionActionsResponse with isPreflightError === true rather than thrown.
Returns Promise<SessionActionsResponse>
- Defined in src/api.ts:475

whitelistAccount

whitelistAccount(tradeAccountId: TradeAccountId): Promise<WhitelistResponse>
Whitelist a trading account.
Parameters
- tradeAccountId: TradeAccountId
  The trade account contract ID.
Returns Promise<WhitelistResponse>
- Defined in src/api.ts:518

withdraw

withdraw(ownerId: string, request: WithdrawRequest): Promise<WithdrawResponse>
Withdraw funds from a trading account.
Parameters
- ownerId: string
  The owner's b256 address.
- request: WithdrawRequest
  The signed withdrawal request.
Returns Promise<WithdrawResponse>
- Defined in src/api.ts:506

Class O2Api

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns O2Api

Properties

Static ReadonlyVALID_RESOLUTIONS

Methods

createAccount

Parameters

Returns Promise<CreateAccountResponse>

createSession

Parameters

Returns Promise<SessionResponse>

getAccount

Parameters

Returns Promise<AccountInfo>

getAggregatedAssets

Returns Promise<AggregatedAsset[]>

getAggregatedOrderbook

Parameters

Returns Promise<AggregatedOrderbook>

getAggregatedSummary

Returns Promise<PairSummary[]>

getAggregatedTicker

Returns Promise<PairTicker[]>

getAggregatedTrades

Parameters

Returns Promise<Trade[]>

getBalance

Parameters

Returns Promise<BalanceResponse>

getBars

Parameters

Returns Promise<Bar[]>

Throws

getDepth

Parameters

Returns Promise<DepthSnapshot>

getMarkets

Returns Promise<MarketsResponse>

getMarketSummary

Parameters

Returns Promise<MarketSummary>

getMarketTicker

Parameters

Returns Promise<MarketTicker>

getOrder

Parameters

Returns Promise<Order>

getOrders

Parameters

Returns Promise<OrdersResponse>

getReferralInfo

Parameters

Returns Promise<ReferralInfo>

getTrades

Parameters

Returns Promise<Trade[]>

getTradesByAccount

Parameters

Returns Promise<Trade[]>

mintToAddress

Parameters

Returns Promise<FaucetResponse>

Throws

mintToContract

Parameters

Returns Promise<FaucetResponse>

Throws

submitActions

Parameters

Returns Promise<SessionActionsResponse>

whitelistAccount

Parameters

`Static` `Readonly`VALID_RESOLUTIONS