Python SDK

from datetime import datetime
from rivermarkets import RiverMarkets

client = RiverMarkets(
    key_id="<uuid from Settings → API Keys>",
    private_key="<base64 private key shown once at creation>",
)

# Search for shutdown related markets on Kalshi.
# Filter to active markets that haven't expired yet so the results are tradeable —
# apply both `status=active` and `expiration_date_start` (now) for any exchange.
results = client.markets.search_markets(
    q="shutdown",
    exchange_name="KALSHI",
    expiration_date_start=datetime.now(),
    status="active",
)
for market in results.results:
    print(f"River ID: {market.river_id}, Ticker: {market.ticker}")

from rivermarkets import AsyncRiverMarkets

client = AsyncRiverMarkets(key_id="<uuid>", private_key="<base64-priv>")
results = await client.markets.search_markets(
    q="shutdown",
    exchange_name="KALSHI",
    expiration_date_start=datetime.now(),
    status="active",
)

order = client.orders.create_order(
    subaccount_id="your_subaccount_id",
    river_id=4552150,
    order_type="LIMIT",
    time_in_force="GTC",
    buy_flag=True,
    price=0.50,
    qty=10,
)
print(f"Order placed: {order.river_order_id}")

orders = client.orders.list_orders(status="RESTING")
for order in orders.orders:
    print(f"{order.river_order_id}: {order.status}")

client.orders.cancel_order(order_id="your_order_id")

from rivermarkets import RiverMarkets
from rivermarkets.types import IcebergOrderParams

client = RiverMarkets(key_id="...", private_key="...")

order = client.complex_orders.create_complex_order(
    subaccount_id="sub_abc",
    river_id=4552150,
    iceberg_order_params=IcebergOrderParams(
        buy_flag=True,
        total_qty=1000,
        displayed_qty=50,
        limit_price=0.42,
        post_only=True,
    ),
)

from rivermarkets.types import PegOrderParams

order = client.complex_orders.create_complex_order(
    subaccount_id="sub_abc",
    river_id=4552150,
    peg_order_params=PegOrderParams(
        buy_flag=True,
        total_qty=100,
        max_price=0.55,        # ceiling — a buy peg never pays more than this
        post_only=True,
        max_qty_level=5000,    # skip levels bigger than this; rest one tick inside instead
    ),
)

from rivermarkets.types import SmartTakerOrderParams

order = client.complex_orders.create_complex_order(
    subaccount_id="sub_abc",
    river_id=4552150,
    smart_taker_order_params=SmartTakerOrderParams(
        buy_flag=True,
        total_qty=500,
        limit_price=0.30,    # worst price the taker will cross at
        min_qty=100,         # only fire when this much liquidity is available within limit_price
    ),
)

from rivermarkets.types import ConditionalOrderCreate, TriggerOrder

parent = client.orders.create_order(
    subaccount_id="sub_abc", river_id=4552150,
    order_type="LIMIT", time_in_force="GTC",
    buy_flag=True, price=0.40, qty=100,
)

tp = client.complex_orders.create_complex_order(
    subaccount_id="sub_abc",
    river_id=4552150,
    conditional_order_params=ConditionalOrderCreate(
        conditional_order_type="TP",
        parent_river_order_id=parent.river_order_id,
        trigger_order=TriggerOrder(
            order_type="LIMIT", buy_flag=False, qty=100, price=0.55,
        ),
    ),
)

stop = client.complex_orders.create_complex_order(
    subaccount_id="sub_abc",
    river_id=4552150,
    conditional_order_params=ConditionalOrderCreate(
        conditional_order_type="STOP",
        stop_order_price=0.30,
        trigger_order=TriggerOrder(
            order_type="MARKET", buy_flag=False, qty=100,
        ),
    ),
)

positions = client.positions.get_positions()

fills = client.fills.get_fills(subaccount_id="your_subaccount_id")

# Filter to one event
r = client.markets.search_markets(event_ticker="KXNBA-26", limit=20)

# Filter to multiple categories (note: category accepts a list)
r = client.markets.search_markets(
    category=["Sports", "Crypto"],
    subcategory="Basketball",
    sort_by="volume",
    limit=50,
)

# Paginate by events instead of markets
r = client.markets.search_markets(
    event_limit=10,
    event_offset=0,
)

# Browse combos by 24h volume
combos = client.markets.search_markets(include_combos="only", sort_by="trending", event_limit=25)

# Resolve their legs (up to 200 river_ids per call)
resolved = client.markets.resolve_combos(river_ids=[c.river_id for c in combos.results])
for combo in resolved.results:
    for leg in combo.legs:
        print(combo.river_id, leg.ticker, leg.leg_qty, leg.market.name if leg.market else None)

orderbook = client.orderbooks.get_orderbook(river_id=4552150)

prices = client.prices.get_prices(river_id=4552150, type="candlesticks", interval="1d")

import asyncio
from rivermarkets import AsyncRiverMarkets

client = AsyncRiverMarkets(
    key_id="YOUR_KEY_ID",
    private_key="YOUR_BASE64_PRIVATE_KEY",
)

async def stream_orderbook():
    async with client.realtime.orderbooks([6003721, 8927]) as stream:
        async for msg in stream:
            if msg.type == "snapshot":
                print("snapshot", msg.river_id, msg.data["best_bid_price"])
            elif msg.type == "update":
                print("update",   msg.river_id, msg.data["best_bid_price"])

asyncio.run(stream_orderbook())

await stream.subscribe([12345, 67890])
await stream.unsubscribe([6003721])

async with client.realtime.orders(subaccount_id="sub_abc") as stream:
    async for msg in stream:
        if msg.type == "snapshot":
            print(f"{len(msg.orders)} open orders at handshake")
        elif msg.type == "order":
            o = msg.model_extra
            print(f"order {o['id']} → {o['status']}")

async with client.realtime.tradeprints([6003721]) as stream:
    async for msg in stream:
        if msg.type == "trade":
            d = msg.data
            side = "BUY" if d["aggressor_buy_flag"] else "SELL"
            print(f"{d['exchange_timestamp']} {side} {d['qty']} @ {d['price']}")

async with client.realtime.fills(subaccount_id="sub_abc") as stream:
    async for msg in stream:
        if msg.type == "fill":
            print(msg.exchange_trade_id, msg.qty, "@", msg.price, "fee", msg.fee)

# List subaccounts
subaccounts = client.subaccounts.list_subaccounts()

# Create a subaccount
subaccount = client.subaccounts.create_subaccount(name="My Strategy")
print(subaccount.subaccount_id)

# Create a watchlist, optionally seeded with markets
wl = client.watchlists.create_watchlist(
    subaccount_id="sub_abc",
    name="Elections",
    river_ids=[6003721, 8927],
)

# List all watchlists (river_ids come back in display order)
for w in client.watchlists.list_watchlists().watchlists:
    print(w.name, w.river_ids)

# Fetch one with full market details per member
detail = client.watchlists.get_watchlist(wl.watchlist_id)
for m in detail.members:
    print(m.river_id, m.name, m.status)

# Add / remove members
client.watchlists.add_watchlist_members(wl.watchlist_id, river_ids=[12345])
client.watchlists.remove_watchlist_members(wl.watchlist_id, river_ids=[8927])

# Reorder — pass the full ordered river_id list
client.watchlists.reorder_watchlist_members(wl.watchlist_id, river_ids=[12345, 6003721])

# Rename / delete
client.watchlists.update_watchlist(wl.watchlist_id, name="Elections 2026")
client.watchlists.delete_watchlist(wl.watchlist_id)

from rivermarkets.errors import UnprocessableEntityError
from rivermarkets.core.api_error import ApiError

try:
    order = client.orders.get_order(order_id="invalid")
except UnprocessableEntityError as e:
    print(f"Validation error: {e.body}")
except ApiError as e:
    print(f"API error {e.status_code}: {e.body}")

client = RiverMarkets(
    key_id="<uuid>",
    private_key="<base64-priv>",
    base_url="https://api.rivermarkets.com",  # default
    timeout=30.0,                              # seconds, default 60
)