Identifiers and Wallet Types

This guide explains when to use Fuel-native vs EVM wallets, and how identifiers map to O2 API/SDK calls.

Wallet choice

  • Fuel-native wallet: best when you want interoperability with other Fuel ecosystem apps.

  • EVM wallet: best when you want to reuse existing EVM accounts across chains and simplify bridging from EVM chains.

Owner identity rule

O2 owner identity is always Fuel B256 (0x + 64 hex chars).

  • Fuel-native wallets provide b256_address directly.

  • EVM wallets provide: - evm_address (0x + 40 hex chars) - b256_address (0x + 64 hex chars)

For EVM wallets:

owner_b256 = 0x000000000000000000000000 + evm_address[2:]

So evm_address is not passed directly as O2 owner_id; b256_address is.

owner_id vs trade_account_id

owner_id and trade_account_id are intentionally different:

  • ``owner_id``: - Wallet identity (B256) for ownership/authentication. - Stable for a given wallet. - Used by setup/session/owner-scoped APIs.

  • ``trade_account_id``: - Trading account contract ID that actually holds exchange balances/positions. - Produced by account setup and stored in the session. - Used by account-state APIs such as balances/orders.

Think of it as: owner identity (owner_id) controls an on-exchange account (trade_account_id).

Which identifier goes where

  • Account/session owner lookups: owner b256_address

  • Trading account state: trade_account_id (contract ID)

  • Market selection: pair string ("fFUEL/fUSDC") or market_id

  • EVM display/bridge context: evm_address

Example

evm_owner = client.generate_evm_wallet()
print(evm_owner.evm_address)    # 20-byte Ethereum address
print(evm_owner.b256_address)   # 32-byte Fuel owner identity (zero-left-padded)

await client.setup_account(evm_owner)  # uses b256_address as owner_id
await client.create_session(owner=evm_owner, markets=["fFUEL/fUSDC"])