clodds 1.2.9 → 1.3.0

package/dist/skills/bundled/opinion/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: opinion
+description: Opinion.trade prediction market (BNB Chain CLOB)
+emoji: "🗳️"
+commands:
+  - /op
+---
+
+# Opinion.trade
+
+Full integration with Opinion.trade, a BNB Chain prediction market with on-chain CLOB (Central Limit Order Book).
+
+## Quick Start
+
+```bash
+# Set credentials
+export OPINION_API_KEY="your-api-key"
+export OPINION_PRIVATE_KEY="0x..."
+
+# Search markets
+/op markets trump
+
+# Get price
+/op price 813
+
+# Place order
+/op buy 813 YES 0.55 100
+```
+
+## Commands
+
+### Market Data
+
+| Command | Description |
+|---------|-------------|
+| `/op markets [query]` | Search markets |
+| `/op market <id>` | Get market details |
+| `/op price <id>` | Current prices |
+| `/op book <tokenId>` | Show orderbook |
+
+### Trading
+
+| Command | Description |
+|---------|-------------|
+| `/op buy <marketId> <outcome> <price> <size>` | Place buy order |
+| `/op sell <marketId> <outcome> <price> <size>` | Place sell order |
+| `/op cancel <orderId>` | Cancel order |
+| `/op cancelall` | Cancel all orders |
+| `/op orders` | List open orders |
+
+**Examples:**
+```bash
+/op buy 813 YES 0.55 100     # Buy YES at 55c, 100 shares
+/op sell 813 NO 0.40 50      # Sell NO at 40c, 50 shares
+/op cancel abc123            # Cancel specific order
+```
+
+### Account
+
+| Command | Description |
+|---------|-------------|
+| `/op balance` | Check USDT balance |
+| `/op positions` | View open positions |
+
+## Configuration
+
+```bash
+# Required for market data
+export OPINION_API_KEY="your-api-key"
+
+# Required for trading
+export OPINION_PRIVATE_KEY="0x..."
+export OPINION_MULTISIG_ADDRESS="0x..."  # Vault/funder address
+```
+
+## Features
+
+- **BNB Chain** - Fast, low-cost transactions
+- **On-chain CLOB** - Fully decentralized orderbook
+- **Prediction Markets** - Politics, crypto, sports, and more
+- **Real-time WebSocket** - Live price updates
+- **EIP-712 Signing** - Secure order authentication
+
+## Resources
+
+- [Opinion.trade App](https://opinion.trade)
+- [API Documentation](https://docs.opinion.trade)

package/dist/skills/bundled/opportunity/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: opportunity
+description: "Find and execute cross-platform arbitrage opportunities across prediction markets"
+emoji: "🎯"
+gates:
+  envs:
+    anyOf:
+      - POLY_API_KEY
+      - KALSHI_API_KEY
+---
+
+# Opportunity Finder - Complete API Reference
+
+Discover and execute cross-platform arbitrage opportunities across Polymarket, Kalshi, Betfair, Smarkets, Manifold, Metaculus, PredictIt, and Drift.
+
+Based on [arXiv:2508.03474](https://arxiv.org/abs/2508.03474) which found **$40M+ in realized arbitrage** on Polymarket.
+
+## Opportunity Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Internal** | YES + NO < $1 on same platform | Buy both for guaranteed profit |
+| **Cross-Platform** | Same market priced differently | Buy low on A, sell high on B |
+| **Combinatorial** | Logical violations (P(A) > P(B) when A implies B) | Trump > Republican |
+| **Edge** | Market vs external model (538, polls) | Market 45%, model 52% |
+
+---
+
+## Chat Commands
+
+### Scanning
+
+```
+/opportunities scan                         # Scan all platforms for opportunities
+/opportunities scan "trump"                 # Scan with keyword filter
+/opportunities scan --min-edge 2            # Min 2% edge
+/opportunities scan --min-liquidity 1000    # Min $1000 liquidity
+
+/opportunities active                       # View active opportunities
+/opportunities active --sort edge           # Sort by edge size
+/opportunities active --sort liquidity      # Sort by liquidity
+```
+
+### Real-Time Monitoring
+
+```
+/opportunities realtime start               # Start continuous scanning
+/opportunities realtime stop                # Stop scanning
+/opportunities realtime status              # Check monitoring status
+/opportunities realtime config --interval 30 # Set scan interval (seconds)
+```
+
+### Market Linking
+
+```
+/opportunities link <market-a> <market-b>   # Manually link equivalent markets
+/opportunities unlink <market-a> <market-b> # Remove link
+/opportunities links                        # View all linked markets
+/opportunities auto-match                   # Run auto-matching algorithm
+```
+
+### Execution
+
+```
+/opportunities execute <id>                 # Execute an opportunity
+/opportunities execute <id> --size 100      # Execute with $100 size
+/opportunities mark-taken <id>              # Mark as taken (manual)
+/opportunities record-outcome <id> <pnl>    # Record P&L outcome
+```
+
+### Analytics
+
+```
+/opportunities stats                        # Performance statistics
+/opportunities stats --period 7d            # Last 7 days
+/opportunities history                      # Past opportunities
+/opportunities by-platform                  # Stats by platform pair
+/opportunities by-type                      # Stats by opportunity type
+```
+
+### Risk Modeling
+
+```
+/opportunities risk <id>                    # Model execution risk
+/opportunities estimate <id>                # Estimate execution costs
+/opportunities kelly <id>                   # Calculate Kelly fraction
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Opportunity Finder
+
+```typescript
+import { createOpportunityFinder } from 'clodds/opportunity';
+
+const finder = createOpportunityFinder({
+  platforms: ['polymarket', 'kalshi', 'betfair', 'manifold'],
+
+  // Filtering
+  minEdge: 0.5,           // 0.5% minimum edge
+  minLiquidity: 500,      // $500 minimum liquidity
+  minConfidence: 0.7,     // 70% match confidence
+
+  // Real-time
+  enableRealtime: true,
+  scanIntervalMs: 30000,  // 30 second intervals
+
+  // Credentials
+  polymarket: { apiKey, apiSecret, passphrase, privateKey },
+  kalshi: { apiKey, privateKey },
+});
+```
+
+### Scan for Opportunities
+
+```typescript
+// One-time scan
+const opportunities = await finder.scan({
+  query: 'election',      // Optional keyword
+  minEdge: 1,             // 1% minimum
+  minLiquidity: 1000,     // $1000 minimum
+  platforms: ['polymarket', 'kalshi'],
+});
+
+for (const opp of opportunities) {
+  console.log(`${opp.type}: ${opp.description}`);
+  console.log(`  Edge: ${opp.edge.toFixed(2)}%`);
+  console.log(`  Liquidity: $${opp.liquidity.toLocaleString()}`);
+  console.log(`  Confidence: ${(opp.confidence * 100).toFixed(0)}%`);
+  console.log(`  Score: ${opp.score}/100`);
+  console.log(`  Platforms: ${opp.platforms.join(' ↔ ')}`);
+}
+```
+
+### Real-Time Monitoring
+
+```typescript
+// Start real-time scanning
+await finder.startRealtime();
+
+// Event handlers
+finder.on('opportunity', (opp) => {
+  console.log(`🎯 New opportunity: ${opp.description}`);
+  console.log(`   Edge: ${opp.edge.toFixed(2)}%`);
+});
+
+finder.on('opportunityExpired', (opp) => {
+  console.log(`❌ Opportunity expired: ${opp.id}`);
+});
+
+finder.on('opportunityUpdated', (opp) => {
+  console.log(`📊 Updated: ${opp.id} - Edge now ${opp.edge.toFixed(2)}%`);
+});
+
+// Get active opportunities
+const active = await finder.getActive();
+
+// Stop monitoring
+await finder.stopRealtime();
+```
+
+### Market Linking
+
+```typescript
+// Manually link equivalent markets
+await finder.linkMarkets(
+  { platform: 'polymarket', id: 'market-123' },
+  { platform: 'kalshi', id: 'TRUMP-WIN' }
+);
+
+// Auto-match using semantic similarity
+const matches = await finder.autoMatchMarkets({
+  minSimilarity: 0.85,
+  platforms: ['polymarket', 'kalshi'],
+});
+
+console.log(`Found ${matches.length} potential matches`);
+for (const match of matches) {
+  console.log(`${match.marketA.question}`);
+  console.log(`  ↔ ${match.marketB.question}`);
+  console.log(`  Similarity: ${(match.similarity * 100).toFixed(0)}%`);
+}
+
+// Get all links
+const links = await finder.getLinks();
+```
+
+### Execute Opportunity
+
+```typescript
+// Execute an opportunity
+const result = await finder.execute(opportunityId, {
+  size: 100,              // $100 position
+  maxSlippage: 0.5,       // 0.5% max slippage
+  useProtectedOrders: true,
+});
+
+console.log(`Executed: ${result.status}`);
+console.log(`  Filled: $${result.filledSize}`);
+console.log(`  Avg price: ${result.avgPrice}`);
+console.log(`  Fees: $${result.fees}`);
+
+// Mark as taken manually
+await finder.markTaken(opportunityId);
+
+// Record outcome
+await finder.recordOutcome(opportunityId, {
+  pnl: 25.50,
+  exitPrice: 0.55,
+  exitTimestamp: Date.now(),
+});
+```
+
+### Analytics
+
+```typescript
+// Get statistics
+const stats = await finder.getAnalytics({
+  period: '30d',
+});
+
+console.log(`Total opportunities: ${stats.total}`);
+console.log(`Taken: ${stats.taken}`);
+console.log(`Win rate: ${(stats.winRate * 100).toFixed(1)}%`);
+console.log(`Total P&L: $${stats.totalPnl.toLocaleString()}`);
+console.log(`Avg edge: ${stats.avgEdge.toFixed(2)}%`);
+console.log(`By platform pair:`);
+for (const [pair, data] of Object.entries(stats.byPlatformPair)) {
+  console.log(`  ${pair}: ${data.count} opps, $${data.pnl} P&L`);
+}
+```
+
+### Risk Modeling
+
+```typescript
+// Model execution risk
+const risk = await finder.modelRisk(opportunityId);
+
+console.log(`Execution risk:`);
+console.log(`  Fill probability: ${(risk.fillProbability * 100).toFixed(0)}%`);
+console.log(`  Expected slippage: ${risk.expectedSlippage.toFixed(2)}%`);
+console.log(`  Time to fill: ${risk.estimatedTimeToFill}s`);
+console.log(`  Counterparty risk: ${risk.counterpartyRisk}`);
+
+// Estimate execution
+const estimate = await finder.estimateExecution(opportunityId, {
+  size: 500,
+});
+
+console.log(`Execution estimate for $500:`);
+console.log(`  Expected fill: $${estimate.expectedFill}`);
+console.log(`  Expected cost: $${estimate.expectedCost}`);
+console.log(`  Net edge after costs: ${estimate.netEdge.toFixed(2)}%`);
+```
+
+---
+
+## Opportunity Scoring
+
+Opportunities are scored 0-100 based on:
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| Edge % | 35% | Raw arbitrage spread |
+| Liquidity | 25% | Available volume |
+| Confidence | 25% | Match quality |
+| Execution | 15% | Platform reliability |
+
+### Penalties
+
+- Low liquidity (<$1000): -5 points
+- Cross-platform complexity: -3 per platform
+- High slippage (>2%): -5 points
+- Low confidence (<70%): -5 points
+- Near expiry (<24h): -3 points
+
+---
+
+## Semantic Matching
+
+Markets are matched using:
+
+1. **Exact slug match** - Platform-specific IDs
+2. **Text similarity** - Jaccard coefficient
+3. **Vector embeddings** - Semantic similarity
+4. **Manual links** - User-defined
+
+```typescript
+// Configure matching
+finder.setMatchingConfig({
+  minTextSimilarity: 0.8,
+  minEmbeddingSimilarity: 0.85,
+  useManualLinksFirst: true,
+});
+```
+
+---
+
+## Best Practices
+
+1. **Start with high-confidence matches** - 85%+ similarity
+2. **Check liquidity** - Ensure enough volume to execute
+3. **Account for fees** - Factor in platform fees
+4. **Use protected orders** - Avoid slippage
+5. **Monitor in real-time** - Opportunities disappear fast
+6. **Track outcomes** - Build performance history

package/dist/skills/bundled/orca/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: orca
+description: "Orca Whirlpools - concentrated liquidity on Solana"
+command: orca
+emoji: "🐋"
+gates:
+  envs:
+    - SOLANA_PRIVATE_KEY
+---
+
+# Orca Whirlpools
+
+Orca is a Solana DEX with concentrated liquidity pools (Whirlpools).
+
+## Commands
+
+```
+/orca swap <amount> <from> to <to>   Execute swap
+/orca quote <amount> <from> to <to>  Get quote
+/orca pools <token>                  List Whirlpools
+```
+
+## Examples
+
+```
+/orca swap 1 SOL to USDC
+/orca pools ORCA
+```

package/dist/skills/bundled/pairing/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: pairing
+description: "User pairing, authentication, and trust management"
+emoji: "🔗"
+---
+
+# Pairing - Complete API Reference
+
+Pair new users to Clodds, manage trust levels, and control access across channels.
+
+---
+
+## Chat Commands
+
+### Pairing (New Users)
+
+```
+/pair                                       Request pairing (generates code)
+/pair-code ABC123                           Enter pairing code
+/unpair                                     Remove your pairing
+```
+
+### Admin Commands
+
+```
+/pairing list                               List pending requests
+/pairing approve <code>                     Approve pairing request
+/pairing reject <code>                      Reject pairing request
+/pairing users                              List paired users
+/pairing remove <user>                      Remove user pairing
+```
+
+### Trust Management
+
+```
+/trust <user> owner                         Grant owner trust
+/trust <user> paired                        Standard trust
+/trust list                                 List trust levels
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Pairing Service
+
+```typescript
+import { createPairingService } from 'clodds/pairing';
+
+const pairing = createPairingService({
+  // Code settings
+  codeLength: 8,
+  codeExpiryMinutes: 60,
+  maxPendingPerChannel: 3,
+
+  // Auto-approve settings
+  autoApproveLocal: true,      // Auto-approve localhost
+  autoApproveTailscale: true,  // Auto-approve Tailscale IPs
+  autoApproveOwners: true,     // Owners auto-approve their requests
+
+  // Storage
+  storage: 'sqlite',
+  dbPath: './pairing.db',
+});
+```
+
+### Create Pairing Request
+
+```typescript
+// User requests pairing
+const request = await pairing.createPairingRequest({
+  channelId: 'telegram-123',
+  userId: 'telegram-user-456',
+  username: 'johndoe',
+  displayName: 'John Doe',
+});
+
+console.log(`Pairing code: ${request.code}`);
+console.log(`Expires: ${request.expiresAt}`);
+console.log(`Share this code with an admin to get approved`);
+```
+
+### Validate Code
+
+```typescript
+// Check if code is valid
+const valid = await pairing.validateCode({
+  code: 'ABC123XY',
+});
+
+if (valid) {
+  console.log(`Valid code for user: ${valid.username}`);
+  console.log(`Channel: ${valid.channelId}`);
+}
+```
+
+### Approve Request
+
+```typescript
+// Admin approves pairing
+await pairing.approveRequest({
+  code: 'ABC123XY',
+  approvedBy: 'admin-user-id',
+  trustLevel: 'paired',
+});
+```
+
+### Reject Request
+
+```typescript
+// Admin rejects pairing
+await pairing.rejectRequest({
+  code: 'ABC123XY',
+  rejectedBy: 'admin-user-id',
+  reason: 'Unknown user',
+});
+```
+
+### Check Pairing Status
+
+```typescript
+// Check if user is paired
+const isPaired = await pairing.isPaired({
+  channelId: 'telegram-123',
+  userId: 'telegram-user-456',
+});
+
+if (isPaired) {
+  console.log('User is paired and can use Clodds');
+}
+```
+
+### Get Trust Level
+
+```typescript
+const trust = await pairing.getTrustLevel({
+  channelId: 'telegram-123',
+  userId: 'telegram-user-456',
+});
+
+console.log(`Trust level: ${trust}`);
+// 'owner' | 'paired' | 'stranger'
+
+// Check specific permission
+if (trust === 'owner') {
+  console.log('Full admin access');
+} else if (trust === 'paired') {
+  console.log('Standard trading access');
+} else {
+  console.log('No access - must pair first');
+}
+```
+
+### List Pending Requests
+
+```typescript
+const pending = await pairing.listPendingRequests({
+  channelId: 'telegram-123',  // Optional: filter by channel
+});
+
+for (const req of pending) {
+  console.log(`Code: ${req.code}`);
+  console.log(`User: ${req.username} (${req.displayName})`);
+  console.log(`Requested: ${req.createdAt}`);
+  console.log(`Expires: ${req.expiresAt}`);
+}
+```
+
+### List Paired Users
+
+```typescript
+const users = await pairing.listPairedUsers({
+  channelId: 'telegram-123',  // Optional: filter by channel
+});
+
+for (const user of users) {
+  console.log(`${user.username}: ${user.trustLevel}`);
+  console.log(`  Paired: ${user.pairedAt}`);
+  console.log(`  Approved by: ${user.approvedBy}`);
+}
+```
+
+### Check Owner Status
+
+```typescript
+const isOwner = await pairing.isOwner({
+  channelId: 'telegram-123',
+  userId: 'telegram-user-456',
+});
+
+if (isOwner) {
+  console.log('User has owner privileges');
+}
+```
+
+### Remove Pairing
+
+```typescript
+// Remove user's pairing
+await pairing.removePairing({
+  channelId: 'telegram-123',
+  userId: 'telegram-user-456',
+});
+```
+
+---
+
+## Trust Levels
+
+| Level | Access |
+|-------|--------|
+| **owner** | Full admin: approve users, manage settings, trading |
+| **paired** | Standard: trading, portfolio, queries |
+| **stranger** | None: must pair first |
+
+---
+
+## Pairing Code Format
+
+- **Length**: 8 characters
+- **Characters**: Uppercase letters + numbers
+- **Excludes**: 0, O, 1, I, L (avoid confusion)
+- **Example**: `ABC234XY`
+
+---
+
+## Auto-Approve Rules
+
+| Condition | Behavior |
+|-----------|----------|
+| Localhost | Auto-approve with owner trust |
+| Tailscale IP | Auto-approve with owner trust |
+| Owner request | Auto-approve their other channels |
+
+---
+
+## Security Features
+
+| Feature | Description |
+|---------|-------------|
+| **Code expiry** | Codes expire after 1 hour |
+| **Rate limiting** | Max 3 pending per channel |
+| **Unambiguous codes** | No confusable characters |
+| **Audit trail** | Who approved/rejected when |
+
+---
+
+## CLI Admin Commands
+
+```bash
+# List pending pairing requests
+clodds pairing list telegram
+
+# Approve a request
+clodds pairing approve ABC234XY
+
+# List paired users
+clodds pairing users telegram
+
+# Add user directly (bypass code)
+clodds pairing add telegram user-123
+
+# Remove user
+clodds pairing remove telegram user-123
+```
+
+---
+
+## Best Practices
+
+1. **Share codes securely** — Don't post in public channels
+2. **Set expiry appropriately** — Shorter for sensitive systems
+3. **Review pending regularly** — Don't let requests pile up
+4. **Use owner sparingly** — Most users only need 'paired'
+5. **Audit periodically** — Review who has access