Session Management

Manage trading sessions and execute automated trading operations using session keys.

Related task guides:

• Create Order
• Cancel Order
• Order History
• Nonces

Update Trading Session

Create or update a trading session key for automated trading.

PUT /v1/session

Headers

O2-Owner-Id required

Request Body

contract_id required

session_id required

nonce required

expiry required

contract_ids

signature required

Supports both nonce kinds: provide the sequential nonce, or, with the typed signature variant, a parallel_nonce packed as a u256 decimal string so the call does not have to wait behind other in-flight transactions. With parallel_nonce, the typed signature covers ParallelSessionArgs instead of SessionArgs. See Nonces.

Rate Limit: 5 requests/second (Owner ID-based)

Source: packages/api/src/app/routes/v1/session.rs:update_session_handler

Execute Session Actions

Execute trading actions with an active session key.

POST /v1/session/actions

Headers

O2-Owner-Id required

Request Body

Market Selection

Market requiredSelect a market...

Action Type

Action requiredCreateOrderCancelOrder

SideBuySell

Price (in quote asset units)Default: 3000000000000 = 3000.0 USDC (e.g., ETH price)

Quantity (in base asset units)Default: 400000 = 0.0004 ETH (1.2 USDC, meets 1.0 min order)

Order TypeSpotMarketFillOrKillPostOnly

Session actions are grouped by market. A single request supports up to 5 actions total across up to 5 markets, for example 5 actions on 1 market, 1 action on 5 markets, or any equivalent split totaling 5 actions.

Request Structure

{
  "actions": [
    {
      "market_id": "0x1234567890abcdef...",
      "actions": [
        {
          "CreateOrder": {
            "side": "Buy",
            "price": "1000000000",
            "quantity": "100000000",
            "order_type": "Spot"
          }
        },
        {
          "CancelOrder": {
            "order_id": "0xabcdef..."
          }
        }
      ]
    }
  ],
  "signature": {
    "Secp256k1": "0x789..."
  },
  "nonce": "2",
  "trade_account_id": "0xdef456...",
  "session_id": {
    "Address": "0xabc123..."
  },
  "collect_orders": true
}

Top-level fields:

Field	Description
actions	Market-grouped action batches. Each group contains a market_id and its actions.
signature	Session key signature for the action payload. See Session Keys.
nonce	Sequential nonce for the trading account. Provide either nonce or parallel_nonce.
parallel_nonce	Packed parallel nonce decimal string. Provide either parallel_nonce or nonce.
trade_account_id	Trading account contract that owns the session.
session_id	Session key identity authorized on the trading account.
collect_orders	Whether the API should collect created order events before returning.

Constraints

• Maximum 5 actions total.
• Maximum 5 markets per request.
• Supported actions are CreateOrder, CancelOrder, SettleBalance, and RegisterReferer.
• The session must be active, unexpired, and authorized for the target market contracts.
• Requests are subject to the session action rate limit.

Supported Actions

CreateOrder places an order on a market. Use Create Order for order fields and Order Types for Spot, Market, Limit, FillOrKill, PostOnly, and BoundedMarket.

{
  "CreateOrder": {
    "side": "Buy",
    "price": "1000000000",
    "quantity": "100000000",
    "order_type": "Spot"
  }
}

CancelOrder cancels an existing open order by ID. See Cancel Order.

{
  "CancelOrder": {
    "order_id": "0xabcdef..."
  }
}

SettleBalance settles balances to an Identity.

{
  "SettleBalance": {
    "to": {
      "Address": "0x..."
    }
  }
}

RegisterReferer registers a referer Identity.

{
  "RegisterReferer": {
    "referer": {
      "Address": "0x..."
    }
  }
}

collect_orders

Set collect_orders to true when the client needs created order data immediately after submission, such as order IDs for local tracking.

Set collect_orders to false when transaction submission status is enough and the client can rely on Order History or WebSocket order updates for follow-up state.

Nonce Options

Session actions support sequential and parallel nonces.

Sequential nonce flow:

• Provide nonce.
• Omit parallel_nonce.
• Re-fetch the account nonce after failures, retries, or concurrent activity.

Parallel nonce flow:

• Provide parallel_nonce.
• Omit nonce.
• The session signature covers (parallel_nonce, calls): sha256 over the ABI encoding of the packed nonce followed by the reconstructed contract calls, signed by the session key.
• Requests are independent, so inclusion order does not matter.

See Nonces for retry rules and Parallel Nonces for the packed layout and lifecycle.

Response

The response depends on the submitted action set, transaction outcome, and collect_orders.

When collect_orders is enabled, use the returned order data to reconcile newly created orders with local state. For longer-running state changes, subscribe to WebSocket order updates or query Order History.

Common Failures

• More than 5 actions or more than 5 market groups.
• Missing or reused nonce / parallel_nonce.
• Expired session or a session that is not authorized for the target market contract.
• Invalid signature or signature over a mismatched payload.
• On-chain revert from the submitted action, such as an invalid order, unsupported market, or failed fill condition.

See Session Keys troubleshooting, Nonces, and Error Codes.

Rate Limit: 5 requests/second (Owner ID-based)

Source: packages/api/src/app/routes/v1/session.rs:session_actions_handler