clodds 1.2.9 → 1.3.0

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

@@ -0,0 +1,278 @@
+---
+name: execution
+description: "Execute trades on prediction markets with slippage protection and order management"
+emoji: "⚡"
+gates:
+  envs:
+    anyOf:
+      - POLY_API_KEY
+      - KALSHI_API_KEY
+---
+
+# Execution Service - Complete API Reference
+
+Execute trades on Polymarket and Kalshi with slippage protection, maker orders, and order management.
+
+## Supported Platforms
+
+| Platform | Order Types | Features |
+|----------|-------------|----------|
+| Polymarket | Limit, Market, Maker | -0.5% maker rebate, GTC/FOK |
+| Kalshi | Limit, Market | US regulated |
+
+---
+
+## Chat Commands
+
+### Place Orders
+
+```
+/execute buy poly <market> YES 100 @ 0.52   # Limit buy on Polymarket
+/execute sell kalshi <market> NO 50 @ 0.48  # Limit sell on Kalshi
+/execute market-buy poly <market> YES 100   # Market buy
+/execute market-sell poly <market> NO 50    # Market sell
+```
+
+### Maker Orders (Rebates)
+
+```
+/execute maker-buy poly <market> YES 100 @ 0.52   # Post-only buy
+/execute maker-sell poly <market> NO 50 @ 0.48    # Post-only sell
+```
+
+### Protected Orders (Slippage Protection)
+
+```
+/execute protected-buy poly <market> YES 100 --max-slippage 1%
+/execute protected-sell poly <market> NO 50 --max-slippage 0.5%
+```
+
+### Order Management
+
+```
+/orders open                                # View open orders
+/orders open poly                           # Open orders on Polymarket
+/orders cancel <order-id>                   # Cancel specific order
+/orders cancel-all                          # Cancel all open orders
+/orders cancel-all poly                     # Cancel all on Polymarket
+```
+
+### Slippage Estimation
+
+```
+/estimate-slippage poly <market> buy 1000   # Estimate slippage for $1000 buy
+/estimate-slippage kalshi <market> sell 500 # Estimate for $500 sell
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Execution Service
+
+```typescript
+import { createExecutionService } from 'clodds/execution';
+
+const executor = createExecutionService({
+  polymarket: {
+    apiKey: process.env.POLY_API_KEY,
+    apiSecret: process.env.POLY_API_SECRET,
+    passphrase: process.env.POLY_API_PASSPHRASE,
+    privateKey: process.env.PRIVATE_KEY,
+  },
+  kalshi: {
+    apiKey: process.env.KALSHI_API_KEY,
+    privateKey: process.env.KALSHI_PRIVATE_KEY,
+  },
+
+  // Defaults
+  defaultSlippageTolerance: 0.5,  // 0.5%
+  autoLogTrades: true,
+});
+```
+
+### Limit Orders
+
+```typescript
+// Buy limit order
+const order = await executor.buyLimit({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'YES',
+  size: 100,           // $100
+  price: 0.52,         // 52 cents
+  timeInForce: 'GTC',  // Good-til-cancel
+});
+
+console.log(`Order placed: ${order.orderId}`);
+console.log(`Status: ${order.status}`);
+
+// Sell limit order
+const sellOrder = await executor.sellLimit({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'YES',
+  size: 100,
+  price: 0.55,
+});
+```
+
+### Market Orders
+
+```typescript
+// Market buy - executes immediately at best price
+const order = await executor.marketBuy({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'YES',
+  size: 100,
+});
+
+console.log(`Filled at: ${order.avgFillPrice}`);
+console.log(`Filled size: ${order.filledSize}`);
+
+// Market sell
+const sellOrder = await executor.marketSell({
+  platform: 'kalshi',
+  marketId: 'TRUMP-WIN',
+  side: 'YES',
+  size: 50,
+});
+```
+
+### Maker Orders (Post-Only)
+
+```typescript
+// Maker buy - only executes as maker (gets rebate)
+const order = await executor.makerBuy({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'YES',
+  size: 100,
+  price: 0.52,
+});
+
+// Will be rejected if it would execute immediately as taker
+if (order.status === 'rejected') {
+  console.log('Price too aggressive - would be taker');
+}
+
+// Maker sell
+const sellOrder = await executor.makerSell({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'NO',
+  size: 50,
+  price: 0.48,
+});
+```
+
+### Protected Orders (Slippage Protection)
+
+```typescript
+// Protected buy - checks slippage before executing
+const order = await executor.protectedBuy({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'YES',
+  size: 100,
+  maxSlippage: 0.5,  // 0.5% max slippage
+});
+
+if (order.status === 'rejected') {
+  console.log(`Rejected: slippage would be ${order.estimatedSlippage}%`);
+} else {
+  console.log(`Executed with ${order.actualSlippage}% slippage`);
+}
+
+// Protected sell
+const sellOrder = await executor.protectedSell({
+  platform: 'kalshi',
+  marketId: 'TRUMP-WIN',
+  side: 'YES',
+  size: 50,
+  maxSlippage: 1,
+});
+```
+
+### Order Management
+
+```typescript
+// Cancel specific order
+await executor.cancelOrder('polymarket', orderId);
+
+// Cancel all orders on platform
+await executor.cancelAllOrders('polymarket');
+
+// Cancel all orders for a market
+await executor.cancelAllOrders('polymarket', { marketId: 'market-123' });
+
+// Get open orders
+const openOrders = await executor.getOpenOrders('polymarket');
+
+for (const order of openOrders) {
+  console.log(`${order.orderId}: ${order.side} ${order.size} @ ${order.price}`);
+  console.log(`  Status: ${order.status}`);
+  console.log(`  Filled: ${order.filledSize}/${order.size}`);
+}
+```
+
+### Slippage Estimation
+
+```typescript
+// Estimate slippage before executing
+const estimate = await executor.estimateSlippage({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  side: 'buy',
+  size: 1000,
+});
+
+console.log(`For $1000 buy:`);
+console.log(`  Avg fill price: ${estimate.avgFillPrice}`);
+console.log(`  Expected slippage: ${estimate.slippagePct}%`);
+console.log(`  Total filled: ${estimate.totalFilled}`);
+console.log(`  Levels consumed: ${estimate.levelsConsumed}`);
+```
+
+---
+
+## Order Types
+
+| Type | Description | Best For |
+|------|-------------|----------|
+| **Limit** | Execute at specific price or better | Price-sensitive orders |
+| **Market** | Execute immediately at best available | Urgent execution |
+| **Maker** | Post-only, gets rebate | Collecting rebates |
+| **Protected** | Checks slippage before executing | Large orders |
+
+## Time In Force
+
+| Value | Description |
+|-------|-------------|
+| **GTC** | Good-til-cancel (default) |
+| **FOK** | Fill-or-kill - all or nothing |
+| **IOC** | Immediate-or-cancel - fill what you can |
+
+---
+
+## Fee Structure
+
+### Polymarket (Verified Jan 2026)
+- **Most markets**: 0% maker, 0% taker (zero fees)
+- **15-min crypto markets**: Dynamic taker fees up to ~3% at 50/50 odds; makers eligible for rebate program
+
+### Kalshi
+- **Taker**: Formula-based ~1.2% average, capped at ~2%
+- **Maker**: ~0.17% (formula-based)
+
+---
+
+## Best Practices
+
+1. **Use maker orders** when possible - Pay no fees on Polymarket (most markets)
+2. **Check slippage** before large orders
+3. **Use protected orders** for size > $500
+4. **Set appropriate timeInForce** - GTC for patient orders, FOK for all-or-nothing
+5. **Monitor open orders** - Cancel stale orders
+6. **Start small** - Test with small sizes first

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

@@ -0,0 +1,80 @@
+---
+name: farcaster
+description: "Farcaster social protocol via Neynar API - read feeds, post casts, follow users"
+command: fc
+emoji: "🟪"
+gates:
+  envs:
+    - NEYNAR_API_KEY
+---
+
+# Farcaster
+
+Interact with the Farcaster decentralized social protocol via Neynar API.
+
+## Setup
+
+Get your API key from [dev.neynar.com](https://dev.neynar.com):
+
+```bash
+export NEYNAR_API_KEY=xxx
+
+# Optional: For posting (requires signer)
+export NEYNAR_SIGNER_UUID=xxx
+```
+
+## Commands
+
+### Users
+```
+/fc user <username>           Look up user profile
+/fc search-users <query>      Search for users
+```
+
+### Feeds
+```
+/fc feed [--channel X]        Get feed (optionally from channel)
+/fc trending                  Trending casts
+/fc channel <id>              Get channel info
+/fc channels <query>          Search channels
+```
+
+### Search
+```
+/fc search <query>            Search casts
+```
+
+### Write Operations (require signer)
+```
+/fc post <text>               Post a cast
+/fc reply <hash> <text>       Reply to a cast
+/fc like <hash>               Like a cast
+/fc recast <hash>             Recast
+/fc follow <username>         Follow user
+/fc unfollow <username>       Unfollow user
+```
+
+## Examples
+
+```
+/fc user vitalik.eth
+/fc trending
+/fc channel base
+/fc search "ethereum"
+/fc post "Hello Farcaster!"
+/fc follow dwr.eth
+```
+
+## Rate Limits
+
+- Free tier: 300 requests/minute
+- Standard: 1,000 requests/minute
+- Premium: Higher limits
+
+## Features
+
+- User profiles with verified addresses
+- Cast search and feeds
+- Channel discovery
+- Trending content
+- Full write operations (with signer)

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

@@ -0,0 +1,20 @@
+---
+name: features
+description: "Real-time market features and trading signals"
+command: features
+emoji: "📈"
+---
+
+# Features
+
+View real-time market features and trading signals computed from tick and orderbook data.
+
+## Commands
+
+```
+/features get <platform> <marketId>       Get features for a specific market
+/features all                             List all tracked markets
+/features signals <platform> <marketId>   Get trading signals and recommendations
+/features stats                           Show feature engine statistics
+/features help                            Show help
+```

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

@@ -0,0 +1,288 @@
+---
+name: feeds
+description: "Real-time market data feeds from 8 prediction market platforms"
+emoji: "📡"
+---
+
+# Market Feeds - Complete API Reference
+
+Real-time and historical market data from Polymarket, Kalshi, Manifold, Metaculus, PredictIt, Drift, Betfair, and Smarkets.
+
+## Supported Platforms
+
+| Platform | Feed Type | Trading | Data |
+|----------|-----------|---------|------|
+| Polymarket | WebSocket + RTDS | Yes | Prices, orderbook, trades |
+| Kalshi | WebSocket | Yes | Prices, orderbook |
+| Betfair | WebSocket | Yes | Odds, volume |
+| Smarkets | WebSocket | Yes | Odds, volume |
+| Drift | REST | Yes | Prices, funding |
+| Manifold | WebSocket | Read-only | Prices, comments |
+| Metaculus | REST | Read-only | Forecasts |
+| PredictIt | REST | Read-only | Prices |
+
+---
+
+## Chat Commands
+
+### Search Markets
+
+```
+/feed search "trump"                        # Search all platforms
+/feed search "election" --platform poly     # Search specific platform
+/feed search "fed rate" --limit 20          # Limit results
+```
+
+### Get Prices
+
+```
+/feed price poly <market-id>                # Get current price
+/feed price kalshi TRUMP-WIN                # Kalshi market
+/feed prices "trump"                        # Prices for all matching markets
+```
+
+### Orderbook
+
+```
+/feed orderbook poly <market-id>            # Get orderbook
+/feed orderbook poly <market-id> --depth 10 # Limit depth
+```
+
+### Subscribe (Real-time)
+
+```
+/feed subscribe poly <market-id>            # Subscribe to price updates
+/feed unsubscribe poly <market-id>          # Unsubscribe
+/feed subscriptions                         # List active subscriptions
+```
+
+### News
+
+```
+/feed news "trump"                          # Get news for topic
+/feed news <market-id>                      # News for specific market
+/feed news --recent 10                      # Last 10 news items
+```
+
+### Edge Analysis
+
+```
+/feed edge poly <market-id>                 # Analyze edge vs models
+/feed kelly poly <market-id> --prob 0.55    # Calculate Kelly fraction
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Feed Manager
+
+```typescript
+import { createFeedManager } from 'clodds/feeds';
+
+const feeds = createFeedManager({
+  platforms: ['polymarket', 'kalshi', 'manifold', 'betfair'],
+
+  // Enable real-time
+  enableRealtime: true,
+
+  // Platform credentials (optional for read-only)
+  polymarket: { apiKey },
+  kalshi: { apiKey },
+  betfair: { appKey, sessionToken },
+});
+```
+
+### Search Markets
+
+```typescript
+// Search across all platforms
+const results = await feeds.searchMarkets('trump election', {
+  platforms: ['polymarket', 'kalshi'],
+  limit: 20,
+  sortBy: 'volume',
+});
+
+for (const market of results) {
+  console.log(`[${market.platform}] ${market.question}`);
+  console.log(`  Price: ${market.price}`);
+  console.log(`  Volume: $${market.volume.toLocaleString()}`);
+}
+```
+
+### Get Single Market
+
+```typescript
+// Get specific market
+const market = await feeds.getMarket('polymarket', 'market-123');
+
+console.log(`Question: ${market.question}`);
+console.log(`YES: ${market.yesPrice} / NO: ${market.noPrice}`);
+console.log(`Volume: $${market.volume.toLocaleString()}`);
+console.log(`End date: ${market.endDate}`);
+```
+
+### Get Price
+
+```typescript
+// Get current price
+const price = await feeds.getPrice('polymarket', 'market-123');
+
+console.log(`YES: ${price.yes}`);
+console.log(`NO: ${price.no}`);
+console.log(`Spread: ${price.spread}`);
+console.log(`Updated: ${price.timestamp}`);
+```
+
+### Get Orderbook
+
+```typescript
+// Get orderbook
+const orderbook = await feeds.getOrderbook('polymarket', 'market-123', {
+  depth: 10,
+});
+
+console.log('Bids (YES):');
+for (const bid of orderbook.bids) {
+  console.log(`  ${bid.price}: $${bid.size}`);
+}
+
+console.log('Asks (YES):');
+for (const ask of orderbook.asks) {
+  console.log(`  ${ask.price}: $${ask.size}`);
+}
+```
+
+### Subscribe to Real-time Updates
+
+```typescript
+// Subscribe to price updates
+const subscription = await feeds.subscribePrice('polymarket', 'market-123');
+
+subscription.on('price', (update) => {
+  console.log(`Price update: YES=${update.yes}, NO=${update.no}`);
+});
+
+subscription.on('trade', (trade) => {
+  console.log(`Trade: ${trade.side} ${trade.size} @ ${trade.price}`);
+});
+
+// Unsubscribe
+await subscription.unsubscribe();
+```
+
+### News
+
+```typescript
+// Get recent news
+const news = await feeds.getRecentNews('trump', { limit: 10 });
+
+for (const article of news) {
+  console.log(`[${article.source}] ${article.title}`);
+  console.log(`  ${article.summary}`);
+  console.log(`  ${article.url}`);
+}
+
+// Search news
+const searchResults = await feeds.searchNews('federal reserve', {
+  from: '2024-01-01',
+  sources: ['reuters', 'bloomberg'],
+});
+```
+
+### Edge Analysis
+
+```typescript
+// Analyze edge vs external models
+const edge = await feeds.analyzeEdge('polymarket', 'market-123');
+
+console.log(`Market price: ${edge.marketPrice}`);
+console.log(`Model estimates:`);
+for (const model of edge.models) {
+  console.log(`  ${model.name}: ${model.estimate}`);
+  console.log(`    Edge: ${model.edge > 0 ? '+' : ''}${model.edge.toFixed(1)}%`);
+}
+console.log(`Consensus edge: ${edge.consensusEdge.toFixed(1)}%`);
+```
+
+### Kelly Criterion
+
+```typescript
+// Calculate optimal position size
+const kelly = await feeds.calculateKelly({
+  platform: 'polymarket',
+  marketId: 'market-123',
+  estimatedProbability: 0.55,  // Your estimate
+  bankroll: 10000,             // Your bankroll
+  kellyFraction: 0.5,          // Half-Kelly for safety
+});
+
+console.log(`Market price: ${kelly.marketPrice}`);
+console.log(`Your estimate: ${kelly.estimatedProb}`);
+console.log(`Edge: ${kelly.edge.toFixed(1)}%`);
+console.log(`Full Kelly: ${kelly.fullKelly.toFixed(1)}%`);
+console.log(`Recommended size: $${kelly.recommendedSize}`);
+```
+
+---
+
+## Platform-Specific Features
+
+### Polymarket RTDS (Real-time Data Service)
+
+```typescript
+// Connect to RTDS for ultra-low-latency updates
+const rtds = await feeds.connectRTDS('polymarket');
+
+rtds.on('tick', (tick) => {
+  console.log(`${tick.market}: ${tick.price} (${tick.side})`);
+});
+
+rtds.subscribe(['market-123', 'market-456']);
+```
+
+### Betfair Odds
+
+```typescript
+// Get Betfair odds
+const odds = await feeds.getBetfairOdds('event-123');
+
+for (const runner of odds.runners) {
+  console.log(`${runner.name}: ${runner.backOdds} / ${runner.layOdds}`);
+}
+```
+
+### Metaculus Forecasts
+
+```typescript
+// Get Metaculus community forecast
+const forecast = await feeds.getMetaculusForecast('question-123');
+
+console.log(`Community median: ${forecast.median}`);
+console.log(`25th percentile: ${forecast.q25}`);
+console.log(`75th percentile: ${forecast.q75}`);
+console.log(`Forecasters: ${forecast.forecasterCount}`);
+```
+
+---
+
+## Data Refresh Rates
+
+| Platform | REST | WebSocket |
+|----------|------|-----------|
+| Polymarket | 5s | Real-time |
+| Kalshi | 10s | Real-time |
+| Betfair | 1s | Real-time |
+| Manifold | 30s | Real-time |
+| Metaculus | 60s | N/A |
+| PredictIt | 30s | N/A |
+
+---
+
+## Best Practices
+
+1. **Use WebSocket** for real-time trading decisions
+2. **Cache responses** for non-time-sensitive queries
+3. **Respect rate limits** - batch requests when possible
+4. **Subscribe selectively** - only to markets you need
+5. **Handle reconnections** - WebSocket connections can drop