Optionns

SKILL.md

# 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** 🦞