Content
# Betbrain - Prediction Markets Intelligence client of heisenberg.so
Advanced prediction markets analysis (Polymarket, Kalshi) and social signals. Written in Go for maximum performance and minimal dependencies.
**Note**: This is the main betbrain program The MCP server allows future integration as a native extension.
## 📦 Project Structure
```
betbrain/
├── cmd/
│ ├── cli/ # Traditional CLI
│ │ └── main.go
│ └── mcp/ # MCP server for picoclaw integration (extension, not skill)
│ └── main.go
├── internal/
│ ├── api/
│ │ └── client.go # HTTP API client
│ ├── models/
│ │ └── models.go # Data structures
│ └── formatter/
│ └── formatter.go # Output formatting (table/JSON)
├── go.mod
├── Makefile
├── README.md
└── main.go # Entry point (builds CLI by default)
```
## 🚀 Installation
1. Clone or download this repository to any location:
```bash
git clone https://github.com/tu-usuario/betbrain.git
```
2. Configure your API key:
create account in https://api.polymarketanalytics.com/sign-up or generate token and copy
```bash
export PREDICTION_MARKET_API_KEY="your-api-key-here"
```
Or create a `.env` file in the project root:
```
PREDICTION_MARKET_API_KEY=your-api-key-here
```
## 🔨 Build
```bash
# Build CLI only
make cli
# Build MCP server only
make mcp
# Build both
make all
# Clean binaries
make clean
```
## 💻 Usage
### Traditional CLI
```bash
# List markets with filters (unified getmarkets/analyze)
./betbrain markets --closed False --min-volume 1000 --limit 20
# Get specific market by slug
./betbrain markets --market-slug will-trump-win-2024
# Filter by date range (Unix timestamps)
./betbrain markets --end-date-min 1701388800 --end-date-max 1704067199
# Filter by event or condition
./betbrain markets --event-slug bitcoin-up-or-down --condition-id 0xeaff81...
# Filter with pagination
./betbrain markets --limit 50 --offset 100
# Get JSON output
./betbrain markets --closed False --limit 10 --json
# Wallet 360 analysis (window: 1, 3, 7, 15 days)
./betbrain wallet --address 0x1234...abcd --window 7
# Wallet analysis with JSON output
./betbrain wallet --address 0x1234...abcd --window 7 --json
# Heisenberg leaderboard (skilled traders, filters bots)
./betbrain hscore --min-win-rate 0.45 --min-roi 0.2 --min-trades 50 --min-pnl 5000 --sort-by h_score
# Heisenberg leaderboard with custom filters
./betbrain hscore --max-win-rate 0.95 --max-trades 10000 --sort-by roi --limit 50 --json
# Polymarket PnL leaderboard (wallets ranked by realized PnL, 15 days)
./betbrain pnl --min-pnl 5000 --sort-by pnl --limit 50
# PnL leaderboard with ROI and win rate filters
./betbrain pnl --min-roi 0.2 --min-win-rate 0.45 --max-win-rate 0.95 --sort-by roi --json
# Social signals (comma-separated keywords)
./betbrain social --keywords "Trump,election,MAGA" --hours 12
# Social signals with custom limit
./betbrain social --keywords "bitcoin,crypto" --hours 24 --limit 50 --json
# Polymarket orderbook snapshots (Unix timestamps in milliseconds)
./betbrain orderbookp --token-id 69435545313357346912686520645149775930858973121193492847015767460308803044235 --start-time 1769902905868 --end-time 1770034843377
# Orderbook with JSON output
./betbrain orderbookp --token-id 69435545313357346912686520645149775930858973121193492847015767460308803044235 --json
# Official Polymarket leaderboard (period: 1d,1w,1m,3m,6m,1y,all)
./betbrain leaderboard --period 7d --limit 50
# Leaderboard with JSON output
./betbrain leaderboard --period 1m --json
# Trade history with all filters
./betbrain trades --market-slug bitcoin-up-or-down-january-9-10am-et --side BUY --start-time 1767973812 --end-time 1767973860
# Filter trades by wallet address
./betbrain trades --proxy-wallet 0xbbaa9ffc1bcd8772262384a1bd84ad48c99badff --limit 50
# Filter by market and condition ID
./betbrain trades --market-slug will-trump-win-2024 --condition-id 0xeaff81... --limit 20
# Get trades with pagination
./betbrain trades --market-slug bitcoin-up-or-down --limit 10 --offset 20 --json
# OHLCV candlesticks (interval: 1m, 5m, 15m, 30m, 1h, 4h, 1d)
# For active markets - uses last 7 days by default
./betbrain candles --slug will-trump-win-2024 --interval 1h
# For closed markets - suggests the correct timestamp range
./betbrain candles --slug will-israel-attack-iran-by-february-15 --interval 1h
# Output: ⚠️ Market is closed (ended: 2024-02-15)
# 💡 Use: --start-time 1706140800 --end-time 1707955200
# Candlesticks with custom date range
./betbrain candles --slug bitcoin-up-or-down --interval 4h --start-time 1767973812 --end-time 1767980000
# Candlesticks with JSON output
./betbrain candles --slug will-trump-win-2024 --interval 1h --json
# Market quality insights (Market360)
./betbrain insights --slug bitcoin-up-or-down --min-volume 10000
# Insights with condition ID and custom limit
./betbrain insights --slug 0xeaff81... --condition-id 0xeaff81... --limit 50 --json
```
### CLI Commands Reference
| Command | Description | Key Parameters |
|---------|-------------|----------------|
| `markets` | List and analyze markets (unified) | `--closed`, `--min-volume`, `--market-slug`, `--event-slug`, `--condition-id`, `--end-date-min`, `--end-date-max`, `--limit`, `--offset`, `--json` |
| `wallet` | Wallet 360° analysis | `--address` (required), `--window` (1,3,7,15 days), `--json` |
| `hscore` | Heisenberg leaderboard (skilled traders) | `--min-win-rate`, `--max-win-rate`, `--min-roi`, `--min-trades`, `--max-trades`, `--min-pnl`, `--sort-by` (h_score, roi, pnl, win_rate, trades, sharpe), `--limit`, `--offset`, `--json` |
| `pnl` | Polymarket PnL leaderboard (15 days) | `--min-pnl`, `--min-roi`, `--min-win-rate`, `--max-win-rate`, `--min-trades`, `--max-trades`, `--sort-by` (h_score, roi, pnl, win_rate, trades, sharpe), `--limit`, `--offset`, `--json` |
| `social` | Social media signals | `--keywords` (required, comma-separated), `--hours`, `--limit`, `--json` |
| `orderbookp` | Polymarket orderbook snapshots | `--token-id` (required), `--start-time` (ms), `--end-time` (ms), `--json` |
| `leaderboard` | Official Polymarket rankings | `--period` (1d,1w,1m,3m,6m,1y,all), `--limit`, `--json` |
| `trades` | Trade history | `--market-slug`, `--proxy-wallet`, `--condition-id`, `--side` (BUY/SELL), `--start-time`, `--end-time`, `--limit`, `--offset`, `--json` |
| `candles` | OHLCV candlestick data | `--slug` (required), `--interval` (1m,5m,15m,30m,1h,4h,1d), `--start-time`, `--end-time`, `--limit`, `--json` |
| `insights` | Market quality metrics (Market360) | `--slug` (required), `--condition-id`, `--min-volume`, `--limit`, `--json` |
**Global Flags:**
| Flag | Description |
|------|-------------|
| `--mcp` | Run as MCP server (auto-detects when stdin is piped) |
### 🦈 MCP Server (Model Context Protocol)
The MCP server allows integrating this program directly into picoclaw (or any MCP-compatible client) as a native extension via stdio transport:
```bash
# Build and start MCP server (communicates via stdin/stdout)
make mcp
./betbrain --mcp
# Or run the standalone MCP server
go run cmd/mcp/main.go
```
Picoclaw can automatically discover available tools via the `tools/list` method.
**Available MCP Tools:**
| Tool | Description | Required Params |
|------|-------------|-----------------|
| `markets` | List and analyze prediction markets with optional filters | None |
| `wallet` | Comprehensive wallet analysis (360° metrics) | `address` |
| `hscore` | Skilled trader leaderboard (filters out bots) | None |
| `pnl` | Polymarket PnL leaderboard - wallets ranked by realized PnL (15 days) | None |
| `social` | Social signals from Twitter/X | `keywords` |
| `orderbookp` | Polymarket orderbook snapshots - historical order book data | `token_id` |
| `leaderboard` | Official Polymarket leaderboard | None |
| `trades` | Get Polymarket trade history with filters | None |
| `candles` | OHLCV candlestick data for technical charts | `slug` |
| `insights` | Market quality metrics | `slug` |
**Tool Parameters:**
<details>
<summary><b>markets</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `closed` | string | Market status - "False" for open, "True" for closed |
| `min_volume` | string | Minimum trading volume filter |
| `market_slug` | string | Market identifier or keyword search |
| `event_slug` | string | Event identifier |
| `condition_id` | string | Ethereum condition ID |
| `end_date_min` | string | Filter markets ending after this Unix timestamp |
| `end_date_max` | string | Filter markets ending before this Unix timestamp |
| `limit` | number | Limit results (default 100) |
| `offset` | number | Offset for pagination |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>wallet</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `address` | string | Wallet address (required) |
| `window` | string | Calculation window in days (1, 3, 7, 15) |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>hscore</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `min_win_rate` | string | Minimum 15-day win rate (0-1, default: 0.45) |
| `max_win_rate` | string | Maximum 15-day win rate (0-1, default: 0.95) |
| `min_roi` | number | Minimum 15-day ROI (e.g., 0.2 for 20%) |
| `min_trades` | string | Minimum trades in 15 days (default: 50) |
| `max_trades` | string | Maximum trades in 15 days (default: 100000) |
| `min_pnl` | string | Minimum realized PnL in USD over 15 days (default: 5000) |
| `sort_by` | string | Sort by: h_score, roi, pnl, win_rate, trades, sharpe (default: h_score) |
| `limit` | number | Limit results (default: 20) |
| `offset` | number | Offset for pagination |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>pnl</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `min_pnl` | string | Minimum realized PnL in USD (default: 5000) |
| `min_roi` | string | Minimum 15-day ROI (e.g., 0.2 for 20%) |
| `min_win_rate` | string | Minimum 15-day win rate (0-1) |
| `max_win_rate` | string | Maximum 15-day win rate (0-1) |
| `min_trades` | string | Minimum trades in 15 days |
| `max_trades` | string | Maximum trades in 15 days |
| `sort_by` | string | Sort metric: h_score, roi, pnl, win_rate, trades, sharpe (default: pnl) |
| `limit` | number | Limit results (default: 50) |
| `offset` | number | Offset for pagination |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>social</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `keywords` | array | Keywords to track (e.g., `["Trump", "election"]`) |
| `hours` | number | Lookback hours (default: 24) |
| `limit` | number | Maximum number of signals to return (default: 100) |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>orderbookp</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `token_id` | string | Token ID of the market outcome (required) |
| `start_time` | string | Start time (Unix timestamp in milliseconds) |
| `end_time` | string | End time (Unix timestamp in milliseconds) |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>leaderboard</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `period` | string | Period granularity: 1d, 1w, 1m, 3m, 6m, 1y, all (default: 7d) |
| `limit` | number | Limit results (default: 20) |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>trades</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `market_slug` | string | Filter trades by specific market |
| `proxy_wallet` | string | Filter by wallet address |
| `condition_id` | string | Ethereum condition ID for the market |
| `side` | string | Trade direction: "BUY" or "SELL" |
| `start_time` | string | Trades after this Unix timestamp (inclusive) |
| `end_time` | string | Trades before this Unix timestamp (inclusive) |
| `limit` | number | Limit results (default: 10) |
| `offset` | number | Offset for pagination |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>candles</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `slug` | string | Market slug (required) |
| `interval` | string | Time interval: 1m, 5m, 15m, 30m, 1h, 4h, 1d (default: 1h) |
| `start_time` | string | Start of date range (Unix timestamp) |
| `end_time` | string | End of date range (Unix timestamp) |
| `limit` | number | Limit results (default: 100) |
| `json` | boolean | Return JSON output |
</details>
<details>
<summary><b>insights</b></summary>
| Param | Type | Description |
|-------|------|-------------|
| `slug` | string | Market slug (required) |
| `condition_id` | string | Condition ID filter |
| `min_volume` | string | Minimum 24h volume |
| `limit` | number | Limit results (default: 20) |
| `json` | boolean | Return JSON output |
</details>
**Example MCP Call:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "wallet",
"arguments": {
"address": "0x1234...abcd",
"period": "30d"
}
}
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Wallet: 0x1234...abcd\nDays Active: 45\nTotal Volume: $523,412.34\n..."
}
]
}
}
```
**MCP Protocol Details:**
- **Protocol Version:** `2024-11-05`
- **Transport:** stdio (JSON-RPC via stdin/stdout)
- **Server Info:** `prediction-markets v0.1.0`
- **Capabilities:** `tools/list`, `tools/call`
## 📋 API Models
### Overview
The API exposes multiple data models organized by functionality:
| Model | Agent ID(s) | Total Fields | Description |
|-------|-------------|--------------|-------------|
| `SocialSignal` | 585 | 7 | Social media posts with sentiment and engagement |
| `PolymarketMarket` | 574 | 19 | Polymarket markets with complete API data |
| `KalshiMarket` | 565 | 14 | Kalshi markets with tickers and prices |
| `PolymarketTrade` | 556 | 10 | Individual transactions in Polymarket |
| `KalshiTrade` | 573 | 8 | Individual transactions in Kalshi |
| `Candlestick` | 568 | 20 | Complete OHLCV data with bid/ask |
| `TokenPnL` | 569 | 8 | PnL by token/position |
| `LeaderboardEntry` | 579 | 9 | Official Polymarket leaderboard |
| `HScoreLeaderboardEntry` | 584 | 12 | Heisenberg ranking (filters bots) |
| `PnLLeaderboardEntry` | 584 | 12 | Ranking by realized PnL (most profitable wallets) |
| `OrderbookSnapshot` | 572 | 4 | Historical orderbook snapshots with asks/bids |
| `Wallet360` | 581 | 77 | Complete wallet analysis with 70+ performance, risk and anomaly detection metrics |
| `MarketInsights` | 575 | 16 | Advanced market quality metrics |
| `PaginatedResponse[T]` | - | 2 | Generic paginated response structure |
---
## 📦 Detailed Model Reference
### `SocialSignal` (Agent 585)
Social media signals (Twitter/X) with sentiment analysis and engagement metrics.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `post_id` | string | Unique post identifier |
| `platform` | string | Origin platform ("twitter", "x") |
| `content` | string | Full post text |
| `sentiment_score` | float64 | Sentiment score (-1.0 to 1.0) |
| `engagement` | int64 | Total engagement (likes + retweets + replies) |
| `created_at` | time.Time | Post creation date and time |
| `author` | string | Author username |
**JSON Example:**
```json
{
"condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
"question": "Bitcoin Up or Down - January 17, 3PM ET",
"slug": "bitcoin-up-or-down-january-17-3pm-et",
"event_slug": "bitcoin-up-or-down-january-17-3pm-et",
"closed": true,
"volume_total": 104456.76,
"start_date": "2026-01-15T20:01:06.506385Z",
"end_date": "2026-01-17T21:00:00Z",
"close_date": "2026-01-17T22:07:24Z",
"side_a_token_id": "54962395221233298907357564706944806093710338832907683007646483576474886134345",
"side_b_token_id": "99436386356623686771311452414494038846982778884699006473918967429453507432222",
"side_a_outcome": "Up",
"side_b_outcome": "Down",
"winning_outcome": "Up"
}
```
---
### `Outcome` (Submodel)
Structure to represent a market outcome option.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Outcome identifier |
| `name` | string | Human-readable name |
| `price` | float64 | Price/probability (0-1) |
---
### `PolymarketTrade` (Agent 556)
Individual transactions on Polymarket.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `trade_id` | string | Unique transaction ID |
| `market_id` | string | Market ID |
| `tx_hash` | string | Blockchain transaction hash |
| `trader` | string | Trader wallet address |
| `outcome` | string | "yes" or "no" |
| `price` | float64 | Price per share (0-1) |
| `amount` | float64 | Number of shares |
| `total_cost` | float64 | Total transaction cost |
| `created_at` | time.Time | Transaction timestamp |
| `fee` | float64 | Fee paid |
**JSON Example:**
```json
{
"trade_id": "0xabc123...",
"market_id": "0xdef456...",
"tx_hash": "0x789xyz...",
"trader": "0x1234...abcd",
"outcome": "yes",
"price": 0.52,
"amount": 100.0,
"total_cost": 52.0,
"created_at": "2025-03-28T12:45:30Z",
"fee": 0.26
}
```
---
### `KalshiMarket` (Agent 565)
Kalshi markets with tickers and prices in cents format (0-100).
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `ticker` | string | Unique market ticker |
| `event_ticker` | string | Parent event ticker |
| `title` | string | Market title |
| `status` | string | "open" or "finalized" |
| `last_price` | int | Last price in cents (0-100) |
| `volume` | int | Total volume in shares |
| `volume_24h` | int | 24h volume in shares |
| `open_time` | time.Time | Opening date |
| `close_time` | time.Time | Closing date |
| `created_time` | time.Time | Creation date |
| `expiration_time` | time.Time | Expiration date |
| `result` | string (optional) | Final result if resolved |
**JSON Example:**
```json
{
"ticker": "KXBTC15M-26FEB030730-30",
"event_ticker": "KXBTC-25",
"title": "Will Bitcoin exceed $70,000 by March 31?",
"status": "open",
"last_price": 62,
"volume": 15432,
"volume_24h": 2341,
"open_time": "2025-02-26T03:07:30Z",
"close_time": "2025-03-31T23:59:59Z",
"created_time": "2025-01-15T08:00:00Z",
"expiration_time": "2025-04-01T00:00:00Z"
}
```
---
### `PolymarketTrade` (Agent 556)
Individual transactions on Polymarket.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique transaction identifier |
| `condition_id` | string | Ethereum contract condition ID |
| `price` | float64 | Price per share (range 0-1) |
| `side` | string | Trade direction: "BUY" or "SELL" |
| `size` | float64 | Number of shares traded |
| `timestamp` | string (ISO 8601) | Trade execution timestamp |
| `transaction_hash` | string | Ethereum transaction hash |
| `slug` | string | Market identifier |
| `outcome` | string | Trade outcome (e.g. "Yes", "No") |
| `proxy_wallet` | string | Trader wallet address |
**JSON Example:**
```json
{
"condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
"id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0x1e30835026c910cd5f676a504ce8c39666917f402dfe93bb46c19adf6b152c13",
"outcome": "Down",
"price": 0.001,
"proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
"side": "BUY",
"size": 225.23,
"slug": "bitcoin-up-or-down-january-9-10am-et",
"timestamp": "2026-01-09T15:51:00Z",
"transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
}
```
**API Request Parameters:**
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `market_slug` | string | Filter trades by specific market | `"bitcoin-up-or-down-january-9-10am-et"` |
| `proxy_wallet` | string | Filter by wallet address | `"0xbbaa9ffc1bcd8772262384a1bd84ad48c99badff"` |
| `condition_id` | string | Ethereum condition ID of the market | `"0xb0fb3465776819e046055164c6fc355e9d3d7da36cd7a2ef7c7658791784e97d"` |
| `side` | string | Trade direction: "BUY" or "SELL" | `"SELL"` |
| `start_time` | string (Unix timestamp) | Trades after this timestamp (inclusive) | `"1603719954"` |
| `end_time` | string (Unix timestamp) | Trades before this timestamp (inclusive) | `"2237550354"` |
---
### `KalshiTrade` (Agent 573)
Individual transactions on Kalshi.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `trade_id` | string | Unique transaction ID |
| `ticker` | string | Market ticker |
| `taker_side` | string | "yes" or "no" |
| `yes_price` | int | YES price in cents (0-100) |
| `no_price` | int | NO price in cents (0-100) |
| `count` | int | Number of shares |
| `created_time` | time.Time | Transaction timestamp |
| `total_cost` | float64 | Total cost in USD |
**JSON Example:**
```json
{
"trade_id": "0xdef456...",
"ticker": "KXBTC15M-26FEB030730-30",
"taker_side": "yes",
"yes_price": 62,
"no_price": 38,
"count": 100,
"created_time": "2025-03-28T14:20:00Z",
"total_cost": 62.0
}
```
---
### `Candlestick` (Agent 568)
Complete OHLCV data for technical charts with bid/ask.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `candle_time` | string (ISO 8601) | Start of time interval |
| `open` | string (decimal) | Opening price (0-1) |
| `high` | string (decimal) | Highest price in interval (0-1) |
| `low` | string (decimal) | Lowest price in interval (0-1) |
| `close` | string (decimal) | Closing price (0-1) |
| `mean` | string (decimal) | Average price in interval |
| `volume` | string (decimal) | Trading volume in USD |
| `trade_count` | integer | Number of trades in interval |
| `outcome` | string | Market outcome (Yes/No) |
| `condition_id` | string | Ethereum condition ID |
| `token_id` | string | Blockchain token ID |
| `ask_open` | string (decimal, nullable) | Opening ask price |
| `ask_high` | string (decimal, nullable) | Highest ask price |
| `ask_low` | string (decimal, nullable) | Lowest ask price |
| `ask_close` | string (decimal, nullable) | Closing ask price |
| `bid_open` | string (decimal, nullable) | Opening bid price |
| `bid_high` | string (decimal, nullable) | Highest bid price |
| `bid_low` | string (decimal, nullable) | Lowest bid price |
| `bid_close` | string (decimal, nullable) | Closing bid price |
**JSON Example:**
```json
{
"candle_time": "2026-02-01T04:00:00Z",
"open": "0.5000",
"high": "0.5100",
"low": "0.5000",
"close": "0.5100",
"mean": "0.5038",
"volume": "1020.08",
"trade_count": 15,
"outcome": "No",
"condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
"token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
"ask_open": "0.9900",
"ask_high": "0.9900",
"ask_low": "0.5100",
"bid_open": "0.0100",
"bid_high": "0.5000",
"bid_low": "0.0100"
}
```
**API Request Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `token_id` | string | Market token identifier (**required**) |
| `interval` | string | Interval: "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w" |
| `start_time` | string (Unix timestamp) | Start of date range (**required**) |
| `end_time` | string (Unix timestamp) | End of date range (**required**) |
**Note:** The CLI automatically handles time ranges:
- **Active markets:** Uses the last 7 days by default
- **Closed markets:** Suggests the market's active period and uses that range automatically
**Interval Limits:**
| Interval | Max Range |
|----------|-----------|
| 1m | 7 days |
| 5m | 15 days |
| 15m | 30 days |
| 1h | 90 days |
| 4h | 180 days |
| 1d | 360 days |
| 1w | 360 days |
**Note:** The `token_id` is automatically obtained when specifying a `market_slug`. The CLI looks up the market and uses the first outcome's token ID (usually "YES").
---
### `TokenPnL` (Agent 569)
PnL by specific token/position.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `token_id` | string | Token/market ID |
| `realized_pnl` | float64 | Realized PnL (USD) |
| `unrealized_pnl` | float64 | Unrealized PnL (USD) |
| `total_pnl` | float64 | Total PnL (realized + unrealized) |
| `position_size` | float64 | Position size in USD |
| `entry_price` | float64 | Average entry price |
| `exit_price` | float64 (optional) | Exit price (if closed) |
**JSON Example:**
```json
{
"token_id": "0x1234...",
"realized_pnl": 1250.50,
"unrealized_pnl": 340.25,
"total_pnl": 1590.75,
"position_size": 5000.00,
"entry_price": 0.45,
"exit_price": 0.62
}
```
---
### `LeaderboardEntry` (Agent 579)
Official Polymarket leaderboard ranking.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `rank` | int64 | Ranking position |
| `wallet` | string | Wallet address |
| `total_pnl` | float64 | Total accumulated PnL (USD) |
| `win_rate` | float64 | Percentage of winning trades (0-1) |
| `total_trades` | int64 | Total number of trades |
| `best_trade` | float64 | Best trade (maximum gain) |
| `worst_trade` | float64 | Worst trade (maximum loss) |
| `avg_holding_time` | int64 | Average holding time (seconds) |
**JSON Example:**
```json
{
"rank": 1,
"wallet": "0xabcd...1234",
"total_pnl": 1254300.50,
"win_rate": 0.68,
"total_trades": 3421,
"best_trade": 45678.90,
"worst_trade": -12345.67,
"avg_holding_time": 86400
}
```
---
### `HScoreLeaderboardEntry` (Agent 584)
Heisenberg ranking (filters bots, measures real skill).
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `rank` | int64 | H-Score ranking position |
| `wallet` | string | Wallet address |
| `h_score` | float64 | H-Score rating (0-100) |
| `h_score_change` | float64 | H-Score change (last period) |
| `activity_score` | float64 | Activity rating |
| `reputation_score` | float64 | Reputation rating |
| `engagement_count` | int64 | Number of interactions |
| `last_updated` | time.Time | Last score update |
**JSON Example:**
```json
{
"rank": 1,
"wallet": "0xabcd...1234",
"h_score": 94.5,
"h_score_change": 2.3,
"activity_score": 88.7,
"reputation_score": 96.2,
"engagement_count": 15234,
"last_updated": "2025-03-28T00:00:00Z"
}
```
---
### `PnLLeaderboardEntry` (Agent 584)
Wallet ranking by realized PnL (last 15 days). Optimized to identify consistently profitable traders.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `leaderboard_rank` | int | PnL ranking position |
| `wallet` | string | Wallet address |
| `tier` | string | Category: Elite, Sharp, Solid, Emerging |
| `h_score` | string | Heisenberg Score (composite) |
| `roi_pct_15d` | string | ROI in last 15 days (%) |
| `win_rate_pct_15d` | string | Win rate in last 15 days (%) |
| `sharpe_ratio_15d` | string (nullable) | Sharpe ratio in 15 days |
| `total_trades_15d` | int | Total trades in 15 days |
| `markets_traded_15d` | int | Unique markets traded |
| `total_pnl_15d` | string | Realized PnL in USD (15 days) |
| `total_volume_15d` | string | Total volume in USD (15 days) |
| `trajectory` | string | Trend: improving, stable, declining |
**JSON Example:**
```json
{
"leaderboard_rank": 1,
"wallet": "0xa6ee41b52d95508b8ce3241fc2c6c487dfd97bd7",
"tier": "Sharp",
"h_score": "56.349",
"roi_pct_15d": "91.7",
"win_rate_pct_15d": "51.4",
"sharpe_ratio_15d": null,
"total_trades_15d": 2379,
"markets_traded_15d": 57,
"total_pnl_15d": "64332.02",
"total_volume_15d": "70120.66",
"trajectory": "stable"
}
```
**Filter Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `min_roi_15d` | string | "0" | Minimum ROI in 15 days (e.g. "0.2" = 20%) |
| `min_win_rate_15d` | string | "0.45" | Minimum win rate (0-1) |
| `max_win_rate_15d` | string | "0.95" | Maximum win rate (0-1) |
| `min_total_trades_15d` | string | "50" | Minimum trades in 15 days |
| `max_total_trades_15d` | string | "100000" | Maximum trades in 15 days |
| `min_pnl_15d` | string | "5000" | Minimum realized PnL in USD |
| `sort_by` | string | "pnl" | Sort metric: h_score, roi, pnl, win_rate, trades, sharpe |
**CLI Usage:**
```bash
# Top wallets by PnL (default)
./betbrain pnl
# Filter by win rate and minimum ROI
./betbrain pnl --min-win-rate 0.5 --min-roi 0.2 --min-pnl 10000
# Sort by ROI instead of PnL
./betbrain pnl --sort-by roi
# More results with pagination
./betbrain pnl --limit 100 --offset 50
# JSON output
./betbrain pnl --json
```
---
### `OrderbookSnapshot` (Agent 572)
Historical orderbook snapshots for a specific token over a time range.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `timestamp` | string (ISO 8601) | Snapshot timestamp |
| `token_id` | string | Market outcome token ID |
| `asks` | string (JSON) | Array of asks as JSON string: `[{"size": "60", "price": "0.99"}]` |
| `bids` | string (JSON) | Array of bids as JSON string: `[{"size": "60", "price": "0.01"}]` |
**JSON Example:**
```json
{
"timestamp": "2026-02-02T12:01:20.885Z",
"token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
"asks": "[{\"size\": \"60\", \"price\": \"0.99\"}, {\"size\": \"723.17\", \"price\": \"0.93\"}]",
"bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"25\", \"price\": \"0.02\"}, {\"size\": \"200\", \"price\": \"0.28\"}]"
}
```
**Filter Parameters:**
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `token_id` | string | Outcome token ID (required) | `"694355453133..."` |
| `start_time` | string | Unix timestamp in milliseconds (start) | `"1769902905868"` |
| `end_time` | string | Unix timestamp in milliseconds (end) | `"1770034843377"` |
**CLI Usage:**
```bash
# Orderbook for a specific market
./betbrain orderbookp --token-id 69435545313357346912686520645149775930858973121193492847015767460308803044235
# With custom time range (timestamps in milliseconds)
./betbrain orderbookp --token-id <token_id> --start-time 1769902905868 --end-time 1770034843377
# JSON output for processing
./betbrain orderbookp --token-id <token_id> --json
```
**Note:** The `start_time` and `end_time` timestamps must be in **milliseconds** (not seconds). To convert from Unix seconds:
```
milliseconds = seconds * 1000
```
---
### `Wallet360` (Agent 581)
Complete wallet analysis (360° view) with advanced performance, risk and anomaly detection metrics.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `date` | string (ISO 8601) | Aggregation date |
| `proxy_wallet` | string | Wallet address |
| `calculation_window_days` | int | Calculation window in days |
| `date_range_start` | string (ISO 8601) | Window start date |
| `date_range_end` | string (ISO 8601) | Window end date |
| `total_trades` | int | Total number of trades |
| `winning_trades` | int | Number of winning trades |
| `losing_trades` | int | Number of losing trades |
| `win_rate` | float64 | Proportion of winning trades (0-1) |
| `total_pnl` | float64 | Total PnL (USD) |
| `total_invested` | float64 | Total capital invested (USD) |
| `roi` | float64 | Return on investment (0-1) |
| `markets_traded` | int | Number of unique markets |
| `last_active` | string (ISO 8601) | Last activity timestamp |
| `avg_position_size` | float64 | Average position size (USD) |
| `best_trade` | float64 | Most profitable trade (USD) |
| `worst_trade` | float64 | Least profitable trade (USD) |
| `sharpe_ratio` | float64 | Sharpe ratio |
| `sortino_ratio` | float64 | Sortino ratio |
| `calmar_ratio` | float64 | Calmar ratio |
| `max_drawdown` | float64 | Maximum drawdown (0-1) |
| `profit_factor` | float64 | Gross profit / Gross loss |
| `ulcer_index` | float64 | Ulcer index (drawdown severity) |
| `gain_to_pain_ratio` | float64 | Total gains / Total losses |
| `drawdown_frequency` | float64 | Drawdown frequency |
| `recovery_time_avg` | float64 | Average recovery time (days) |
| `performance_trend` | string | Performance trend (improving/stable/declining) |
| `edge_decay` | float64 | Statistical edge degradation |
| `performance_by_category` | string (JSON) | Performance by category |
| `category_diversity_score` | float64 | Diversification score |
| `days_active` | int | Days of activity |
| `annualized_return` | float64 | Annualized return |
| `win_rate_last_30d` | float64 | Win rate last 30 days |
| `win_rate_z_score` | float64 | Statistical deviation of win rate |
| `suspicious_win_rate_flag` | bool | TRUE if win rate is suspicious |
| `dominant_market_id` | string | Market generating most PnL |
| `dominant_market_pnl` | float64 | PnL from dominant market |
| `market_concentration_ratio` | float64 | Concentration in top market |
| `num_markets_traded` | int | Total distinct markets |
| `single_market_dependence_flag` | bool | TRUE if dependent on single market |
| `suspicious_timing_trades` | int | Trades with suspicious timing |
| `total_timed_trades` | int | Total trades evaluated |
| `timing_hit_rate` | float64 | Timing success rate |
| `timing_z_score` | float64 | Statistical deviation of timing |
| `timing_anomaly_flag` | bool | TRUE if timing anomaly detected |
| `stddev_position_size` | float64 | Standard deviation of position size |
| `coefficient_of_variation` | float64 | Relative variability of size |
| `position_size_volatility_flag` | bool | TRUE if position size is volatile |
| `similar_wallets_count` | int | Wallets with correlated behavior |
| `trade_timing_correlation_max` | float64 | Maximum timing correlation |
| `sybil_risk_score` | float64 | Sybil risk score (0-1) |
| `sybil_risk_flag` | bool | TRUE if Sybil risk detected |
| `perfect_entry_count` | int | Perfectly timed entries |
| `perfect_exit_count` | int | Perfectly timed exits |
| `total_closed_positions` | int | Total closed positions |
| `perfect_timing_score` | float64 | Composite timing score |
| `perfect_timing_flag` | bool | TRUE if timing is abnormal |
| `combined_risk_score` | float64 | Aggregate risk score |
| `risk_level` | string | Classification (LOW/MEDIUM/HIGH) |
| `flagged_metrics` | []string | Flagged risk metrics |
| `statistical_confidence` | float64 | Statistical confidence (0-1) |
| `curve_smoothness` | float64 | Equity curve smoothness |
| `equity_curve_pattern` | string | Equity curve pattern |
| `trade_size_stdev` | float64 | Standard deviation of trade sizes |
| `max_position_pct` | float64 | Max position as % of capital |
| `position_size_consistency` | float64 | Position size consistency |
**Response:**
```json
{
"timestamp": "",
"params": {
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"window_days": "3"
},
"pagination": {
"limit": 100,
"offset": 0,
"has_more": true
},
"data": {
"results": [
{
"date": "2026-01-04T00:00:00Z",
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"calculation_window_days": 3,
"date_range_start": "2026-01-02T00:00:00Z",
"date_range_end": "2026-01-04T00:00:00Z",
"total_trades": 2930,
"winning_trades": 252,
"losing_trades": 245,
"win_rate": 0.507,
"total_pnl": -118529.16,
"total_invested": 282952.23,
"roi": -41.8902,
"markets_traded": 389,
"last_active": "2026-01-04T23:59:59.999999Z",
"avg_position_size": 727.38,
"best_trade": 6943.19,
"worst_trade": -68604.58,
"sharpe_ratio": -11.6995,
"sortino_ratio": -9.3802,
"calmar_ratio": -100,
"max_drawdown": 0.1235,
"profit_factor": 0.6114,
"ulcer_index": 7.1328,
"gain_to_pain_ratio": -0.9401,
"drawdown_frequency": 0.3333,
"recovery_time_avg": 0,
"performance_trend": "declining",
"edge_decay": null,
"performance_by_category": "W3sicG5sIjogLTEyLjEsICJ0cmFkZXMiOiAxLCAiY2F0ZWdvcnkiOiAiV29ybGQgRXZlbnRzIn0sIHsicG5sIjogLTI1ODc4Ljk1LCAidHJhZGVzIjogMzk5LCAiY2F0ZWdvcnkiOiAiT3RoZXIifSwgeyJwbmwiOiAtOTI2MzguMSwgInRyYWRlcyI6IDIxMiwgImNhdGVnb3J5IjogIlNwb3J0cyJ9XQ==",
"category_diversity_score": 0.7586,
"days_active": 3,
"annualized_return": -50.9664,
"win_rate_last_30d": 0.4828,
"win_rate_z_score": 2.68,
"suspicious_win_rate_flag": false,
"dominant_market_id": "0xaa1203d00f7c8166ecf8a6da6fb1b63a2cd8456fb56dfd5805834f5e6670f9b4",
"dominant_market_pnl": -68604.58,
"market_concentration_ratio": 0.1424,
"num_markets_traded": 389,
"single_market_dependence_flag": false,
"suspicious_timing_trades": 0,
"total_timed_trades": 2930,
"timing_hit_rate": 0,
"timing_z_score": 0.86,
"timing_anomaly_flag": false,
"stddev_position_size": 1625.04,
"coefficient_of_variation": 2.2226,
"position_size_volatility_flag": true,
"similar_wallets_count": 0,
"trade_timing_correlation_max": 0,
"sybil_risk_score": 0,
"sybil_risk_flag": false,
"perfect_entry_count": 93,
"perfect_exit_count": 0,
"total_closed_positions": 211,
"perfect_timing_score": 0.2204,
"perfect_timing_flag": false,
"combined_risk_score": 10,
"risk_level": "LOW",
"flagged_metrics": "{position_size_volatility}",
"statistical_confidence": 0.9815,
"curve_smoothness": 0.4181,
"equity_curve_pattern": "volatile",
"trade_size_stdev": 383.6896,
"max_position_pct": 3.7087,
"position_size_consistency": 0
}
]
}
}
```
**Note:** The API returns an array of results in `data.results[]`. Each element represents metrics for a different date. The client returns the first (most recent) result by default.
`performance_by_category` is base64-encoded JSON. `edge_decay` can be `null`. `flagged_metrics` is a string like `"{position_size_volatility}"`.
---
### `MarketInsights` (Agent 575)
Advanced market quality metrics (AI-powered).
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `market_id` | string | Market ID |
| `question` | string | Market question |
| `current_price` | float64 | Current price (0-1) |
| `volume_24h` | float64 | 24h volume (USD) |
| `liquidity` | float64 | Liquidity (USD) |
| `sentiment_score` | float64 | Sentiment score (-1 to 1) |
| `volatility_index` | float64 | Volatility index |
| `momentum` | float64 | Momentum score |
| `trend_direction` | string | "bullish", "bearish", "neutral" |
| `signal_strength` | float64 | Signal strength (0-1) |
| `predicted_odds` | float64 | AI-predicted probability (0-1) |
| `confidence_interval` | float64 | Confidence interval |
| `last_updated` | time.Time | Last update |
**JSON Example:**
```json
{
"market_id": "0x1234...",
"question": "Will Fed cut rates in April?",
"current_price": 0.73,
"volume_24h": 4567890.12,
"liquidity": 1234567.89,
"sentiment_score": 0.42,
"volatility_index": 0.15,
"momentum": 0.68,
"trend_direction": "bullish",
"signal_strength": 0.82,
"predicted_odds": 0.71,
"confidence_interval": 0.05,
"last_updated": "2025-03-28T15:00:00Z"
}
```
---
### `ArbitrageOpportunity`
Arbitrage opportunities between Polymarket and Kalshi.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `market_question` | string | Market question (normalized) |
| `polymarket_yes` | float64 | YES price on Polymarket (0-1) |
| `kalshi_yes` | float64 | YES price on Kalshi (0-1) |
| `difference` | float64 | Absolute price difference |
**JSON Example:**
```json
{
"market_question": "will-trump-win-2024",
"polymarket_yes": 0.523,
"kalshi_yes": 0.491,
"difference": 0.032
}
```
---
### `PaginatedResponse[T]`
Generic structure for paginated responses.
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `results` | []T | Array of results of generic type T |
| `total` | int64 (optional) | Total available records |
**JSON Example (for `[]PolymarketMarket`):**
```json
{
"results": [
{
"question": "Will Bitcoin reach $100,000?",
"slug": "bitcoin-100k",
"last_price": 0.67
}
],
"total": 1523
}
```
---
## 📋 API Endpoints
### Heisenberg Prediction Market Intelligence API
Unified, real-time access to prediction market data across multiple platforms through a single, standardized interface.
**Base URL:** `https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized`
All requests are POST with JSON body:
```json
{
"agent_id": 574,
"params": { "key": "value", ... },
"pagination": { "limit": 10, "offset": 0 },
"formatter_config": { "format_type": "raw" }
}
```
**Authentication:**
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
### Agent IDs Reference
| Endpoint | Agent ID | Required Params | Description |
|----------|----------|-----------------|-------------|
| Polymarket Markets | `574` | — | Search/filter markets |
| Polymarket Trades | `556` | — | Historical trade feed |
| Polymarket Candlesticks | `568` | `token_id` | OHLCV data |
| Polymarket Orderbook | `572` | `token_id` | Order book snapshots |
| Polymarket PnL | `569` | `wallet` | Realized PnL time series |
| Polymarket Leaderboard | `579` | — | Official rankings |
| H-Score Leaderboard | `584` | — | Proprietary skilled trader ranking |
| Wallet 360 | `581` | `proxy_wallet`, `window_days` | Full wallet profile |
| Market Insights | `575` | — | Market quality metrics |
| Kalshi Markets | `565` | — | Kalshi market catalog |
| Kalshi Trades | `573` | — | Kalshi trade history |
| Social Pulse | `585` | `keywords`, `hours_back` | Social media signals |
### Endpoint Details
#### Agent 574 - Polymarket Markets
```json
{
"agent_id": 574,
"params": {
"closed": "False",
"min_volume": "100",
"market_slug": "bitcoin-up-or-down-january-17-3pm-et",
"event_slug": "bitcoin-up-or-down-january-17-3pm-et",
"condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
"end_date_min": "1768467703",
"end_date_max": "1769213303"
},
"pagination": { "limit": 100, "offset": 0 }
}
```
**Request Parameters:**
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `closed` | String (Boolean) | Market status - "False" for open, "True" for closed | "False" |
| `min_volume` | String | Minimum trading volume filter | "1000" |
| `market_slug` | String | Market identifier or keyword search | "bitcoin" |
| `event_slug` | String | Event identifier | "bitcoin-up-or-down" |
| `condition_id` | String | Ethereum condition ID | "0xeaff81..." |
| `end_date_min` | String (Unix timestamp) | Filter markets ending after this timestamp | "1701388800" |
| `end_date_max` | String (Unix timestamp) | Filter markets ending before this timestamp | "1704067199" |
**Response Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `condition_id` | String | Ethereum condition ID for the market |
| `question` | String | Market question/title |
| `slug` | String | URL-friendly market identifier |
| `event_slug` | String | URL-friendly event identifier |
| `closed` | Boolean | Market status (false = open, true = closed) |
| `volume_total` | Float | Total trading volume |
| `start_date` | String (ISO 8601) | Market start timestamp |
| `end_date` | String (ISO 8601) | Market end/resolution timestamp |
| `close_date` | String (ISO 8601) | Market close timestamp |
| `side_a_token_id` | String | Token ID of the first side |
| `side_b_token_id` | String | Token ID of the second side |
| `side_a_outcome` | String | Outcome of the first side |
| `side_b_outcome` | String | Outcome of the second side |
| `winning_outcome` | String | Winning outcome (if resolved) |
#### Agent 556 - Polymarket Trades
```json
{
"agent_id": 556,
"params": {
"wallet_proxy": "0xabc123...",
"condition_id": "0xeaff81...",
"market_slug": "will-trump-win-2024",
"side": "BUY",
"start_time": "1767973812",
"end_time": "1767973860"
}
}
```
#### Agent 568 - Polymarket Candlesticks
```json
{
"agent_id": 568,
"params": {
"token_id": "58639447033085668146701215689433308999613524738987821507545529427932862502961",
"interval": "1h",
"start_time": "1769219100",
"end_time": "1769508420"
}
}
```
#### Agent 569 - Polymarket PnL
```json
{
"agent_id": 569,
"params": {
"wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
"granularity": "1d",
"start_time": "2026-02-10",
"end_time": "2026-02-28"
}
}
```
**Note:** Dates use `YYYY-MM-DD` format (NOT Unix timestamps).
#### Agent 579 - Polymarket Leaderboard
```json
{
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "7d"
}
}
```
#### Agent 584 - H-Score Leaderboard
```json
{
"agent_id": 584,
"params": {
"min_win_rate_15d": "0.45",
"max_win_rate_15d": "0.95",
"min_roi_15d": "0",
"min_total_trades_15d": "30",
"max_total_trades_15d": "5000",
"min_pnl_15d": "5000",
"sort_by": "roi"
}
}
```
#### Agent 581 - Wallet 360
```json
{
"agent_id": 581,
"params": {
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"window_days": "7"
}
}
```
**Request Parameters:**
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `proxy_wallet` | string | Wallet address (required) | "0x204f72f35326db932158cba6adff0b9a1da95e14" |
| `window_days` | string | Calculation window: "1", "3", "7", "15" | "7" |
**Note:** `window_days` must be one of: `"1"`, `"3"`, `"7"`, `"15"`.
**Response Fields:**
See `Wallet360` model above for complete response structure with 70+ metrics including:
- Trading performance (win rate, PnL, ROI)
- Risk metrics (Sharpe, Sortino, Calmar, Max Drawdown)
- Market analysis (diversification, concentration)
- Timing analysis (suspicious timing detection)
- Position sizing analysis
- Sybil risk detection
- Equity curve analysis
#### Agent 575 - Market Insights
```json
{
"agent_id": 575,
"params": {
"min_volume_24h": "10000",
"min_liquidity_percentile": "75",
"volume_trend": "UP",
"min_top1_wallet_pct": "0",
"max_unique_traders_7d": "0"
}
}
```
#### Agent 585 - Social Pulse
```json
{
"agent_id": 585,
"params": {
"keywords": "{Trump,election,MAGA}",
"hours_back": "12"
}
}
```
**Note:** `keywords` must be comma-separated and **wrapped in curly braces**. `hours_back` is required.
### Pagination
All endpoints support pagination:
```json
"pagination": {
"limit": 100,
"offset": 0
}
```
- `limit`: Max 200 per page
- `offset`: Increment by limit for next page
### Timestamp Formats
- **Most endpoints:** Unix timestamps in **seconds** (e.g., `"1767973812"`)
- **Exception - PnL (569):** Uses `YYYY-MM-DD` date strings (e.g., `"2026-02-10"`)
## 🔧 Ready Workflows
### 1. Copy-Trading Pipeline
```bash
# Step 1: Find skilled traders (Heisenberg leaderboard filters out bots and lucky streaks)
./betbrain hscore --min-win-rate 0.45 --max-win-rate 0.95 --min-roi 0.2 --min-trades 50 --min-pnl 5000 --limit 50
# Step 2: Analyze top performers with Wallet 360
./betbrain wallet --address 0xtop1 --window 7
# Step 3: Check their recent trades
./betbrain trades --proxy-wallet 0xtop1 --limit 50
```
### 2. Arbitrage Scanner
```bash
# Run periodically to find price discrepancies between Polymarket and Kalshi
./betbrain arbitrage --threshold 0.03 --json > arbitrage_$(date +%s).json
```
### 3. Market Intelligence Dashboard
```bash
# Combine social signals with market data
./betbrain social --keywords "{Fed,interest rates}" --hours-back 12
# Find markets with rising volume and high liquidity (Market360)
./betbrain insights --slug bitcoin-up-or-down --min-volume 10000
# List active markets with minimum volume
./betbrain markets --min-volume 5000 --closed False --limit 50
```
### 4. Wallet Due Diligence
```bash
# Full analysis before copying a trader
./betbrain wallet --address 0x123... --window 7
./betbrain trades --proxy-wallet 0x123... --limit 100
./betbrain leaderboard --period 30d --limit 50
```
### 5. Breaking News Trading
```bash
# Monitor social signals for surging topics
./betbrain social --keywords "{election,Trump,MAGA}" --hours-back 6
# Check if markets have repriced yet
./betbrain markets --slug will-trump-win-2024
# Analyze candlestick data for price movement
./betbrain candles --slug will-trump-win-2024 --interval 1h --start-time 1767973812 --end-time 1767980000
```
## 🎯 Features
✅ **Zero external dependencies** - only Go standard library
✅ **Modular** - clear separation between CLI and MCP server
✅ **Type-safe** - all models with strong types
✅ **Automatic pagination** - API handles offsets internally
✅ **Validation** - Ethereum addresses, parameters, etc.
✅ **Flexible formatter** - table or JSON output
✅ **MCP stdio** - ready for picoclaw integration
✅ **Robust error handling** - context in all errors
## 📊 Output Examples
### Markets (table format)
```
SLUG QUESTION YES% LIQUIDITY VOLUME CATEGORY
--- ------- ---- --------- ------ --------
trump-election-2024 Will Trump win 2024? 52.3 $145230.50 $892341 politics
```
### Wallet 360
```
Wallet: 0x1234...abcd
Days Active: 45
Total Volume: $523,412.34
Total PnL: $45,231.12
ROI: 8.6%
H-Score: 67.4
Win Rate: 62.3%
Sharpe Ratio: 1.87
...
```
### Arbitrage
```
MARKET POLYMARKET% KALSHI% DIFF
------ ------------ ------- ----
Will Trump win 2024? 52.3% 49.1% 3.2%
```
## 🛠️ Development
### Add New CLI Command
1. Add method in `internal/api/client.go`
2. Add handler in `cmd/cli/main.go`
3. Add MCP tool in `cmd/mcp/main.go`
4. Add formatter in `internal/formatter/formatter.go` if needed
### Testing
```bash
# Basic connection test
./betbrain markets --limit 1
# Test with invalid wallet (should fail)
./betbrain wallet --address 0xinvalid
```
## 🔒 Limitations
- API has rate limits (see official docs)
- Historical data limited to ~90 days
- Kalshi requires separate account (different API key)
- Ethereum addresses only (no other L2s)
## 📚 References
- API Docs: https://prediction.heisenberg.so/prediction_market_api_context.md
- Polymarket: https://polymarket.com
- Kalshi: https://kalshi.com
- MCP Protocol: https://modelcontextprotocol.io
## 📄 License
MIT
Connection Info
You Might Also Like
Vibe-Trading
Vibe-Trading: Your Personal Trading Agent
ai-berkshire
Berkshire in the AI Era: A Value Investment Research Framework Based on...
hexstrike-ai
HexStrike AI is an AI-powered MCP cybersecurity automation platform with 150+ tools.
valuecell
Valuecell is a Python project for efficient data management.
tradingview-mcp
AI-assisted TradingView chart analysis — connect Claude Code to your...
tradingview-mcp
TradingView MCP Server offers real-time market analysis for crypto and stocks.