Skip to content

fastboxex.arena

The Arena object is returned by p.create_arena(), p.join_arena(), or p.reconnect_arena(). It manages lifecycle transitions and connection factories for all sub-users (generator and pre-allocated traders).

Arena

Properties

Property Type Description
arena.arena_id int Numeric arena ID
arena.asset_id int Synthetic asset ID (unique per arena)
arena.invite_code str Code to share with external participants
arena.reference_price int Reference price in raw ticks
arena.credentials list[dict] Credential dicts visible to the caller (all for owner, own sub-users for participant)
arena.generator_credential dict \| None Generator sub-user
arena.trader_credentials list[dict] Pre-allocated trader sub-users
arena.owner_user_id int Real user_id of arena owner

Connecting sub-users

arena.connect_generator(*, label="generator") → Connection

Connect to the generator slot. Call conn.activate(arena.asset_id) immediately after.

gen = arena.connect_generator()
gen.activate(arena.asset_id)

arena.connect_trader(index=0, *, label=None) → Connection

Connect to pre-allocated trader slot index (zero-indexed).

trader0 = arena.connect_trader(0)
trader1 = arena.connect_trader(1)
trader0.activate(arena.asset_id)
trader1.activate(arena.asset_id)

arena.connect_all_traders() → list[Connection]

Connect to all pre-allocated trader slots at once.

traders = arena.connect_all_traders()
for t in traders:
    t.activate(arena.asset_id)

Lifecycle transitions

arena.transition_to(target) → None

Transition the arena's matching engine to the target lifecycle state.

Target Description
"suspended" Orders enter the book; nothing fills
"book_only" Book is visible; still no fills
"trade" Live continuous two-sided matching 
import time
arena.transition_to("suspended") ; time.sleep(0.3)
arena.transition_to("book_only") ; time.sleep(0.5)
arena.transition_to("trade")     ; time.sleep(0.3)

Order matters

Transitions must follow suspended → book_only → trade. Skipping states or going backward raises a lifecycle error.

Cleanup

arena.destroy() → None

Destroy the arena (owner only). Cancels all orders; discards all balances.

p.create_arena() parameters

arena = p.create_arena(
    symbol,                          # e.g. "JTW"
    num_traders         = 2,         # pre-allocated same-user slots (0 → generator only)
    reference_price     = 1_000_000, # raw ticks (= 100.00 display)
    tick_size           = 100,
    lot_size            = 100,
    generator_cash      = 50_000_000_000,
    generator_inventory = 50_000,
    trader_cash         = 1_000_000_000, # per pre-allocated slot
    trader_inventory    = 0,
    joiner_cash         = 1_000_000_000, # per external joiner slot
    joiner_inventory    = 0,
    joiner_num_traders  = 1,         # slots per join call
    max_participants    = 20,        # max unique external joiners
    max_order_qty       = 50_000,
    circuit_breaker_bps = 2_000,
    maker_fee_bps       = 0,
    taker_fee_bps       = 0,
    exchange_fee_bps    = 0,
)
Parameter Default Description
num_traders 0 Pre-allocated same-user trader slots
reference_price required Mid-price anchor in raw ticks
tick_size 100 Minimum price step
lot_size 100 Minimum quantity
generator_cash required Generator starting cash
generator_inventory required Generator starting inventory
trader_cash 0 Cash per pre-allocated slot
trader_inventory 0 Inventory per pre-allocated slot
joiner_cash 0 Cash per external joiner slot
joiner_inventory 0 Inventory per external joiner slot
joiner_num_traders 1 Slots issued per join_arena() call
max_participants 20 Max distinct external joiners
max_order_qty 50_000 Single-order quantity cap
circuit_breaker_bps 2_000 Auto-halt threshold in basis points
maker_fee_bps 0 Maker rebate/fee in bps
taker_fee_bps 0 Taker fee in bps
exchange_fee_bps 0 Exchange fee in bps
Pre-allocated vs joiner slots

Pre-allocated slots (num_traders) are issued at create time and accessed by the arena owner via p.reconnect_arena() → connect_trader(i). They bypass the join flow — no invite code needed.

Joiner slots are issued when an external user calls p.join_arena(code). Each joiner receives joiner_num_traders slots.

Both slot types can coexist in the same arena simultaneously.

Price and circuit-breaker

reference_price anchors the price grid. Set it at the expected mid-price: from_float(100.00) → 1_000_000 raw ticks.

circuit_breaker_bps triggers an automatic halt if the mid drifts more than this many basis points from reference_price: 

halt if |mid - ref| > circuit_breaker_bps / 10_000 × ref
For ref=1_000_000, bps=2_000: halt at ±20% (±200_000 raw ticks = ±20.00 display).