Authentication & Signing

o2 uses two keys:

• Owner key: controls the trading account and authorizes privileged actions.
• Session key: temporary trading key used for orders and other session actions.

Use the SDK when possible. It handles signing payloads, session key creation, nonce handling, and request encoding for normal integrations.

For byte layouts and raw signing details, see Session Keys.

SDK Examples

The SDK signs owner operations with the owner wallet and session actions with the session key.

TypeScript

import { Network, O2Client } from "@o2exchange/sdk";

const client = new O2Client({ network: Network.TESTNET });
const wallet = O2Client.loadWallet("0xYOUR_PRIVATE_KEY");

const { tradeAccountId } = await client.setupAccount(wallet);

// Owner-signed: creates or updates the session.
await client.createSession(wallet, ["fFUEL/fUSDC"], 30);

// Session-signed: places the order using the active session.
const result = await client.createOrder("fFUEL/fUSDC", "buy", "1", "5");
console.log(result.txId, tradeAccountId);

Python

from o2_sdk import Network, O2Client, OrderSide, OrderType

client = O2Client(network=Network.TESTNET)
wallet = client.load_wallet("0xYOUR_PRIVATE_KEY")

account = await client.setup_account(wallet)

# Owner-signed: creates or updates the session.
session = await client.create_session(
    owner=wallet,
    markets=["fFUEL/fUSDC"],
    expiry_days=30,
)

# Session-signed: places the order using the active session.
result = await client.create_order(
    market="fFUEL/fUSDC",
    side=OrderSide.BUY,
    price="1",
    quantity="5",
    order_type=OrderType.SPOT,
)
print(result.tx_id, account.trade_account_id, session.session_expiry)

Rust

use o2_sdk::{Network, O2Client, OrderType, Side};
use std::time::Duration;

let mut client = O2Client::new(Network::Testnet);
let wallet = client.load_wallet("0xYOUR_PRIVATE_KEY")?;

let account = client.setup_account(&wallet).await?;

// Owner-signed: creates or updates the session.
let mut session = client
    .create_session(
        &wallet,
        &["fFUEL/fUSDC"],
        Duration::from_secs(30 * 24 * 3600),
    )
    .await?;

// Session-signed: places the order using the session.
let result = client
    .create_order(
        &mut session,
        "fFUEL/fUSDC",
        Side::Buy,
        "1",
        "5",
        OrderType::Spot,
        true,
        true,
    )
    .await?;

println!("{}", result.tx_id.as_deref().unwrap_or("?"));
println!("{:?}", account.trade_account_id);

Owner Key

The owner key controls the trading account.

Owner-key operations include:

• setting up the trading account
• creating or updating sessions
• withdrawals
• account upgrades
• privileged account calls

Owner-authenticated API requests generally include:

O2-Owner-Id: 0x<owner_b256_address>

Use the owner wallet's B256 address, not the trading account contract ID. This header is also used for owner-based rate limiting. See Rate Limits.

Session Key

The session key is an ephemeral key authorized by the owner for day-to-day trading.

Session-key operations include:

• placing orders
• cancelling orders
• settling balances
• registering a referer

Session keys cannot withdraw funds or transfer ownership funds. If a session key is compromised, revoke or replace the session.

For SDK examples, see Sessions and Orders.

When To Use Raw Signing

Use raw signing only when you are building a custom client, debugging signing bytes, or implementing a language without SDK support.

Operation	Signing key	Raw reference
Create/update session	Owner key	Owner Signing
Execute session actions	Session key	Session Signing
Withdraw to Fuel Ignition	Owner key	Withdraw Assets

Signature Types

Secp256k1 is the primary supported signature type for common integrations.

Other signature variants may be defined by the API or contracts, but support can vary by environment. Check Supported Signature Types before using a non-default variant.

Nonces

Signed operations include a replay-protection nonce.

The SDK manages this for common flows. If you are implementing raw requests, use Nonces for sequential nonce, parallel nonce, retry, and concurrency guidance.

Common Failure Modes

• Missing or incorrect O2-Owner-Id
• Signing with the owner key when a session key is required, or vice versa
• Reusing a consumed nonce
• Signing bytes that differ from the submitted action payload
• Using a session that does not include the target market contract ID

For error codes, see Error Codes.