API Reference

# .env file

# --- FIX client (validated by SignalDrivenAlpha.from_paper) ---
PAPER_USERNAME=your-username
PAPER_PASSWORD=your-password
PAPER_REST_BASE_URL=http://localhost:9090
SOCKET_HOST=your-fix-server
SOCKET_PORT=5001
SENDER_COMP_ID=your-sender-id
TARGET_COMP_ID=SERVER

# --- Market data: Redis (default backend) ---
MARKET_REDIS_HOST=your-redis-host
MARKET_REDIS_PORT=6379
MARKET_REDIS_PASSWORD=your-redis-password   # optional

# --- Market data: Kafka (recommended for multi-instrument alphas) ---
PAPERBROKER_KAFKA_BOOTSTRAP_SERVERS=host:port
PAPERBROKER_KAFKA_USERNAME=sasl-user
PAPERBROKER_KAFKA_PASSWORD=sasl-pass
PAPERBROKER_ENV_ID=real

# --- Convention (read by examples, not validated) ---
PAPER_ACCOUNT_ID=main
PAPER_ACCOUNT_ID_D2=V001          # example 03 only
VN30F1M=HNXDS:VN30F2606           # examples 09-14
VN30F2M=HNXDS:VN30F2609           # example 12 pair-spread
EQUITY=HSX:MWG                    # example 07

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 (v0.2.7: tif defaults to "DAY")
cl_ord_id = client.place_order(
    full_symbol="HNXDS:VN30F2606",
    side="BUY",
    qty=1,
    price=1200.0,
    ord_type="LIMIT",  # default
    # tif="DAY"        # default; only TIF Vietnam venues accept
)
print(f"Order placed: {cl_ord_id}")

# Check status (or wait for a specific status)
status = client.get_order_status(cl_ord_id)
client.wait_for(cl_ord_id, statuses={"NEW", "REJECTED"}, timeout=5.0)

# Cancel order — v0.2.6+ returns (is_terminal, status)
is_terminal, final_status = client.cancel_order(cl_ord_id, timeout=5.0)
if is_terminal:
    print(f"Cancel confirmed: {final_status}")
else:
    print(f"Still pending: {final_status}")

# Cleanup terminal orders in long-running processes
if client.is_order_done(cl_ord_id):
    client.cleanup_order(cl_ord_id)

# 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())

from paperbroker.alpha import AlphaContext, Signal, SignalDrivenAlpha

class RSI1MAlpha(SignalDrivenAlpha):
    declared_params = {"rsi_period", "oversold", "overbought"}

    def get_indicators(self, ctx: AlphaContext):
        sym = self.config.instruments[0]
        closes = [b.close for b in ctx.bars[sym]]
        return {"rsi": _rsi(closes, int(self.config.params["rsi_period"]))}

    def get_signals(self, indicators, ctx):
        sym, rsi = self.config.instruments[0], indicators["rsi"]
        if rsi is None: return []
        pos = ctx.positions.get(sym)
        if pos and abs(pos.quantity) > 1e-9:
            if pos.quantity > 0 and rsi > 50: return [Signal(sym, "SELL", tag="exit")]
            if pos.quantity < 0 and rsi < 50: return [Signal(sym, "BUY",  tag="exit")]
            return []
        if rsi < 30: return [Signal(sym, "BUY",  tag="entry")]
        if rsi > 70: return [Signal(sym, "SELL", tag="entry")]
        return []

    def get_entry_price(self, signal, ctx): return ctx.bars[signal.symbol][-1].close
    def get_quantity(self, signal, ctx):    return self.config.qty_for(signal.symbol)


alpha = RSI1MAlpha.from_paper(
    instruments=["HNXDS:VN30F2606"],
    sub_account="main", timeframe="1m", qty=1,
    params={"rsi_period": 14, "oversold": 30, "overbought": 70},
    state_path="state/rsi1m.json",
)
alpha.run()

pip install 'paperbroker_client[cli]'

paperbroker run --config examples/09_alpha_rsi_1m.yaml
paperbroker diagnose

alpha:
  # Dotted module path OR file-path form (supports digit-prefix filenames):
  class: examples/09_alpha_rsi_1m.py:RSI1MAlpha
  instruments:
    - HNXDS:VN30F2606
  sub_account: main
  timeframe: 1m
  qty: 1
  params:
    rsi_period: 14
    oversold: 30
    overbought: 70
  state_path: state/rsi1m.json