Upload README.md

README.md

@@ -1,13 +1,11 @@
----
-tags:
-- ml-intern
----
 # BuilderBrain
 
 **Agentic Prediction Market Intelligence** — An AI research and trading agent that reads the prediction-market universe, produces structured probabilities and reasoning traces, and routes orders via Polymarket builder codes, settling capital over Arc using USDC Nanopayments and Gateway.
 
 Built for the **Agora Agents Hackathon** (Canteen × Circle).
 
+**Status:** Core quant engine, reasoning agent, and Polymarket market data are **fully functional**. Arc/Circle settlement layer has **real API skeletons + simulated fallback** — documented with exact integration paths. See [`REAL_VS_SIMULATED.md`](./REAL_VS_SIMULATED.md) for detailed status.
+
 ---
 
 ## What It Does
@@ -26,13 +24,17 @@ Polymarket Data → Reasoning Agent → Kelly Engine → Builder Code Router →
 
 ### Key Features
 
-| Component | What It Does | Why It Wins |
-|-----------|-------------|-------------|
-| **Reasoning Agent** | Generates structured reasoning traces (arguments, evidence, risks) for every trade | "Trading-R1": reasoning as a first-class product, hashed and auditable |
-| **QP Kelly Engine** | Convex optimization for correlation-aware position sizing | References Tepelyan (Bloomberg 2026) Laplace quadrature; achieves 95%+ optimal in <10ms |
-| **Block-Diagonal Correlation** | Politics/crypto/sports/macro theme blocks with intra-theme correlations | Jane Street-level rigor; most teams do independent Kelly |
-| **Builder Code Router** | Routes orders through builder codes, earning fees on every fill | Real monetization; aligns with Polymarket's builder ecosystem |
-| **Arc Integration** | Gateway, Nanopayments, USYC, Paymaster, Wallets | Full Circle primitive showcase |
+| Component | Status | What It Does | Why It Wins |
+|-----------|--------|-------------|-------------|
+| **Reasoning Agent** | ✅ Real | Generates structured reasoning traces (arguments, evidence, risks) for every trade | "Trading-R1": reasoning as a first-class product, hashed and auditable |
+| **QP Kelly Engine** | ✅ Real | Convex optimization for correlation-aware position sizing | References Tepelyan (Bloomberg 2026) Laplace quadrature; achieves 95%+ optimal in <10ms |
+| **Block-Diagonal Correlation** | ✅ Real | Politics/crypto/sports/macro theme blocks with intra-theme correlations | Jane Street-level rigor; most teams do independent Kelly |
+| **Polymarket Data** | ✅ Real | Live market data via Gamma API (public, no auth) | Real prices, liquidity, orderbook |
+| **Builder Code Router** | ⚠️ Simulated | Routes orders through builder codes, earning fees on every fill | Real monetization; fields correct per Polymarket docs |
+| **Circle Gateway** | ⚠️ Simulated | Cross-chain USDC routing via CCTP | Real HTTP client skeleton; needs API key + burn intent encoding |
+| **Arc Nanopayments** | ⚠️ Simulated | Per-trade (5bps) + per-insight (1¢) fees | Architecture correct per x402/EIP-3009 docs; needs signatures |
+| **USYC Yield** | ⚠️ Simulated | 4.3% APY on idle capital with auto risk-off rotation | Real Arc Testnet contracts documented |
+| **Paymaster** | ⚠️ Simulated | Gas-abstracted UX via ERC-4337 | Architecture correct per Pimlico + Circle docs |
 
 ---
 
@@ -42,7 +44,7 @@ Polymarket Data → Reasoning Agent → Kelly Engine → Builder Code Router →
 # Install dependencies
 pip install -r requirements.txt
 
-# Run demo
+# Run demo (simulated mode, works without credentials)
 python demo.py
 ```
 
@@ -59,7 +61,7 @@ brain = BuilderBrain(
     min_edge=0.03,  # 3% minimum edge
 )
 
-# Run one cycle
+# Run one cycle (fetches real Polymarket data)
 signals = brain.run_cycle()
 
 # Get top signals
@@ -72,46 +74,76 @@ for sig in brain.get_top_signals(5):
 brain.export_audit_log("audit.json")
 ```
 
+### Using Real Circle Gateway API
+
+```python
+from builderbrain import BuilderBrain, CircleGatewayClient
+
+# Initialize with real Gateway client
+gateway = CircleGatewayClient(api_key="sk_test_...")
+brain = BuilderBrain(
+    bankroll_usd=10000,
+    arc_bridge=gateway,  # Use real Gateway instead of simulated
+)
+
+# Query balances
+balances = gateway.get_balances(depositor="0x...", domain=0)
+print(balances)
+```
+
 ---
 
 ## Architecture
 
 ```
 builderbrain/
-├── __init__.py           # Package exports
-├── quant_engine.py       # KellyEngine + CorrelationMatrix
-├── polymarket_client.py  # PolymarketClient + BuilderCodeRouter
-├── reasoning_agent.py    # ReasoningAgent + TradeSignal
-├── arc_bridge.py         # ArcBridge + NanopaymentConfig
-└── pipeline.py           # BuilderBrain main orchestrator
-
-demo.py                   # Hackathon demo script
-requirements.txt          # Dependencies
+├── __init__.py                    # Package exports
+├── quant_engine.py                # KellyEngine + CorrelationMatrix (REAL)
+├── polymarket_client.py           # PolymarketClient + BuilderCodeRouter (Market data REAL, orders SIMULATED)
+├── reasoning_agent.py             # ReasoningAgent + TradeSignal (REAL)
+├── arc_bridge.py                  # ArcBridge — simulated with real API patterns documented
+├── circle_gateway_client.py       # CircleGatewayClient — REAL HTTP client for Gateway API
+├── pipeline.py                    # BuilderBrain main orchestrator
+
+demo.py                            # Hackathon demo script
+requirements.txt                   # Dependencies
+.env.example                       # All required credentials for live mode
+REAL_VS_SIMULATED.md              # Detailed real vs simulated breakdown
+tests/
+└── test_quant_engine.py          # Unit tests for Kelly engine
 ```
 
-### Quant Engine (`quant_engine.py`)
+### Quant Engine (`quant_engine.py`) — ✅ FULLY REAL
 
-- **KellyEngine**: Convex QP approximation to multivariate Kelly
+- **KellyEngine**: Convex QP approximation to multivariate Kelly using `cvxpy` + `ECOS` solver
 - **CorrelationMatrix**: Block-diagonal structure (politics, crypto, sports, macro)
 - **Constraints**: Leverage ≤2×, drawdown ≤20%, per-position ≤25%
+- **Reference**: Tepelyan (Bloomberg, 2026) — QP approximation achieves >95% of Laplace quadrature solution in <10ms
 
-### Reasoning Agent (`reasoning_agent.py`)
+### Reasoning Agent (`reasoning_agent.py`) — ✅ FULLY REAL
 
 - **ReasoningTrace**: Complete audit artifact with sources, arguments, risks
 - **TradeSignal**: Executable recommendation with urgency classification
 - **On-chain anchoring**: SHA256 hash of canonical JSON representation
 
-### Polymarket Client (`polymarket_client.py`)
+### Polymarket Client (`polymarket_client.py`) — MIXED
 
-- **PolymarketClient**: Live market data via Gamma API + paper trading
-- **BuilderCodeRouter**: Intelligent builder code selection (category match, fee share, volume)
+- ✅ **Market data**: Live Gamma API calls (public, no auth)
+- ✅ **Orderbook**: Live CLOB API calls
+- ⚠️ **Order execution**: Simulated paper trading; builder code field structure is correct per Polymarket docs
 
-### Arc Bridge (`arc_bridge.py`)
+### Arc Bridge (`arc_bridge.py`) — SIMULATED WITH REAL PATTERNS
 
-- **Gateway + CCTP**: Cross-chain USDC routing
-- **Nanopayments**: Per-trade (5bps) + per-insight (1¢) fees
-- **USYC**: 4.3% APY on idle capital with auto risk-off rotation
-- **Paymaster**: Gas-abstracted UX
+- Documented with exact real API endpoints and request/response schemas
+- Simulated for hackathon demo without credentials
+- Dual mode: pass `gateway_client` for real API calls
+
+### Circle Gateway Client (`circle_gateway_client.py`) — ✅ REAL HTTP CLIENT
+
+- **GET /v1/gateway-info**: Enumerate domains/chains/contracts
+- **POST /v1/balances**: Query unified USDC balance
+- **POST /v1/transfer**: Create transfer attestation (needs burn intent encoding + signatures)
+- Base URL: `https://gateway-api-testnet.circle.com`
 
 ---
 
@@ -147,6 +179,30 @@ s.t.  f ≥ 0
 
 ---
 
+## Real vs Simulated: Migration Path
+
+### Already Working (No Credentials)
+
+- ✅ Live Polymarket market data
+- ✅ Kelly optimization with correlation-aware sizing
+- ✅ Structured reasoning trace generation
+- ✅ Paper trading with builder code field tracking
+
+### Needs Credentials (See `.env.example`)
+
+| Step | What You Need | Estimated Time |
+|------|--------------|---------------|
+| 1. Polymarket builder codes | Register at polymarket.com/settings?tab=builder | 10 min |
+| 2. Circle API key | Sign up at developers.circle.com | 30 min |
+| 3. Gateway transfers | API key + depositor address + domain info | 2-4 hours |
+| 4. Nanopayments | x402 client + EIP-3009 signing | 1 day |
+| 5. USYC yield | Web3 provider + Teller ABI | 2-3 hours |
+| 6. Paymaster | Pimlico bundler + ERC-4337 setup | 1 day |
+
+See [`REAL_VS_SIMULATED.md`](./REAL_VS_SIMULATED.md) for detailed integration paths, exact API endpoints, and contract addresses.
+
+---
+
 ## Hackathon Alignment
 
 ### RFB 02: Prediction Market Trader Intelligence
@@ -223,7 +279,7 @@ Canteen's stack: Market Creation → Liquidity → Resolution → Settlement →
 ```
 numpy>=1.24.0      # Numerical computing
 cvxpy>=1.3.0       # Convex optimization
-requests>=2.28.0   # HTTP client for Polymarket API
+requests>=2.28.0   # HTTP client for Polymarket + Circle APIs
 ```
 
 ---
@@ -244,22 +300,6 @@ requests>=2.28.0   # HTTP client for Polymarket API
 - Canteen (2026). *Unbundling the Prediction Market Stack*.
 - Circle (2026). *USDC OpenClaw Hackathon*.
 
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
-
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
-
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
-
-## Usage
-
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-model_id = "razvan/builderbrain"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
-```
+---
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+*ML Intern generated repository. See source code for implementation details and REAL_VS_SIMULATED.md for integration status.*