api — Low-level REST client

The O2Api class provides typed wrappers for every REST endpoint exposed by the O2 Exchange. All methods return typed response objects and raise O2Error on failures.

For most use cases, use O2Client instead, which provides a higher-level interface with automatic market resolution, signing, and nonce management.

The O2Api instance is accessible on the client as client.api for advanced use cases.

See also

The O2 Exchange REST API is documented at https://docs.o2.app.

O2Api

class o2_sdk.api.O2Api(config, session=None)[source]

Low-level REST API client for the O2 Exchange.

Includes automatic rate-limit handling with exponential backoff retries and network error retries (up to 3 attempts).

Parameters:

  • config (NetworkConfig) – Network configuration.

  • session (aiohttp.ClientSession | None) – Optional aiohttp.ClientSession to reuse. If None, a new session is created automatically.

async close()[source]

Close the HTTP session (if owned by this instance).

Market data endpoints

async O2Api.get_markets()[source]

GET /v1/markets — Get all available markets and exchange metadata.

Returns:

Exchange metadata and market definitions.

Return type:

MarketsResponse

async O2Api.get_market_summary(market_id)[source]

GET /v1/markets/summary — Get summary data for a market.

Parameters:

market_id (str) – The market ID.

Return type:

MarketSummary

async O2Api.get_market_ticker(market_id)[source]

GET /v1/markets/ticker — Get ticker data for a market.

Parameters:

market_id (str) – The market ID.

Return type:

MarketTicker

async O2Api.get_depth(market_id, precision=10)[source]

GET /v1/depth — Get order book depth snapshot.

Parameters:

  • market_id (str) – The market ID.

  • precision (int) – Price aggregation precision (default 10).

Return type:

DepthSnapshot

async O2Api.get_trades(market_id, direction='desc', count=50, start_timestamp=None, start_trade_id=None)[source]

GET /v1/trades — Get recent trades for a market.

Parameters:

  • market_id (str) – The market ID.

  • direction (str) – Sort direction ("desc" or "asc").

  • count (int) – Number of trades to return (default 50).

  • start_timestamp (int | None) – Pagination cursor — start timestamp.

  • start_trade_id (str | None) – Pagination cursor — start trade ID.

Return type:

list[Trade]

async O2Api.get_trades_by_account(market_id, contract, direction='desc', count=50)[source]

GET /v1/trades_by_account — Get trades for a specific account.

Parameters:

  • market_id (str) – The market ID.

  • contract (str) – The trading account contract ID.

  • direction (str) – Sort direction.

  • count (int) – Number of trades to return.

Return type:

list[Trade]

async O2Api.get_bars(market_id, from_ts, to_ts, resolution='1h')[source]

GET /v1/bars — Get OHLCV candlestick bars.

Parameters:

  • market_id (str) – The market ID.

  • from_ts (int) – Start timestamp in milliseconds (not seconds).

  • to_ts (int) – End timestamp in milliseconds (not seconds).

  • resolution (str) – Candle resolution (e.g., "1m", "5m", "1h", "1d"). Default "1h".

Return type:

list[Bar]

Account and balance endpoints

async O2Api.create_account(owner_address)[source]

POST /v1/accounts — Create a new trading account.

Parameters:

owner_address (str) – The owner’s B256 address.

Return type:

AccountCreateResponse

async O2Api.get_account(owner=None, trade_account_id=None)[source]

GET /v1/accounts — Get account information.

Provide either owner (B256 address) or trade_account_id.

Parameters:

  • owner (str | None) – The owner’s B256 address.

  • trade_account_id (str | None) – The trading account contract ID.

Return type:

AccountInfo

async O2Api.get_balance(asset_id, contract=None, address=None)[source]

GET /v1/balance — Get balance for a specific asset.

Provide either contract (trading account ID) or address.

Parameters:

  • asset_id (str) – The asset ID.

  • contract (str | None) – The trading account contract ID.

  • address (str | None) – The owner address.

Return type:

Balance

Order endpoints

async O2Api.get_orders(market_id, contract=None, account=None, direction='desc', count=20, is_open=None, start_timestamp=None, start_order_id=None)[source]

GET /v1/orders — Get orders for a market and account.

Parameters:

  • market_id (str) – The market ID.

  • contract (str | None) – The trading account contract ID.

  • account (str | None) – Alternative account identifier.

  • direction (str) – Sort direction ("desc" or "asc").

  • count (int) – Maximum number of orders (default 20).

  • is_open (bool | None) – Filter by open status (True/False/None).

  • start_timestamp (int | None) – Pagination cursor.

  • start_order_id (str | None) – Pagination cursor.

Return type:

OrdersResponse

async O2Api.get_order(market_id, order_id)[source]

GET /v1/order — Get a single order by ID.

Parameters:

  • market_id (str) – The market ID.

  • order_id (str) – The order ID.

Return type:

Order

Session endpoints

async O2Api.create_session(owner_id, session_request)[source]

PUT /v1/session — Create a new trading session.

Sends the O2-Owner-Id header with the owner address.

Parameters:

  • owner_id (str) – The owner’s B256 address.

  • session_request (dict) – The session creation payload.

Return type:

SessionResponse

async O2Api.submit_actions(owner_id, actions_request)[source]

POST /v1/session/actions — Submit signed session actions.

Sends the O2-Owner-Id header. Raises raise_for_error() on failure.

Parameters:

  • owner_id (str) – The owner’s B256 address.

  • actions_request (dict) – The actions payload (signed).

Return type:

ActionsResponse

Account operation endpoints

async O2Api.withdraw(owner_id, withdraw_request)[source]

POST /v1/accounts/withdraw — Submit a signed withdrawal.

Parameters:

  • owner_id (str) – The owner’s B256 address.

  • withdraw_request (dict) – The withdrawal payload (signed).

Return type:

WithdrawResponse

Analytics endpoints

async O2Api.whitelist_account(trade_account_id)[source]

POST /analytics/v1/whitelist — Whitelist a trading account.

Parameters:

trade_account_id (str) – The trading account contract ID.

Return type:

WhitelistResponse

async O2Api.get_referral_info(code)[source]

GET /analytics/v1/referral/code-info — Get referral code info.

Parameters:

code (str) – The referral code.

Return type:

ReferralInfo

Aggregated endpoints

async O2Api.get_aggregated_assets()[source]

GET /v1/aggregated/assets — Get all assets.

Return type:

list[AggregatedAsset]

async O2Api.get_aggregated_orderbook(market_pair, depth=500, level=2)[source]

GET /v1/aggregated/orderbook — Get aggregated order book.

Parameters:

  • market_pair (str) – The trading pair (e.g., "FUEL_USDC").

  • depth (int) – Order book depth (default 500).

  • level (int) – Aggregation level (default 2).

Return type:

dict

async O2Api.get_aggregated_summary()[source]

GET /v1/aggregated/summary — Get market summaries.

Return type:

list[dict]

async O2Api.get_aggregated_ticker()[source]

GET /v1/aggregated/ticker — Get all tickers.

Return type:

list[dict]

async O2Api.get_aggregated_trades(market_pair)[source]

GET /v1/aggregated/trades — Get aggregated trades.

Parameters:

market_pair (str) – The trading pair.

Return type:

list[Trade]

Faucet endpoints

Available on testnet and devnet only.

async O2Api.mint_to_address(address)[source]

Mint test tokens to an address (wallet).

Parameters:

address (str) – The B256 address.

Return type:

FaucetResponse

Raises:

O2Error – If the faucet is not available on this network.

async O2Api.mint_to_contract(contract_id)[source]

Mint test tokens to a contract (trading account).

Parameters:

contract_id (str) – The trading account contract ID.

Return type:

FaucetResponse

Raises:

O2Error – If the faucet is not available on this network.