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