API Reference

# .env file
SOCKET_HOST=your-fix-server
SOCKET_PORT=5001
SENDER_COMP_ID=your-sender-id
TARGET_COMP_ID=SERVER

# Credentials (keep secure)
FIX_USERNAME=your-username
FIX_PASSWORD=your-password

# REST & Account
PAPER_REST_BASE_URL=http://localhost:9090
PAPER_ACCOUNT_ID=D1

client.connect()

if client.wait_until_logged_on(timeout=10):
    print("✅ Connected!")
    # ... trading logic ...
    client.disconnect()
else:
    print(f"❌ Failed: {client.last_logon_error()}")

# Place order
cl_ord_id = client.place_order(
    full_symbol="HNXDS:VN30F2511",
    side="BUY",
    qty=1,
    price=1950.0,
    ord_type="LIMIT",  # default
    tif="GTC"          # default: Good Till Cancel
)
print(f"Order placed: {cl_ord_id}")

# Check status
status = client.get_order_status(cl_ord_id)
print(f"Status: {status}")  # NEW, PARTIALLY_FILLED, FILLED, etc.

# Cancel order (async - listen to event for confirmation)
def on_canceled(orig_cl_ord_id, **kw):
    print(f"Canceled: {orig_cl_ord_id}")

client.on("fix:order:canceled", on_canceled)
client.cancel_order(cl_ord_id, timeout=2.0)

# Returns dict with success flag and items list
{
    "success": True,
    "items": [
        {
            "instrument": "HNXDS:VN30F2511",  # Symbol
            "quantity": 2,                    # Position size
            "totalCost": 3900.0,              # Total cost basis
            "currentPrice": 1960.0,           # Current market price
            "marketValue": 3920.0,            # quantity * currentPrice
            "pnl": 20.0                       # Unrealized P&L
        }
    ]
}

# Returns dict with success flag and items list
{
    "success": True,
    "items": [
        {
            "orderId": "2503150001",          # Exchange order ID
            "clOrdId": "abc123...",           # Client order ID
            "symbol": "HNXDS:VN30F2511",      # Instrument
            "side": "1",                      # "1"=BUY, "2"=SELL
            "orderQty": 5,                    # Requested quantity
            "cumQty": 3,                      # Filled quantity
            "leavesQty": 2,                   # Remaining quantity
            "price": 1950.0,                  # Limit price
            "avgPx": 1948.5,                  # Average fill price
            "ordStatus": "PARTIALLY_FILLED"   # Order status
        }
    ]
}

{
    "maxQty": 25,               # Maximum placeable quantity
    "perUnitCost": 1960.0,      # Cost per unit (margin/price)
    "remainCash": 50000.0,      # Available cash/margin
    "unlimited": False          # True if no quantity limit
}

# Query account data
portfolio = client.get_portfolio_by_sub("D1")
print(f"Positions: {len(portfolio)}")
for pos in portfolio:
    print(f"  {pos['instrument']}: {pos['quantity']} @ {pos['currentPrice']}")
    print(f"    P&L: {pos['pnl']}")

# Get max order size
max_info = client.get_max_placeable("HNXDS:VN30F2511", 1950.0, "BUY")
print(f"Max BUY: {max_info['maxQty']} contracts")

# Switch accounts temporarily
with client.use_sub_account("D1"):
    client.place_order("HNXDS:VN30F2511", "SELL", 1, 1950.0)

with client.use_sub_account("D2"):
    client.place_order("HNXDS:VN30F2511", "BUY", 1, 1950.0)
# Restores to default after context exits

# Session events
def on_logon(session_id, **kw):
    print(f"✅ Connected: {session_id}")

def on_logout(session_id, reason=None, **kw):
    print(f"Disconnected: {reason or 'Normal logout'}")

def on_error(error, **kw):
    print(f"❌ Auth failed: {error}")

client.on("fix:logon", on_logon)
client.on("fix:logout", on_logout)
client.on("fix:logon_error", on_error)

# Order events
def on_accepted(cl_ord_id, status, **kw):
    print(f"Order {cl_ord_id[:8]}... accepted: {status}")

def on_filled(cl_ord_id, last_px, last_qty, cum_qty=None, **kw):
    print(f"Filled: {last_qty} @ {last_px}")
    if cum_qty:
        print(f"  Total: {cum_qty}")

def on_rejected(cl_ord_id, reason, **kw):
    print(f"❌ Rejected: {reason}")

client.on("fix:order:accepted", on_accepted)
client.on("fix:order:filled", on_filled)
client.on("fix:order:rejected", on_rejected)

from paperbroker.market_data import RedisMarketDataClient

client = RedisMarketDataClient(
    host=os.getenv("MARKET_REDIS_HOST"),
    port=int(os.getenv("MARKET_REDIS_PORT", 6379)),
    password=os.getenv("MARKET_REDIS_PASSWORD"),
    merge_updates=True  # Full snapshots
)

# Query mode - one-time lookup
quote = await client.query("HNXDS:VN30F2511")
if quote:
    print(f"Price: {quote.latest_matched_price}")

# Subscribe mode - real-time updates
def on_quote(instrument, quote):
    print(f"{instrument}: {quote.latest_matched_price}")

await client.subscribe("HNXDS:VN30F2511", on_quote)

# .env file - Kafka connection
PAPERBROKER_KAFKA_BOOTSTRAP_SERVERS=your-kafka-host:9092
PAPERBROKER_KAFKA_USERNAME=your-username
PAPERBROKER_KAFKA_PASSWORD=your-password
PAPERBROKER_ENV_ID=real

import asyncio
import os
from dotenv import load_dotenv
from paperbroker.market_data import KafkaMarketDataClient

load_dotenv()

async def main():
    # Create Kafka client
    client = KafkaMarketDataClient(
        bootstrap_servers=os.getenv("PAPERBROKER_KAFKA_BOOTSTRAP_SERVERS"),
        username=os.getenv("PAPERBROKER_KAFKA_USERNAME"),
        password=os.getenv("PAPERBROKER_KAFKA_PASSWORD"),
        env_id=os.getenv("PAPERBROKER_ENV_ID"),
        merge_updates=True  # Full snapshots
    )
    
    # Quote callback
    def on_quote(instrument, quote):
        print(f"{instrument}: {quote.latest_matched_price}")
        print(f"  Bid: {quote.bid_price_1} x {quote.bid_quantity_1}")
        print(f"  Ask: {quote.ask_price_1} x {quote.ask_quantity_1}")
    
    # Subscribe and start
    await client.subscribe("HNXDS:VN30F2602", on_quote)
    await client.start()
    
    try:
        while True:
            await asyncio.sleep(1)
    finally:
        await client.stop()

asyncio.run(main())