clodds 1.2.9 → 1.3.0

package/dist/skills/bundled/trading-kalshi/SKILL.md

@@ -0,0 +1,629 @@
+---
+name: trading-kalshi
+description: "Execute trades on Kalshi - full REST API access for markets, orders, positions, balance"
+emoji: "📈"
+gates:
+  envs:
+    - KALSHI_EMAIL
+    - KALSHI_PASSWORD
+---
+
+# Kalshi Trading - Complete API Reference
+
+Full access to Kalshi's CFTC-regulated prediction market via their REST API.
+
+**Docs**: https://docs.kalshi.com/welcome
+**Discord**: #dev channel for support
+
+## Required Environment Variables
+
+```bash
+KALSHI_EMAIL=your@email.com
+KALSHI_PASSWORD=your_password
+```
+
+## Installation
+
+```bash
+pip install requests
+# Optional: pip install kalshi-python  # Official SDK
+```
+
+---
+
+## API Base URLs
+
+```python
+# Production
+BASE_URL = "https://trading-api.kalshi.com/trade-api/v2"
+
+# Demo/Sandbox (for testing)
+DEMO_URL = "https://demo-api.kalshi.co/trade-api/v2"
+```
+
+---
+
+## Authentication
+
+Kalshi uses email/password login returning a bearer token valid for 30 minutes.
+
+### Login & Token Management
+
+```python
+import os
+import time
+import requests
+
+BASE_URL = "https://trading-api.kalshi.com/trade-api/v2"
+
+class KalshiClient:
+    def __init__(self):
+        self.email = os.getenv("KALSHI_EMAIL")
+        self.password = os.getenv("KALSHI_PASSWORD")
+        self.token = None
+        self.token_expiry = 0
+        self.member_id = None
+
+    def _ensure_auth(self):
+        """Refresh token if expired (30 min lifetime)"""
+        if time.time() > self.token_expiry - 60:
+            self._login()
+
+    def _login(self):
+        """POST /login - Get new auth token"""
+        r = requests.post(f"{BASE_URL}/login", json={
+            "email": self.email,
+            "password": self.password
+        })
+        r.raise_for_status()
+        data = r.json()
+        self.token = data["token"]
+        self.member_id = data.get("member_id")
+        self.token_expiry = time.time() + 29 * 60  # Refresh at 29 mins
+        return data
+
+    def _headers(self):
+        """Get auth headers for requests"""
+        self._ensure_auth()
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json"
+        }
+
+    def logout(self):
+        """POST /logout - Invalidate current token"""
+        r = requests.post(f"{BASE_URL}/logout", headers=self._headers())
+        self.token = None
+        self.token_expiry = 0
+        return r.status_code == 200
+
+# Initialize
+client = KalshiClient()
+```
+
+---
+
+## Market Data Endpoints
+
+### Get Markets
+
+```python
+def get_markets(
+    status: str = "open",    # "open", "closed", "settled"
+    series_ticker: str = None,  # Filter by series
+    limit: int = 100,
+    cursor: str = None  # For pagination
+):
+    """GET /markets - List markets"""
+    params = {"status": status, "limit": limit}
+    if series_ticker:
+        params["series_ticker"] = series_ticker
+    if cursor:
+        params["cursor"] = cursor
+
+    r = requests.get(f"{BASE_URL}/markets", headers=client._headers(), params=params)
+    r.raise_for_status()
+    data = r.json()
+    return {
+        "markets": data.get("markets", []),
+        "cursor": data.get("cursor")  # Use for pagination
+    }
+
+# Examples
+markets = get_markets(series_ticker="INXD")  # S&P 500 daily
+markets = get_markets(series_ticker="FED")    # Fed rate decisions
+markets = get_markets(series_ticker="KXBTC")  # Bitcoin price
+```
+
+### Get Single Market
+
+```python
+def get_market(ticker: str):
+    """GET /markets/{ticker} - Single market details"""
+    r = requests.get(f"{BASE_URL}/markets/{ticker}", headers=client._headers())
+    r.raise_for_status()
+    return r.json()["market"]
+
+market = get_market("INXD-24JAN10-T5805")
+# Returns: ticker, title, subtitle, status, yes_bid, yes_ask,
+#          no_bid, no_ask, volume, open_interest, close_time, result
+```
+
+### Get Market Orderbook
+
+```python
+def get_orderbook(ticker: str, depth: int = 10):
+    """GET /markets/{ticker}/orderbook - Full orderbook"""
+    r = requests.get(f"{BASE_URL}/markets/{ticker}/orderbook",
+                    headers=client._headers(),
+                    params={"depth": depth})
+    r.raise_for_status()
+    data = r.json()["orderbook"]
+
+    # data["yes"] = list of [price, size] for YES side
+    # data["no"] = list of [price, size] for NO side
+    return data
+
+book = get_orderbook("INXD-24JAN10-T5805")
+print(f"Yes bids: {book['yes']}")  # [[45, 100], [44, 200], ...]
+print(f"No asks: {book['no']}")
+```
+
+### Get Market History/Trades
+
+```python
+def get_market_history(ticker: str, limit: int = 100):
+    """GET /markets/{ticker}/history - Trade history"""
+    r = requests.get(f"{BASE_URL}/markets/{ticker}/history",
+                    headers=client._headers(),
+                    params={"limit": limit})
+    r.raise_for_status()
+    return r.json().get("history", [])
+
+trades = get_market_history("INXD-24JAN10-T5805")
+for t in trades:
+    print(f"{t['created_time']}: {t['count']} @ {t['yes_price']}¢")
+```
+
+### Get Series/Events
+
+```python
+def get_series():
+    """GET /series - List all series (categories)"""
+    r = requests.get(f"{BASE_URL}/series", headers=client._headers())
+    r.raise_for_status()
+    return r.json().get("series", [])
+
+def get_events(series_ticker: str = None):
+    """GET /events - List events"""
+    params = {}
+    if series_ticker:
+        params["series_ticker"] = series_ticker
+    r = requests.get(f"{BASE_URL}/events", headers=client._headers(), params=params)
+    r.raise_for_status()
+    return r.json().get("events", [])
+
+series = get_series()
+events = get_events("FED")
+```
+
+---
+
+## Order Management
+
+### Place Order
+
+```python
+def place_order(
+    ticker: str,
+    side: str,           # "yes" or "no"
+    action: str,         # "buy" or "sell"
+    count: int,          # Number of contracts
+    price: int = None,   # Price in cents (1-99), None for market
+    order_type: str = "limit",  # "limit" or "market"
+    expiration_ts: int = None,  # Optional: GTD expiration timestamp
+    client_order_id: str = None  # Optional: Your reference ID
+):
+    """POST /portfolio/orders - Place an order"""
+    payload = {
+        "ticker": ticker,
+        "side": side.lower(),
+        "action": action.lower(),
+        "count": count,
+        "type": order_type
+    }
+
+    if order_type == "limit" and price:
+        # yes_price is always from YES perspective
+        payload["yes_price"] = price if side.lower() == "yes" else (100 - price)
+
+    if expiration_ts:
+        payload["expiration_ts"] = expiration_ts
+
+    if client_order_id:
+        payload["client_order_id"] = client_order_id
+
+    r = requests.post(f"{BASE_URL}/portfolio/orders",
+                     headers=client._headers(),
+                     json=payload)
+    r.raise_for_status()
+    return r.json()
+
+# Examples
+# Buy 10 YES at 45 cents
+result = place_order("INXD-24JAN10-T5805", "yes", "buy", 10, 45)
+
+# Sell 5 NO at 30 cents (equivalent to YES at 70 cents)
+result = place_order("INXD-24JAN10-T5805", "no", "sell", 5, 30)
+
+# Market order (immediate fill)
+result = place_order("INXD-24JAN10-T5805", "yes", "buy", 10, order_type="market")
+```
+
+### Batch Create Orders
+
+```python
+def batch_create_orders(orders: list):
+    """POST /portfolio/orders/batched - Create multiple orders"""
+    payload = {"orders": orders}
+    r = requests.post(f"{BASE_URL}/portfolio/orders/batched",
+                     headers=client._headers(),
+                     json=payload)
+    r.raise_for_status()
+    return r.json()
+
+orders = [
+    {"ticker": "INXD-24JAN10-T5805", "side": "yes", "action": "buy", "count": 5, "type": "limit", "yes_price": 40},
+    {"ticker": "INXD-24JAN10-T5805", "side": "yes", "action": "buy", "count": 5, "type": "limit", "yes_price": 42},
+]
+results = batch_create_orders(orders)
+```
+
+### Amend Order
+
+```python
+def amend_order(order_id: str, count: int = None, price: int = None):
+    """POST /portfolio/orders/{order_id}/amend - Modify order"""
+    payload = {}
+    if count:
+        payload["count"] = count
+    if price:
+        payload["yes_price"] = price
+
+    r = requests.post(f"{BASE_URL}/portfolio/orders/{order_id}/amend",
+                     headers=client._headers(),
+                     json=payload)
+    r.raise_for_status()
+    return r.json()
+```
+
+### Decrease Order Size
+
+```python
+def decrease_order(order_id: str, reduce_by: int):
+    """POST /portfolio/orders/{order_id}/decrease - Reduce order size"""
+    r = requests.post(f"{BASE_URL}/portfolio/orders/{order_id}/decrease",
+                     headers=client._headers(),
+                     json={"reduce_by": reduce_by})
+    r.raise_for_status()
+    return r.json()
+```
+
+### Cancel Order
+
+```python
+def cancel_order(order_id: str):
+    """DELETE /portfolio/orders/{order_id} - Cancel single order"""
+    r = requests.delete(f"{BASE_URL}/portfolio/orders/{order_id}",
+                       headers=client._headers())
+    return r.status_code in [200, 204]
+
+def batch_cancel_orders(order_ids: list):
+    """DELETE /portfolio/orders/batched - Cancel multiple orders"""
+    r = requests.delete(f"{BASE_URL}/portfolio/orders/batched",
+                       headers=client._headers(),
+                       json={"order_ids": order_ids})
+    r.raise_for_status()
+    return r.json()
+
+# Cancel specific order
+cancel_order("abc123-order-id")
+
+# Cancel multiple
+batch_cancel_orders(["order-1", "order-2", "order-3"])
+```
+
+### Get Orders
+
+```python
+def get_orders(
+    ticker: str = None,
+    status: str = None,  # "resting", "canceled", "executed", "pending"
+    limit: int = 100
+):
+    """GET /portfolio/orders - List orders"""
+    params = {"limit": limit}
+    if ticker:
+        params["ticker"] = ticker
+    if status:
+        params["status"] = status
+
+    r = requests.get(f"{BASE_URL}/portfolio/orders",
+                    headers=client._headers(),
+                    params=params)
+    r.raise_for_status()
+    return r.json().get("orders", [])
+
+def get_order(order_id: str):
+    """GET /portfolio/orders/{order_id} - Single order"""
+    r = requests.get(f"{BASE_URL}/portfolio/orders/{order_id}",
+                    headers=client._headers())
+    r.raise_for_status()
+    return r.json()["order"]
+
+# Get all open orders
+orders = get_orders(status="resting")
+for o in orders:
+    print(f"{o['order_id']}: {o['action']} {o['side']} {o['remaining_count']} @ {o['yes_price']}¢")
+```
+
+---
+
+## Portfolio Management
+
+### Get Balance
+
+```python
+def get_balance():
+    """GET /portfolio/balance - Account balance"""
+    r = requests.get(f"{BASE_URL}/portfolio/balance", headers=client._headers())
+    r.raise_for_status()
+    data = r.json()
+
+    return {
+        "balance": data.get("balance", 0) / 100,  # Available in dollars
+        "portfolio_value": data.get("portfolio_value", 0) / 100
+    }
+
+bal = get_balance()
+print(f"Available: ${bal['balance']:.2f}")
+print(f"Portfolio: ${bal['portfolio_value']:.2f}")
+```
+
+### Get Positions
+
+```python
+def get_positions(limit: int = 100):
+    """GET /portfolio/positions - Current positions"""
+    r = requests.get(f"{BASE_URL}/portfolio/positions",
+                    headers=client._headers(),
+                    params={"limit": limit})
+    r.raise_for_status()
+    return r.json().get("market_positions", [])
+
+positions = get_positions()
+for p in positions:
+    if p.get("position", 0) != 0:
+        print(f"{p['ticker']}: {p['position']} contracts @ avg {p['average_price']}¢")
+        print(f"  Realized P&L: ${p.get('realized_pnl', 0) / 100:.2f}")
+```
+
+### Get Fills (Trade History)
+
+```python
+def get_fills(
+    ticker: str = None,
+    limit: int = 100,
+    cursor: str = None
+):
+    """GET /portfolio/fills - Executed trades"""
+    params = {"limit": limit}
+    if ticker:
+        params["ticker"] = ticker
+    if cursor:
+        params["cursor"] = cursor
+
+    r = requests.get(f"{BASE_URL}/portfolio/fills",
+                    headers=client._headers(),
+                    params=params)
+    r.raise_for_status()
+    data = r.json()
+    return {
+        "fills": data.get("fills", []),
+        "cursor": data.get("cursor")
+    }
+
+fills = get_fills()
+for f in fills["fills"]:
+    print(f"{f['created_time']}: {f['action']} {f['side']} {f['count']} @ {f['price']}¢")
+```
+
+### Get Settlements
+
+```python
+def get_settlements(limit: int = 100):
+    """GET /portfolio/settlements - Settlement history"""
+    r = requests.get(f"{BASE_URL}/portfolio/settlements",
+                    headers=client._headers(),
+                    params={"limit": limit})
+    r.raise_for_status()
+    return r.json().get("settlements", [])
+
+settlements = get_settlements()
+for s in settlements:
+    print(f"{s['ticker']}: Settled at {s['settlement_value']}¢, P&L: ${s['revenue'] / 100:.2f}")
+```
+
+---
+
+## Exchange Status
+
+```python
+def get_exchange_status():
+    """GET /exchange/status - Exchange operational status"""
+    r = requests.get(f"{BASE_URL}/exchange/status", headers=client._headers())
+    r.raise_for_status()
+    return r.json()
+
+status = get_exchange_status()
+print(f"Trading: {status.get('trading_active')}")
+print(f"Exchange open: {status.get('exchange_active')}")
+```
+
+---
+
+## WebSocket (Real-time Data)
+
+For real-time updates, use WebSocket after REST authentication:
+
+```python
+import websocket
+import json
+
+def on_message(ws, message):
+    data = json.loads(message)
+    print(f"Update: {data}")
+
+def on_open(ws):
+    # Subscribe to orderbook updates
+    ws.send(json.dumps({
+        "type": "subscribe",
+        "channel": "orderbook",
+        "ticker": "INXD-24JAN10-T5805"
+    }))
+
+# Connect with auth token
+ws = websocket.WebSocketApp(
+    f"wss://trading-api.kalshi.com/trade-api/ws/v2?token={client.token}",
+    on_message=on_message,
+    on_open=on_open
+)
+ws.run_forever()
+```
+
+---
+
+## Complete Trading Bot
+
+```python
+#!/usr/bin/env python3
+"""
+Production Kalshi trading bot
+"""
+
+import os
+import time
+import requests
+
+BASE_URL = "https://trading-api.kalshi.com/trade-api/v2"
+
+class KalshiBot:
+    def __init__(self):
+        self.email = os.getenv("KALSHI_EMAIL")
+        self.password = os.getenv("KALSHI_PASSWORD")
+        self.token = None
+        self.token_expiry = 0
+
+    def _auth(self):
+        if time.time() > self.token_expiry - 60:
+            r = requests.post(f"{BASE_URL}/login", json={
+                "email": self.email, "password": self.password
+            })
+            r.raise_for_status()
+            self.token = r.json()["token"]
+            self.token_expiry = time.time() + 29 * 60
+
+    def _h(self):
+        self._auth()
+        return {"Authorization": f"Bearer {self.token}", "Content-Type": "application/json"}
+
+    def get_market(self, ticker):
+        r = requests.get(f"{BASE_URL}/markets/{ticker}", headers=self._h())
+        r.raise_for_status()
+        return r.json()["market"]
+
+    def get_positions(self):
+        r = requests.get(f"{BASE_URL}/portfolio/positions", headers=self._h())
+        r.raise_for_status()
+        return {p["ticker"]: p for p in r.json().get("market_positions", [])}
+
+    def get_balance(self):
+        r = requests.get(f"{BASE_URL}/portfolio/balance", headers=self._h())
+        r.raise_for_status()
+        return r.json().get("balance", 0) / 100
+
+    def buy(self, ticker, side, count, price):
+        payload = {
+            "ticker": ticker, "side": side, "action": "buy",
+            "count": count, "type": "limit",
+            "yes_price": price if side == "yes" else (100 - price)
+        }
+        r = requests.post(f"{BASE_URL}/portfolio/orders", headers=self._h(), json=payload)
+        return r.json() if r.status_code == 200 else {"error": r.text}
+
+    def sell(self, ticker, side, count, price):
+        payload = {
+            "ticker": ticker, "side": side, "action": "sell",
+            "count": count, "type": "limit",
+            "yes_price": price if side == "yes" else (100 - price)
+        }
+        r = requests.post(f"{BASE_URL}/portfolio/orders", headers=self._h(), json=payload)
+        return r.json() if r.status_code == 200 else {"error": r.text}
+
+# Run
+bot = KalshiBot()
+TICKER = "INXD-24JAN10-T5805"
+
+while True:
+    try:
+        market = bot.get_market(TICKER)
+        positions = bot.get_positions()
+        balance = bot.get_balance()
+
+        yes_bid = market["yes_bid"]
+        yes_ask = market["yes_ask"]
+        pos = positions.get(TICKER, {}).get("position", 0)
+
+        print(f"Balance: ${balance:.2f}, Position: {pos}, Price: {yes_bid}/{yes_ask}")
+
+        # Trading logic
+        if yes_ask < 40 and pos < 10 and balance > 5:
+            print(f"BUYING at {yes_ask}")
+            bot.buy(TICKER, "yes", 5, yes_ask)
+        elif yes_bid > 60 and pos > 0:
+            print(f"SELLING at {yes_bid}")
+            bot.sell(TICKER, "yes", pos, yes_bid)
+
+        time.sleep(10)
+
+    except Exception as e:
+        print(f"Error: {e}")
+        time.sleep(30)
+```
+
+---
+
+## Popular Market Series
+
+| Series | Description | Example Ticker |
+|--------|-------------|----------------|
+| FED | Fed rate decisions | FED-24MAR-T525 |
+| INXD | S&P 500 daily close | INXD-24JAN10-T5805 |
+| KXBTC | Bitcoin price brackets | KXBTC-24JAN-T45000 |
+| KXETH | Ethereum price | KXETH-24JAN-T2500 |
+| CPI | Inflation data | CPI-24JAN-T3.5 |
+| GDP | GDP growth | GDP-24Q1-T2.0 |
+| NFP | Non-farm payrolls | NFP-24JAN-T200K |
+
+---
+
+## Key Notes
+
+1. **Prices in CENTS** - 45 means $0.45 per contract
+2. **Contracts pay $1 if correct** - Cost is the price, profit is $1 - price
+3. **No trading fees** - Only spread matters
+4. **Token expires in 30 min** - Auto-refresh before expiry
+5. **US residents only** - KYC verification required
+6. **Rate limits exist** - Implement exponential backoff on 429 errors
+7. **Max position limits** - Varies by market, check market details
+