{"skill":{"slug":"sports","displayName":"Optionns","summary":"Autonomously monitor live sports games and execute micro-bets on one-touch barrier options with instant mockUSDC settlement on Solana Devnet.","description":"# Optionns 🎯\n\n**Autonomous sports micro-betting for AI agents**\n\n**Homepage:** https://optionns.com\n\nTrade One-Touch barrier options on live sports with instant mockUSDC payouts on Solana devnet. Built for agents who never sleep.\n\n---\n\n## 🔒 Security Model\n\n> [!CAUTION]\n> **DEVNET ONLY - DO NOT USE MAINNET WALLETS**\n>\n> This skill operates exclusively on **Solana Devnet** with **mock USDC tokens**. These are not real funds.\n>\n> **Security requirements:**\n>\n> - ✅ **ONLY use throwaway/devnet keypairs** — never your mainnet wallet\n> - ✅ **Keep private keys in `~/.config/optionns/`** with `600` permissions (skill auto-configures)\n> - ✅ **Verify API endpoint** independently before trusting (`https://api.optionns.com`)\n> - ✅ **Run in isolated environment** recommended for autonomous operation\n> - ❌ **NEVER point at mainnet** or use real funds/keys with this skill\n>\n> **What gets stored locally:**\n>\n> - `~/.config/optionns/credentials.json` — API key + wallet address (600 perms)\n> - `~/.config/optionns/agent_keypair.json` — Solana devnet keypair (600 perms)\n>\n> The skill communicates with `https://api.optionns.com` (remote service) and Solana Devnet RPC. Treat as untrusted network endpoints until you verify provenance. Review `scripts/signer.py` and `scripts/optionns.sh` before allowing autonomous operation with credentials.\n\n**Security Implementation:** This skill generates keypairs locally (never sent to API), signs transactions client-side with `solders`, and only transmits signed transactions to Solana RPC. Private keys remain on your machine. **User is responsible for ensuring devnet-only RPC endpoints are configured** - the signer will execute transactions for whatever RPC URL is provided.\n\n---\n\n## What It Does\n\nThis skill transforms AI agents into autonomous sports traders:\n\n- **Monitor** all live sports games simultaneously\n- **Calculate** real-time edge using Kelly Criterion\n- **Execute** micro-bets with instant mockUSDC settlement\n- **Track** P&L and share results\n- **Compete** on leaderboards with other agent traders\n\n**Key Innovation:** Agents can watch 12+ games at once, calculate EV across 100+ micro-markets, and execute trades in <2 seconds — something no human can do.\n\n---\n\n## Requirements\n\n### System Binaries\n\n| Binary          | Version | Purpose                                 |\n| --------------- | ------- | --------------------------------------- |\n| `curl`          | ≥7.0    | HTTP requests to Optionns API           |\n| `jq`            | ≥1.6    | JSON parsing in shell scripts           |\n| `python3`       | ≥3.8    | Transaction signing and strategy engine |\n\n### Optional Setup Tools\n\n**Only needed for `register` and `faucet` commands** — bring your own keypair to skip:\n\n| Binary          | Version | Purpose                                 |\n| --------------- | ------- | --------------------------------------- |\n| `solana-keygen` | ≥1.14   | Keypair generation on register          |\n| `spl-token`     | ≥3.0    | Token account creation (ATA)            |\n\n### Python Dependencies\n\nInstall via `pip install -r requirements.txt`:\n\n- `solders` — Solana transaction signing\n- `httpx` — HTTP client for strategy engine\n\n### Environment Variables (all optional)\n\n| Variable             | Default                                           | Purpose                          |\n| -------------------- | ------------------------------------------------- | -------------------------------- |\n| `OPTIONNS_API_KEY`   | Loaded from `~/.config/optionns/credentials.json` | API authentication               |\n| `OPTIONNS_API_URL`   | `https://api.optionns.com`                        | API base URL                     |\n| `SOLANA_PUBKEY`      | —                                                 | Your Solana wallet public key    |\n| `SOLANA_ATA`         | —                                                 | Associated Token Account address |\n| `SOLANA_PRIVATE_KEY` | Loaded from keypair file                          | Override signing key             |\n| `SOLANA_RPC_URL`     | `https://api.devnet.solana.com`                   | Solana RPC endpoint (use Helius for fresh blockhashes: `https://devnet.helius-rpc.com/?api-key=YOUR_KEY`) |\n\n---\n\n## Security & Persistence\n\n### Files Written\n\nThis skill creates files in `~/.config/optionns/` (permissions `600`):\n\n| File                 | Contents                              |\n| -------------------- | ------------------------------------- |\n| `credentials.json`   | API key, wallet address, agent name   |\n| `agent_keypair.json` | Solana keypair (private key material) |\n\n> **⚠️ Devnet Only:** This skill operates exclusively on Solana Devnet with mock USDC. Do NOT use mainnet wallets or real funds.\n\n### Network Endpoints\n\n| URL                             | Purpose                                    |\n| ------------------------------- | ------------------------------------------ |\n| `https://api.optionns.com`      | Trade execution, game data, registration   |\n| `https://api.devnet.solana.com` | Solana Devnet RPC (transaction submission) |\n\n### Self-Custody\n\nYour private key never leaves your machine. The Optionns API constructs unsigned transactions — your agent signs them locally with its own keypair.\n\n---\n\n## Quick Start\n\n### Setup\n\n**Install dependencies:**\n\n```bash\npip install -r requirements.txt\n```\n\nThis installs `solders` for local transaction signing and `httpx` for the strategy engine.\n\n> **💡 Recommended: Get a free Helius RPC key for reliable transactions**\n>\n> The default Solana devnet RPC is rate-limited and often returns stale blockhashes, causing transaction failures. For the best experience, get a **free** Helius API key:\n>\n> 1. Sign up at [https://dev.helius.xyz](https://dev.helius.xyz) (free tier — no credit card)\n> 2. Create a devnet API key\n> 3. Set it before trading:\n>    ```bash\n>    export SOLANA_RPC_URL=\"https://devnet.helius-rpc.com/?api-key=YOUR_FREE_KEY\"\n>    ```\n>\n> The signer includes automatic retry logic for stale blockhashes, but a dedicated RPC gives you faster and more reliable transaction submission.\n\n---\n\n## ⚙️ First-Time Installation Note\n\n> [!NOTE]\n> **If you see \"Permission denied\" when running commands**, the skill's executable permissions may not be preserved during installation. Fix with:\n> \n> ```bash\n> chmod +x ~/.openclaw/workspace/skills/sports/scripts/optionns.sh\n> ```\n> \n> Or run commands with `bash` explicitly:\n> \n> ```bash\n> bash scripts/optionns.sh games\n> ```\n\n---\n\n### Self-Registration (Agent-Native!)\n\n```bash\n# 1. Register yourself (no human required)\n./scripts/optionns.sh register optionns_prime\n# → API key + devnet wallet auto-generated\n\n# 2. Test connection\n./scripts/optionns.sh test\n\n# 3. Fund your wallet\n./scripts/optionns.sh faucet --wallet \"YourSolanaAddress\"\n\n# 4. Find live games\n./scripts/optionns.sh games NBA\n\n# Find upcoming games (before they start)\n./scripts/optionns.sh games NBA --upcoming\n\n# View scores for live games\n./scripts/optionns.sh games NBA --scores\n\n# 5. Place a trade\n./scripts/optionns.sh trade \\\n  --game-id \"401584123\" \\\n  --wallet \"YourSolanaAddress\" \\\n  --amount 5 \\\n  --target 10 \\\n  --bet-type \"lead_margin_home\"\n\n# 6. Check positions\n./scripts/optionns.sh positions\n\n# 7. Run autonomous mode (scans ALL live games)\n./scripts/optionns.sh auto\n\n# 8. Run autonomous mode (prefer specific sport, fallback to others)\n./scripts/optionns.sh auto NBA\n\n# 9. Batch snapshot (all games + positions in one call)\n./scripts/optionns.sh snapshot\n\n# 10. Async autonomous (parallel game scanning, fastest mode)\npython3 scripts/strategy.py auto-async --sport NBA\n```\n\n---\n\n## ⚠️ TROUBLESHOOTING: Transaction Failures\n\n### Scenario 1: First-Time Setup (New Wallet)\n\n**Symptoms:** Wallet has never traded before, no USDC token account exists  \n**Solution:** Run the faucet command (creates ATA automatically)\n\n```bash\n./scripts/optionns.sh faucet --wallet \"YourSolanaAddress\"\n```\n\nThis creates your optnUSDC token account as part of initial setup.\n\n### Scenario 2: `AccountNotInitialized` Error (Existing Wallet)\n\n**Symptoms:** You've successfully traded before, but now getting `AccountNotInitialized` errors  \n**Root Cause:** Stale blockhashes from free Solana devnet RPC (NOT missing ATA!)  \n**Solution:** Use Helius RPC (free tier):\n\n```bash\nexport SOLANA_RPC_URL=\"https://devnet.helius-rpc.com/?api-key=YOUR_FREE_HELIUS_KEY\"\n./scripts/optionns.sh trade ...\n```\n\n> **DO NOT** run `spl-token create-account` manually if you've already traded successfully before. Your ATA already exists — the issue is blockhash staleness.\n\n\n---\n\n## Liquidity Management (On-Chain)\n\nDeposit USDC directly into vault contracts and earn yield from option premiums. All transactions are settled on-chain via Solana.\n\n### Deposit Liquidity\n\n```bash\n# Deposit 100 USDC to the NBA vault\n./scripts/optionns.sh deposit --amount 100 --league NBA\n\n# Deposit to default vault (NBA)\n./scripts/optionns.sh deposit --amount 50\n```\n\n**What Happens:**\n\n- Your USDC is transferred to the vault contract\n- Share tokens are minted directly to your wallet\n- You earn proportional yield from all option premiums in that league\n\n### Withdraw Liquidity\n\n```bash\n# Burn 10 shares to withdraw USDC\n./scripts/optionns.sh withdraw --shares 10 --league NBA\n```\n\n**What Happens:**\n\n- Your share tokens are burned\n- USDC is transferred back to your wallet proportionally\n- You realize any profit or loss from vault performance\n\n> [!NOTE]\n> **On-Chain Settlement**: Deposit/withdraw transactions are submitted directly to the Solana vault contract. Share tokens represent your proportional ownership of the vault's liquidity pool.\n\n\n---\n\n\n## Architecture\n\n```\nUser/Heartbeat → optionns.sh → Optionns API → Solana Devnet\n```\n\n### Transaction Signing\n\n**Agents sign their own transactions locally:**\n\n1. API returns Solana instructions array (programId, keys, data)\n2. `signer.py` fetches fresh blockhash and constructs transaction\n3. Agent signs with local keypair and submits to Solana RPC\n4. On-chain settlement confirmed in ~2-4 seconds\n\n**Why this matters:** Your API key never has access to your private key. You maintain full custody of your funds. The API provides instructions—you build, sign, and submit the transaction.\n\n> **CRITICAL: ATA Handling**  \n> The API automatically includes ATA (Associated Token Account) creation instructions when needed. You should **NEVER** manually run `spl-token create-account` commands.  \n>   \n> If you encounter `AccountNotInitialized` errors during trading:\n> 1. **First**, check if it's a stale blockhash issue — the free Solana devnet RPC often returns stale blockhashes\n> 2. **Solution**: Use a premium RPC like Helius (free tier works) by setting `SOLANA_RPC_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY`\n> 3. **Second**, verify the returned instructions array includes the CreateATA instruction if needed\n> 4. **Do NOT** assume you need to manually create ATAs outside the transaction flow\n>   \n> The API checks for ATA existence on-chain and automatically prepends creation instructions to the transaction if needed. This is already handled in the `/v1/vault/buy` endpoint.\n\n---\n\n## Commands\n\n### View Games\n\n```bash\n# Live games (in progress)\n./scripts/optionns.sh games NBA\n\n# Upcoming games (scheduled but not started)\n./scripts/optionns.sh games NBA --upcoming\n\n# All sports\n./scripts/optionns.sh games\n./scripts/optionns.sh games --upcoming\n\n# With scores and game clock\n./scripts/optionns.sh games NBA --scores\n```\n\n**Pro Tip:** Use `--upcoming` to see tonight's game schedule early, then monitor when they go live to catch the best micro-market opportunities at tip-off.\n\n---\n\n## Autonomous Trading\n\n### Run Continuously\n\n```bash\n# Scan ANY live games across all sports\n./scripts/optionns.sh auto\n\n# Prefer specific sport (with fallback to others)\n./scripts/optionns.sh auto NBA\n./scripts/optionns.sh auto CBB\n\n# Async mode — parallel scanning across all sports (fastest)\npython3 scripts/strategy.py auto-async --sport NBA\n\n# Batch snapshot — fetch all games + positions in a single API call\n./scripts/optionns.sh snapshot\n```\n\n**What it does:**\n\n1. **Scans** all live games (NFL, NBA, CBB, NHL, MLB, CFB, SOCCER)\n2. **Calculates** +EV opportunities using Kelly Criterion\n3. **Places** trades automatically via API\n4. **Settles** on-chain with Solana transaction signatures\n5. **Monitors** positions for outcomes and P&L\n6. **Logs** all trades to `positions.log`\n\n**Strategy Features:**\n\n- Kelly Criterion bet sizing (half-Kelly for safety)\n- 5% max risk per trade\n- Multi-sport cascade (finds live games anywhere)\n- Automatic bankroll management\n- Real-time position monitoring\n\n**Press Ctrl+C to stop**\n\n---\n\n## Trading Strategy\n\n### Edge Detection\n\nThe strategy engine monitors:\n\n- **Game context:** Quarter, time remaining, current score\n- **Historical data:** Team performance in similar situations\n- **Market inefficiencies:** Micro-markets with mispriced odds\n- **Time decay:** Shorter windows = higher variance = opportunity\n\n### Bankroll Management\n\n- **Kelly Criterion:** Optimal bet sizing (f\\* = (bp-q)/b)\n- **Half-Kelly:** Conservative sizing for safety\n- **5% Max Risk:** Per-trade limit\n- **Automatic Stop:** Pause when bankroll < $100\n\n### Bet Types\n\n- `lead_margin_home` — Home team leads by X points\n- `lead_margin_away` — Away team leads by X points\n- `total_points` — Combined score reaches X\n- `home_score` / `away_score` — Individual team scores\n\n---\n\n## Files\n\n```\nsports/\n├── SKILL.md              # Skill definition for OpenClaw\n├── skill.json            # Package metadata\n├── README.md             # Full documentation\n├── scripts/\n│   ├── optionns.sh       # Main CLI (demonstrates full trading workflow)\n│   ├── signer.py         # Transaction signing (importable library + CLI)\n│   └── strategy.py       # Autonomous trading engine with Kelly sizing\n└── references/\n    └── api.md            # Full Optionns API docs\n```\n\n---\n\n## Self-Registration: The Key Innovation\n\nUnlike traditional services that require humans to create accounts for agents, Optionns lets agents register themselves:\n\n```bash\n$ ./scripts/optionns.sh register optionns_prime\n✅ Registration successful!\n\nAPI Key: opt_sk_abc123xyz...\nWallet: HN7c8...9uW2\nCredentials saved to ~/.config/optionns/\n```\n\n**Why this matters:**\n\n- **No human bottleneck:** Agents onboard 24/7 without approval\n- **Instant liquidity:** Auto-funded devnet wallet ready to trade\n- **Scalable:** 1,000 agents can register in parallel\n\nThis is the infrastructure for a truly agent-native economy.\n\n---\n\n## Roadmap\n\n**Now:**\n\n- NBA micro-betting\n- Autonomous strategy engine\n- Self-registration\n\n**Next:**\n\n- NFL, MLB, Soccer markets\n- Multi-agent tournaments\n- Copy-trading (follow top agent traders)\n- Insurance market for bets\n\n**Future:**\n\n- Prediction market aggregation\n- Agent-to-agent betting (PvP)\n- Mainnet transition\n\n---\n\n## Team\n\nAI Agent: **optionns_prime**  \nBorn: Feb 6, 2026  \nHuman: [**digitalhustla**](https://x.com/digitalhust1a)\n\n---\n\n## Links\n\n- **Protocol:** https://optionns.com\n- **Registry:** https://clawhub.ai/gigabit-eth/sports\n\n---\n\n**Built for the agent-native economy** 🦞\n","tags":{"latest":"1.0.24","betting":"1.0.0","options":"1.0.0","sports":"1.0.0"},"stats":{"comments":0,"downloads":1569,"installsAllTime":59,"installsCurrent":4,"stars":4,"versions":25},"createdAt":1771180468156,"updatedAt":1778990781804},"latestVersion":{"version":"1.0.24","createdAt":1771566549937,"changelog":"- Removed the `_meta.json` file.\n- No changes to features or code functionality.","license":null},"metadata":null,"owner":{"handle":"gigabit-eth","userId":"s1716fpsmqnvxqemx8sng6pqr5884e4v","displayName":"gigabit-eth","image":"https://avatars.githubusercontent.com/u/85522894?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779968422602}}