Exchange

Appearance

🌐Network: Mainnet▼

Parameters Reference ​

A comprehensive glossary of all parameters used across the o2 Exchange API endpoints, organized alphabetically for quick reference.

Query Parameters ​

account ​

  • Type: string (Address)
  • Description: User wallet address to filter trades or orders
  • Used in: /trades_by_account, /orders
  • Mutually exclusive with: contract
  • Example: 0xB54142d25D14E7cf0a9e709556071710E73A9cd184aCf79e60eAF6CCA909dC59

address ​

  • Type: string (Address)
  • Description: User wallet address for account identification (legacy parameter name)
  • Used in: Legacy endpoints
  • Example: 0xB54142d25D14E7cf0a9e709556071710E73A9cd184aCf79e60eAF6CCA909dC59

asset_id ​

  • Type: string (AssetId)
  • Description: Asset contract identifier for balance queries or withdrawal operations
  • Used in: /balance (query), /accounts/withdraw (body)
  • Example: 0x789abc...

contract ​

  • Type: string (ContractId)
  • Description: Trading account contract ID
  • Used in: /balance, /trades_by_account, /orders
  • Mutually exclusive with: account
  • Example: 0xabc123...

count ​

  • Type: number (integer)
  • Description: Number of items to return in a single request
  • Used in: /trades, /trades_by_account, /orders
  • Limits: Maximum 50 for /trades and /trades_by_account
  • Example: 25, 50

count_back ​

  • Type: number (integer)
  • Description: Number of historical bars to return. Overrides time range when specified.
  • Used in: /bars
  • Maximum: 5000 bars per request
  • Example: 100

depth ​

  • Type: number (integer)
  • Description: Number of price levels to return on each side (bids and asks)
  • Used in: /aggregated/orderbook
  • Default: 500
  • Maximum: 500
  • Example: 100

direction ​

  • Type: string (enum: "asc" | "desc")
  • Description: Query direction for result ordering
  • Used in: /trades, /trades_by_account, /orders
  • Values:
    • asc: Ascending order (oldest first)
    • desc: Descending order (newest first)
  • Example: desc

from ​

  • Type: number (integer, milliseconds)
  • Description: Start timestamp in milliseconds (Unix epoch time) for historical data range
  • Used in: /bars
  • Example: 1699100000000, 1704067200000

is_open ​

  • Type: boolean
  • Description: Filter to show only open/active orders
  • Used in: /orders
  • Values:
    • true: Return only active/unfilled orders
    • false or omitted: Return all orders
  • Example: true

level ​

  • Type: number (integer, enum: 2 | 3)
  • Description: Order book aggregation level
  • Used in: /aggregated/orderbook
  • Default: 2
  • Values:
    • 2: Aggregated order book (price levels with total volumes)
    • 3: Full depth order book
  • Example: 2

market_id ​

  • Type: string
  • Description: Unique identifier for a trading market
  • Used in: /markets/summary, /markets/ticker, /depth, /trades, /trades_by_account, /bars, /orders, /order
  • Example: c0c5c48315d8cfff9f00777f81fdf04e9b4ef69e802a1a068549a8d6a06ee19f

market_pair ​

  • Type: string
  • Description: Market pair in BASE_QUOTE format (aggregator endpoints alternative to market_id)
  • Used in: /aggregated/orderbook, /aggregated/trades
  • Format: {BASE_ASSET}_{QUOTE_ASSET}
  • Example: FUEL_USDC

order_id ​

  • Type: string
  • Description: Specific order identifier. Must be used together with market_id.
  • Used in: /order
  • Example: 0xorder123...

owner ​

  • Type: string (Address)
  • Description: Owner wallet address to look up the trading account
  • Used in: /accounts
  • Mutually exclusive with: trade_account_id
  • Example: 0xB54142d25D14E7cf0a9e709556071710E73A9cd184aCf79e60eAF6CCA909dC59

precision ​

  • Type: number (integer)
  • Description: Price aggregation precision level. Controls how prices are grouped in order book display.
  • Used in: /depth, WebSocket subscribe_depth
  • Notes: Higher values provide more granular price levels
  • Example: 10

resolution ​

  • Type: string (time unit format)
  • Description: Bar/candlestick time resolution
  • Used in: /bars
  • Supported formats:
    • Minutes: 1m, 5m, 15m, 30m
    • Hours: 1h, 4h, 12h
    • Days: 1d
    • Weeks: 1w
    • Months: 1M
  • Example: 5m, 1h, 1d

start_order_id ​

  • Type: string
  • Description: Starting order ID for pagination. Use with start_timestamp.
  • Used in: /orders
  • Best Practice: Always provide both start_timestamp and start_order_id for stable pagination
  • Example: 0xorder123...

start_timestamp ​

  • Type: string (timestamp)
  • Description: Starting timestamp filter for pagination
  • Used in: /trades, /trades_by_account, /orders
  • Format: Unix timestamp in milliseconds (as string)
  • Best Practice: Use with corresponding start_trade_id or start_order_id for stable pagination
  • Example: 1699200000, 1704067200000

start_trade_id ​

  • Type: string
  • Description: Starting trade ID for pagination. Use with start_timestamp.
  • Used in: /trades, /trades_by_account
  • Best Practice: Always provide both start_timestamp and start_trade_id for stable pagination
  • Example: 0xtrade123...

to ​

  • Type: number (integer, milliseconds)
  • Description: End timestamp in milliseconds (Unix epoch time) for historical data range
  • Used in: /bars
  • Example: 1699200000000, 1704153600000

trade_account_id ​

  • Type: string (ContractId)
  • Description: Trading account contract ID
  • Used in: /accounts (query), /session/actions (body)
  • Mutually exclusive with: owner (when used in /accounts query)
  • Example: 0xabc123...

Header Parameters ​

O2-Owner-Id ​

  • Type: string (B256 format address)
  • Description: Trading account owner address for authentication and authorization
  • Used in: All authenticated account operations
    • PUT /session
    • POST /session/actions
    • POST /accounts/call
    • POST /accounts/calls
    • POST /accounts/upgrade
    • POST /accounts/withdraw
  • Format: 64-character hexadecimal string (with or without 0x prefix)
  • Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Body Parameters ​

Body parameters are organized by the request type they're used in.

actions ​

  • Type: array<MarketActions>
  • Description: Array of market actions to execute. Each element contains a market_id and an array of actions (CreateOrder, CancelOrder, SettleBalance, RegisterReferer). Maximum 5 actions total distributed across maximum 5 markets.
  • Used in: POST /session/actions
  • Constraints:
    • Maximum 5 actions total across all markets
    • Maximum 5 markets per request
    • Each action is validated against market state (e.g., market must not be paused)
  • Structure: [{ market_id: "0x...", actions: [{ CreateOrder: {...} }, { CancelOrder: {...} }] }]
  • Example: See /session/actions endpoint documentation for detailed examples

amount ​

  • Type: string
  • Description: Amount to withdraw (as string to preserve precision). Must be in asset's smallest unit.
  • Used in: POST /accounts/withdraw
  • Example: 1000000

call ​

  • Type: object
  • Description: Contract call parameters object containing method name and arguments
  • Used in: POST /accounts/call
  • Example: { "method": "place_order", "params": { ... } }

calls ​

  • Type: array
  • Description: Array of contract call parameter objects for batch execution
  • Used in: POST /accounts/calls
  • Example: [{ "method": "deposit", "params": {...} }, { "method": "place_order", "params": {...} }]

collect_orders ​

  • Type: boolean
  • Description: When set to true, the API will subscribe to order events and return the created orders in the response. Used with CreateOrder actions to immediately receive order details after transaction confirmation. For fastest confirmations, set this to false.
  • Used in: POST /session/actions
  • Default: false
  • Notes: Only applicable when actions contain CreateOrder operations. Enables real-time order collection with a timeout of 5 seconds.
  • Example: true

contract_id ​

  • Type: string
  • Description: Trading account contract ID for session or account operations
  • Used in: PUT /session, POST /accounts/call, POST /accounts/calls, POST /accounts/upgrade, POST /accounts/withdraw
  • Example: 0xabc123...

estimate_gas_usage ​

  • Type: boolean
  • Description: When true, estimates gas usage for the transaction before execution. Helps prevent out-of-gas errors by calculating required gas based on the operations being performed.
  • Used in: POST /session/actions
  • Default: false
  • Example: false

expiry ​

  • Type: string
  • Description: Session expiry timestamp (Unix epoch time). Session becomes invalid after this time.
  • Used in: PUT /session
  • Example: 1699200000

identity.Address ​

  • Type: string
  • Description: User wallet address for creating a new trading account contract
  • Used in: POST /accounts
  • Example: 0xB54142d25D14E7cf0a9e709556071710E73A9cd184aCf79e60eAF6CCA909dC59

implementation ​

  • Type: string
  • Description: New implementation contract address for account upgrades
  • Used in: POST /accounts/upgrade
  • Example: 0x789...

min_gas_limit ​

  • Type: string
  • Description: Minimum gas limit for the transaction execution. Overrides automatic gas calculation to ensure sufficient gas is available for complex operations. Value is in gas units.
  • Used in: POST /session/actions
  • Notes: Use with caution. Setting too low may cause transaction failure; setting too high increases costs unnecessarily.
  • Example: 1000000

nonce ​

  • Type: string
  • Description: Nonce value for replay attack protection. Must be unique and incrementing.
  • Used in: PUT /session, POST /session/actions, POST /accounts/call, POST /accounts/calls, POST /accounts/upgrade, POST /accounts/withdraw
  • Example: 1, 2, 3

session_id ​

  • Type: object (Identity)
  • Description: Session key identifier. Can be an Address or ContractId identity type used to authorize session-based transactions.
  • Used in: PUT /session, POST /session/actions
  • Structure: { "Address": "0x..." } or { "ContractId": "0x..." }
  • Example: { "Address": "0xabc123..." }

signature ​

  • Type: object (JsonSignature)
  • Description: Cryptographic signature proving ownership and authorization. Supports multiple signature schemes: Secp256r1, Secp256k1, and Ed25519.
  • Used in: PUT /session, POST /session/actions, POST /accounts/call, POST /accounts/calls, POST /accounts/upgrade, POST /accounts/withdraw
  • Structure: { "Secp256k1": "0x..." }, { "Secp256r1": "0x..." }, or { "Ed25519": "0x..." }
  • Example: { "Secp256k1": "0x789..." }

variable_outputs ​

  • Type: number (integer)
  • Description: Number of variable outputs to include in the transaction. Variable outputs allow the transaction to return assets or data to dynamic addresses determined at execution time. Required when transaction outputs are not known in advance.
  • Used in: POST /session/actions
  • Maximum: 10
  • Notes: Each variable output adds to transaction size and gas costs. Only specify the number actually needed.
  • Example: 5

Parameter Patterns & Best Practices ​

Mutual Exclusivity ​

Some parameters cannot be used together:

Account Lookup (GET /accounts):

  • Use owner OR trade_account_id, never both

Trade/Order Filtering (GET /trades_by_account, GET /orders):

  • Use account OR contract, never both

Pagination Pattern ​

When paginating through trades or orders:

  1. Initial Request: Omit pagination parameters

    GET /trades?market_id=XXX&direction=desc&count=50

  2. Subsequent Requests: Use timestamp and ID from last item

    GET /trades?market_id=XXX&direction=desc&count=50&start_timestamp=1699200000&start_trade_id=0xabc...

  3. Direction Usage:

    • desc: Newest first (most common for UI)
    • asc: Oldest first (useful for backfilling)

Rate Limits ​

  • Trades: Maximum 50 items per request
  • Bars (OHLCV): Maximum 5000 bars per request
  • Order Book Depth: Maximum 500 levels per side (aggregator)

Authentication Requirements ​

Authenticated endpoints require:

  1. O2-Owner-Id header with owner address
  2. signature in request body (cryptographically signed)
  3. nonce in request body (unique and incrementing)

The signature must be generated by signing the request payload with the owner's private key.

WebSocket Parameters ​

For WebSocket subscriptions, parameters are sent in the message body:

json
{
  "action": "subscribe_depth",
  "market_id": "c0c5c48315d8cfff9f00777f81fdf04e9b4ef69e802a1a068549a8d6a06ee19f",
  "precision": "10"
}

Available Actions ​

  • subscribe_depth: Order book updates
    • Requires: market_id, precision
  • subscribe_orders: Order updates
    • Requires: market_id, account parameters
  • subscribe_trades: Trade updates
    • Requires: market_id
  • subscribe_balances: Balance updates
    • Requires: account parameters

See System Endpoints for detailed WebSocket examples.