coinjure 0.1.0

An intelligent trading agent for Polymarket prediction markets, powered by Social World Models and LLM-driven decision making.

Agent-Native Trading System for Prediction Markets

Coinjure is an agent-native trading stack for prediction markets.

The goal is simple: give an autonomous agent everything it needs to discover, test, and run strategies end-to-end — including managing a portfolio of ~50 parallel spread/arb strategies across Polymarket and Kalshi — while the human operator only does two things:

1. Monitor the system.
2. Pause or emergency-stop when needed.

1-Minute Start

coinjure engine run --exchange polymarket \
  --strategy-ref ./strategies/my_strategy.py:MyStrategy \
  --mode paper --monitor

Why Agent-First

AI agents are now strong enough to self-discover alpha from messy, fast-moving market and news streams. The practical question is no longer "can an agent reason about trades," but:

Can we build the tools, infrastructure, and environment that let an agent operate like a disciplined human trader, but through command-line APIs that are easy for agents to use?

Coinjure is our answer:

• Strategy is the primary interface.
• The engine owns execution, risk checks, and lifecycle.
• Data, simulation, monitoring, and live controls are unified behind CLI commands.

This lets agents iterate quickly, safely, and reproducibly without rebuilding trading plumbing for every strategy or exchange.

System Structure

Core runtime components:

• DataSource: live market/news or historical replay.
• Strategy: async decision logic (process_event).
• Trader: execution adapter (PaperTrader, PolymarketTrader, KalshiTrader).
• RiskManager: pre-trade constraints and safety checks.
• PositionManager: positions, realized/unrealized PnL.
• TradingEngine: event loop, orchestration, monitoring state.
• ControlServer: pause/resume/status/stop via Unix socket.
• Monitor UI: human visibility and emergency controls.
• StrategyRegistry: persistent portfolio registry (~/.coinjure/portfolio.json).
• RelationStore: persistent market relation graph (~/.coinjure/relations.json).

Agent (Claude)
     | bash calls (--json)
     v
CLI Layer (4 groups)
  coinjure market    — discover, analyze, relations, news
  coinjure strategy  — validate, backtest, batch, pipeline, gate
  coinjure engine    — run, list, add, deploy, allocate, report, retire
  coinjure memory    — add, list, best, summary
     | reads/writes ~/.coinjure/
     | spawns subprocesses
     v
[strategy-001]   [strategy-002]  ...  [strategy-050]
engine run       engine run            engine run
(paper process)  (paper process)       (live process)
sock: 001.sock   sock: 002.sock        sock: 050.sock

Each strategy process:
TradingEngine
  |- DataSource (market/news/backtest)
  |- Strategy (agent logic)
  |- Trader (paper/live exchange adapter)
  |  |- RiskManager
  |  |- PositionManager
  |- ControlServer (per-strategy socket)
  |- Monitor UI (operator)

Installation

pip install coinjure

From source:

git clone https://github.com/ulab-uiuc/prediction-market-cli.git
cd prediction-market-cli
pip install poetry
poetry install

Quick Start

1) Explore markets

coinjure market discover -q "election" --exchange both --limit 20 --json
coinjure market analyze --exchange polymarket --market-id <market_id> --json
coinjure market news --source google --query "prediction market" --limit 10

2) Validate a strategy

coinjure strategy validate --strategy-ref ./strategies/my_strategy.py:MyStrategy

# Dry-run smoke check before backtest
coinjure strategy validate \
  --strategy-ref ./strategies/my_strategy.py:MyStrategy \
  --strategy-kwargs-json '{"trade_size": "25"}' \
  --dry-run --events 10 --json

3) Backtest

coinjure strategy backtest \
  --history-file ./data/events.jsonl \
  --market-id M1 --event-id E1 \
  --strategy-ref ./strategies/my_strategy.py:MyStrategy --json

4) Paper trading

coinjure engine run \
  --exchange polymarket --mode paper \
  --strategy-ref ./strategies/my_strategy.py:MyStrategy \
  --strategy-kwargs-json '{"trade_size": "25"}' \
  --monitor

5) Runtime control (separate terminal)

coinjure engine status --id my-strategy-001
coinjure engine pause  --id my-strategy-001
coinjure engine resume --id my-strategy-001
coinjure engine stop   --id my-strategy-001

Spread Trading System

Coinjure includes a spread trading system that discovers, validates, and manages cross-market spread/arbitrage opportunities:

1. Market Discovery (market discover) — multi-keyword search + structural pair detection (temporal implication, cross-platform match, complementary outcomes).
2. Quantitative Analysis (market analyze) — single-market stats or pair analysis (correlation, cointegration, hedge ratio, half-life).
3. Relation Management (market relations) — persistent graph of discovered pairs with lifecycle (active → validated → deployed → retired).
4. Live Maintenance (engine report --check-health) — agent checks status and takes action via pause/retire.

Discover spread opportunities

# Search markets and find structural spread pairs
coinjure market discover -q "election" -q "Trump" --exchange both --limit 50 --json
# -> persists discovered pairs to ~/.coinjure/relations.json

# Quantitative analysis of a single market
coinjure market analyze --exchange polymarket --market-id <id> --json

# Pair analysis (correlation, cointegration, spread stats)
coinjure market analyze --exchange polymarket --market-id <id_a> --compare <id_b> --json

Manage discovered relations

coinjure market relations list --type same_event --json
coinjure market relations add --market-id-a <id_a> --market-id-b <id_b> --spread-type implication --json
coinjure market relations remove <relation_id>

Capital allocation

# Capital allocation across strategies
coinjure engine allocate --method kelly --max-exposure 10000 --json

Portfolio Management

Manage ~50 parallel strategy instances through a single registry:

# Register a new strategy
coinjure engine add \
  --strategy-id arb-nba-001 \
  --strategy-ref coinjure/strategy/builtin/direct_arb_strategy.py:DirectArbStrategy \
  --kwargs-json '{"poly_market_id": "xxx", "kalshi_ticker": "NBANBA-GSW"}' --json

# Deploy to paper trading
# Portfolio report with health diagnostics
coinjure engine report --check-health --json

# Retire a stale strategy
coinjure engine retire --id arb-nba-001 --reason "market_closed" --json

# View all strategies
coinjure engine list --json

# Bulk operations
coinjure engine pause --all --json
coinjure engine stop --all --json
coinjure engine retire --all --reason "end_of_season" --json

Human-in-the-Loop Model

The operator is intentionally lightweight:

• Use coinjure engine monitor for live visibility.
• Use coinjure engine pause|resume|stop for intervention.
• Use coinjure engine killswitch --on for emergency halt.

The operator should not need to manually place/cancel orders in normal operation.

CLI Reference

coinjure market — Market discovery and analysis

Command	Description
market analyze	Quantitative analysis of a market or pair of markets
market discover	Multi-keyword search + structural spread pair discovery
market news	Fetch news headlines
market relations list	List stored market relations
market relations add	Create a relation between two markets
market relations remove	Remove a relation

coinjure strategy — Strategy development and testing

Command	Description
strategy validate	Import-check and optionally feed mock events
strategy backtest	Run a backtest against a local history file

coinjure engine — Running instances and portfolio management

Command	Description
engine run	Start trading (--mode paper|live)
engine list	Show all strategies with lifecycle and PnL
engine add	Register a new strategy
engine status	Show engine status (--full for positions, PnL, order books)
engine pause	Pause event ingestion (--all for all instances)
engine resume	Resume after pause
engine stop	Graceful shutdown (--all for all instances)
engine swap	Hot-swap strategy without restarting
engine retire	Stop and mark as retired (--all for all instances)
engine report	Portfolio PnL report (--check-health for diagnostics)
engine feedback	Record feedback on a strategy
engine monitor	Attach Textual TUI to a running engine
engine killswitch	Toggle the global kill-switch
engine allocate	Capital allocation across strategies

coinjure hub — Shared Market Data Hub

Command	Description
hub start	Start the shared Market Data Hub
hub status	Show hub status
hub stop	Stop the hub

coinjure memory — Experiment memory

Command	Description
memory add	Persist run results to experiment memory
memory list	Query experiment memory
memory best	Show best runs
memory summary	Summarize experiment history

coinjure research — Research tooling

Command	Description
research strategy-gate	Promotion gate with thresholds
research alpha-pipeline	Full alpha discovery pipeline
research batch-markets	Run strategy across N markets
research harvest	Harvest results from completed runs
research feedback-report	Generate feedback report
research market-snapshot	Snapshot market state

Environment Variables

export POLYMARKET_PRIVATE_KEY="your_private_key"
export KALSHI_API_KEY_ID="your_kalshi_key_id"
export KALSHI_PRIVATE_KEY_PATH="/path/key.pem"

Development

poetry install --with dev,test
pre-commit install
ruff check . && ruff format .
mypy coinjure/
pytest tests/ -v

License

MIT

Disclaimer

This software is for educational and research use. Live trading carries financial risk.