probable-trader 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# Probable Markets Trading Skill
+
+An OpenClaw Skill that wraps the [Probable Markets](https://probable.markets) prediction market on BNB Chain (BSC). Enables agents to onboard wallets, discover markets, view orderbooks, place/cancel orders, track positions, and generate audit reports.
+
+Built on top of `opinion_clob_sdk` — the official Probable Markets / Opinion Labs Python SDK.
+
+## Features
+
+- **One-command onboarding** — auto-generates API key via L1 EIP-712 auth
+- **Full trading lifecycle** — place/cancel limit & market orders, split/merge/redeem
+- **Safety by default** — dry-run mode, `--confirm` required for all transactions, secret masking
+- **Audit logging** — every action logged to local SQLite
+- **Real-time streaming** — WebSocket orderbook & execution report subscriptions
+- **Agent-native** — all output as structured JSON (ActionResult envelope)
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+pip install opinion_clob_sdk websockets httpx
+
+# 2. Set your private key
+export PROB_PRIVATE_KEY="0xYOUR_PRIVATE_KEY"
+export PROB_RPC_URL="https://bsc-dataseed.binance.org"
+
+# 3. Register on probable.markets (connect wallet), then set proxy wallet
+export PROB_MULTI_SIG_ADDR="0xYOUR_PROXY_WALLET"
+
+# 4. Auto-generate API key
+python3 scripts/prob.py onboard --confirm --json
+
+# 5. Enable trading approvals (on-chain)
+python3 scripts/prob.py setup --confirm --json
+
+# 6. Start trading
+python3 scripts/prob.py market list --status activated --json
+python3 scripts/prob.py book <token_id> --json
+python3 scripts/prob.py order place --market-id <M> --token-id <T> --side BUY --price 0.55 --amount 100 --confirm --json
+```
+
+## CLI Commands
+
+```
+prob.py config {show,init}              # Configuration management
+prob.py doctor                          # Health check
+prob.py onboard [--confirm]             # Generate API key (L1 auth)
+prob.py setup [--confirm]               # Enable trading (on-chain approvals)
+
+prob.py market {list,get,search}        # Market discovery
+prob.py book <token_id>                 # Orderbook snapshot
+prob.py price <token_id>                # Latest price
+prob.py history <token_id>              # Price history
+prob.py fee-rates <token_id>            # Fee rates
+
+prob.py order {place,get,list,cancel,cancel-all}   # Order management
+prob.py positions [--market-id M]       # My positions
+prob.py trades [--market-id M]          # My trades
+prob.py balance                         # My balances
+
+prob.py split --market-id M --amount A [--confirm]   # Split collateral
+prob.py merge --market-id M --amount A [--confirm]   # Merge tokens
+prob.py redeem --market-id M [--confirm]             # Redeem resolved
+
+prob.py ws book <token_id> [--duration N]   # Stream orderbook
+prob.py ws user [--duration N]              # Stream execution reports
+prob.py report daily [--format json|markdown|both]   # Trading report
+```
+
+Global flags: `--json` (JSON output), `--confirm` (execute), `--dry-run` (preview)
+
+## Project Structure
+
+```
+marketskill/
+├── SKILL.md                 # OpenClaw skill definition
+├── scripts/
+│   ├── prob.py              # CLI entry point
+│   └── lib/
+│       ├── config.py        # Env var + config file loading
+│       ├── client_wrapper.py # Wraps opinion_clob_sdk.Client
+│       ├── onboard.py       # L1 auth + API key generation
+│       ├── safety.py        # Dry-run, confirmation, secret masking
+│       ├── db.py            # SQLite audit log + cache
+│       ├── ws_client.py     # WebSocket client
+│       └── report.py        # Daily report generator
+├── schemas/                 # JSON schemas (config, order intent, output)
+├── references/              # API, WebSocket, and onboarding docs
+└── examples/                # Example interactions
+```
+
+## Safety Model
+
+| Feature | Behavior |
+|---------|----------|
+| Default mode | Dry-run — shows what would happen without executing |
+| Transactions | Require `--confirm` flag (orders, cancel, split, merge, redeem, setup) |
+| Secrets | Private keys and API secrets masked in all output |
+| Audit | Every action logged to `.probable/probable.db` (SQLite) |
+| Output | Standardized JSON envelope with `success`, `error`, `request_id`, `timestamp` |
+
+## Key Contracts (BSC Mainnet)
+
+| Contract | Address |
+|----------|---------|
+| ConditionalTokens | `0xAD1a38cEc043e70E83a3eC30443dB285ED10D774` |
+| MultiSend | `0x998739BFdAAdde7C933B942a68053933098f9EDa` |
+| FeeManager | `0xC9063Dc52dEEfb518E5b6634A6b8D624bc5d7c36` |
+
+## Requirements
+
+- Python 3.10+
+- `opinion_clob_sdk` (v0.4.3+)
+- `websockets`, `httpx`
+- BNB Chain wallet with BNB (gas) and USDT (trading)
+
+## License
+
+MIT

package/bin/probable-trader.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const { ensureEnvironment, checkPython, installDeps } = require("../lib/setup");
+
+const PROB_PY = path.resolve(__dirname, "..", "scripts", "prob.py");
+
+// Handle "setup-python" — force (re)install deps
+if (process.argv[2] === "setup-python") {
+  try {
+    const pythonBin = checkPython();
+    console.log("Python found: " + pythonBin);
+    // Remove marker to force reinstall
+    const fs = require("fs");
+    const marker = path.resolve(__dirname, "..", ".probable", ".deps-installed");
+    if (fs.existsSync(marker)) {
+      fs.unlinkSync(marker);
+    }
+    installDeps(pythonBin);
+    console.log("Setup complete.");
+  } catch (err) {
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// For --help / -h / no args, only need python check (skip pip install)
+const userArgs = process.argv.slice(2);
+const helpOnly =
+  userArgs.length === 0 ||
+  userArgs.includes("--help") ||
+  userArgs.includes("-h");
+
+let pythonBin;
+try {
+  if (helpOnly) {
+    pythonBin = checkPython();
+  } else {
+    pythonBin = ensureEnvironment();
+  }
+} catch (err) {
+  console.error("Error:", err.message);
+  process.exit(1);
+}
+
+// Forward all args after "probable-trader" to prob.py
+const args = [PROB_PY, ...process.argv.slice(2)];
+
+const child = spawn(pythonBin, args, {
+  stdio: "inherit",
+  cwd: path.resolve(__dirname, ".."),
+});
+
+child.on("error", (err) => {
+  console.error("Failed to start Python:", err.message);
+  process.exit(1);
+});
+
+child.on("close", (code) => {
+  process.exit(code ?? 1);
+});

package/lib/setup.js

@@ -0,0 +1,125 @@
+"use strict";
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const MARKER_DIR = path.join(PKG_ROOT, ".probable");
+const MARKER_FILE = path.join(MARKER_DIR, ".deps-installed");
+
+/**
+ * Find a working python3 binary and verify version >= 3.10.
+ * Returns the binary name (e.g. "python3") or throws.
+ */
+function checkPython() {
+  const candidates = ["python3", "python"];
+  for (const bin of candidates) {
+    try {
+      const raw = execFileSync(bin, ["--version"], {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      const match = raw.match(/Python\s+(\d+)\.(\d+)/);
+      if (match) {
+        const major = parseInt(match[1], 10);
+        const minor = parseInt(match[2], 10);
+        if (major === 3 && minor >= 10) {
+          return bin;
+        }
+      }
+    } catch {
+      // binary not found, try next
+    }
+  }
+  throw new Error(
+    "Python 3.10+ is required but not found.\n" +
+      "Install it from https://www.python.org/downloads/ and ensure it is on your PATH."
+  );
+}
+
+/**
+ * Try to run a pip install command. Returns true on success.
+ */
+function tryPipInstall(args) {
+  try {
+    execFileSync(args[0], args.slice(1), {
+      stdio: "inherit",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if `uv` is available.
+ */
+function hasUv() {
+  try {
+    execFileSync("uv", ["--version"], { stdio: ["pipe", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install Python dependencies from requirements.txt (only once).
+ * Tries multiple strategies: uv pip, pip, pip --user, pip --break-system-packages.
+ */
+function installDeps(pythonBin) {
+  if (fs.existsSync(MARKER_FILE)) {
+    return;
+  }
+
+  const reqFile = path.join(PKG_ROOT, "requirements.txt");
+  if (!fs.existsSync(reqFile)) {
+    throw new Error("requirements.txt not found at " + reqFile);
+  }
+
+  console.error("[probable-trader] Installing Python dependencies (first run)...");
+
+  const strategies = [
+    // 1. uv pip install (fast, respects PEP 668)
+    ...(hasUv() ? [["uv", "pip", "install", "-r", reqFile]] : []),
+    // 2. Standard pip
+    [pythonBin, "-m", "pip", "install", "-r", reqFile],
+    // 3. pip --user (avoids system site-packages)
+    [pythonBin, "-m", "pip", "install", "--user", "-r", reqFile],
+    // 4. pip --break-system-packages (PEP 668 override, last resort)
+    [pythonBin, "-m", "pip", "install", "--break-system-packages", "-r", reqFile],
+  ];
+
+  for (const args of strategies) {
+    console.error("[probable-trader] Trying: " + args.join(" "));
+    if (tryPipInstall(args)) {
+      // Write marker
+      if (!fs.existsSync(MARKER_DIR)) {
+        fs.mkdirSync(MARKER_DIR, { recursive: true });
+      }
+      fs.writeFileSync(MARKER_FILE, new Date().toISOString() + "\n");
+      console.error("[probable-trader] Python dependencies installed successfully.");
+      return;
+    }
+  }
+
+  throw new Error(
+    "Failed to install Python dependencies.\n" +
+      "Try running manually:\n" +
+      "  " + pythonBin + " -m pip install -r " + reqFile + "\n" +
+      "Or use a virtual environment:\n" +
+      "  " + pythonBin + " -m venv .venv && source .venv/bin/activate && pip install -r " + reqFile
+  );
+}
+
+/**
+ * Ensure Python environment is ready. Returns the python binary name.
+ */
+function ensureEnvironment() {
+  const pythonBin = checkPython();
+  installDeps(pythonBin);
+  return pythonBin;
+}
+
+module.exports = { checkPython, installDeps, ensureEnvironment };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "probable-trader",
+  "version": "1.0.0",
+  "description": "CLI for trading prediction markets on Probable Markets (BSC)",
+  "bin": {
+    "probable-trader": "bin/probable-trader.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/**/*.py",
+    "schemas/",
+    "requirements.txt"
+  ],
+  "keywords": [
+    "prediction-market",
+    "bsc",
+    "trading",
+    "cli",
+    "probable-markets"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duolaAmengweb3/probable-trader-skill"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/requirements.txt

@@ -0,0 +1,6 @@
+opinion_clob_sdk>=0.4.3
+py_clob_client>=0.1.0
+websockets>=12.0
+httpx>=0.27
+eth_account>=0.11
+hexbytes>=0.3

package/schemas/action-output.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Action Output",
+  "description": "Standardized output envelope for all Probable Markets CLI actions",
+  "type": "object",
+  "properties": {
+    "success": {
+      "type": "boolean",
+      "description": "Whether the action completed successfully"
+    },
+    "action": {
+      "type": "string",
+      "description": "Action name (e.g. 'place_order', 'get_markets', 'doctor')"
+    },
+    "data": {
+      "description": "Action-specific response data (null on error)"
+    },
+    "error": {
+      "type": ["string", "null"],
+      "description": "Error message if success=false"
+    },
+    "dry_run": {
+      "type": "boolean",
+      "description": "True if action was simulated (not executed)",
+      "default": false
+    },
+    "request_id": {
+      "type": "string",
+      "description": "Unique request ID for audit correlation",
+      "pattern": "^[0-9a-f]{12}$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "UTC ISO-8601 timestamp"
+    }
+  },
+  "required": ["success", "action", "request_id", "timestamp"],
+  "examples": [
+    {
+      "success": true,
+      "action": "get_markets",
+      "data": [{"id": 1, "title": "Will BTC hit 100k?"}],
+      "error": null,
+      "dry_run": false,
+      "request_id": "a1b2c3d4e5f6",
+      "timestamp": "2026-03-04T12:00:00+00:00"
+    }
+  ]
+}

package/schemas/config.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Probable Markets Skill Configuration",
+  "description": "Configuration schema for the probable-trader skill",
+  "type": "object",
+  "properties": {
+    "host": {
+      "type": "string",
+      "description": "Probable Markets API host URL",
+      "default": "https://api.probable.markets"
+    },
+    "chain_id": {
+      "type": "integer",
+      "description": "BSC chain ID",
+      "default": 56,
+      "enum": [56]
+    },
+    "rpc_url": {
+      "type": "string",
+      "description": "BSC RPC endpoint URL (e.g. https://bsc-dataseed.binance.org)"
+    },
+    "api_key": {
+      "type": "string",
+      "description": "Probable Markets API key (from onboarding)"
+    },
+    "private_key": {
+      "type": "string",
+      "description": "EOA private key for signing (hex, with or without 0x prefix)",
+      "pattern": "^(0x)?[0-9a-fA-F]{64}$"
+    },
+    "multi_sig_addr": {
+      "type": "string",
+      "description": "Gnosis Safe proxy wallet address",
+      "pattern": "^0x[0-9a-fA-F]{40}$"
+    }
+  },
+  "required": [],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "host": "https://api.probable.markets",
+      "chain_id": 56,
+      "rpc_url": "https://bsc-dataseed.binance.org",
+      "api_key": "your-api-key",
+      "private_key": "0x...",
+      "multi_sig_addr": "0x..."
+    }
+  ]
+}

package/schemas/order-intent.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Order Intent",
+  "description": "Input schema for placing an order on Probable Markets",
+  "type": "object",
+  "properties": {
+    "market_id": {
+      "type": "integer",
+      "description": "Market/Topic ID"
+    },
+    "token_id": {
+      "type": "string",
+      "description": "CTF ERC1155 token ID for the outcome to trade"
+    },
+    "side": {
+      "type": "string",
+      "enum": ["BUY", "SELL"],
+      "description": "Order side"
+    },
+    "price": {
+      "type": "string",
+      "description": "Price per token (0.001 to 0.999)",
+      "pattern": "^0\\.[0-9]{1,3}$"
+    },
+    "amount": {
+      "type": "string",
+      "description": "Amount in quote token (for BUY) or base token (for SELL), in token units"
+    },
+    "order_type": {
+      "type": "string",
+      "enum": ["limit", "market"],
+      "default": "limit",
+      "description": "Order type: limit (GTC) or market (IOC)"
+    }
+  },
+  "required": ["market_id", "token_id", "side", "price", "amount"],
+  "examples": [
+    {
+      "market_id": 42,
+      "token_id": "12345678901234567890",
+      "side": "BUY",
+      "price": "0.55",
+      "amount": "100",
+      "order_type": "limit"
+    }
+  ]
+}

package/scripts/lib/__init__.py

@@ -0,0 +1 @@
+# Probable Markets Skill library