@farazirfan/costar-server-executor 1.7.20 → 1.7.21

package/skills/coinbase/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: coinbase
+description: "Execute real trades on Coinbase Advanced Trade. Supports market, limit, stop-limit, and bracket orders for crypto. Handles account balances, order management, price data, portfolio tracking, and fee estimation. Use when the user wants to buy/sell crypto, check balances, place orders, manage positions, or do anything on Coinbase."
+metadata:
+  emoji: "🪙"
+  requires:
+    env: ["COINBASE_API_KEY", "COINBASE_API_SECRET"]
+---
+
+# Coinbase Trading Executor
+
+You can execute real trades on Coinbase using the Advanced Trade API. This is real money — be precise, confirm with the user, and never skip risk checks.
+
+## CRITICAL: Always Read LEARNING.md First
+
+**Before ANY Coinbase action, read [LEARNING.md](LEARNING.md).** It contains API quirks you've discovered, order patterns that work, mistakes to avoid, and fee insights from real trades.
+
+## Authentication
+
+The user's Coinbase API credentials are available as environment variables:
+- `COINBASE_API_KEY` — format: `organizations/{org_id}/apiKeys/{key_id}`
+- `COINBASE_API_SECRET` — EC private key in PEM format
+
+These use **CDP (Coinbase Developer Platform) keys** with **ES256 JWT** authentication. The `coinbase-api` npm package handles JWT generation internally.
+
+## Setup
+
+Before first use, ensure the SDK is installed in the workspace:
+
+```bash
+npm list coinbase-api 2>/dev/null || npm install coinbase-api
+```
+
+## How to Execute Trades
+
+All Coinbase operations use TypeScript/JavaScript scripts via `execute_code` or shell commands. Use the `coinbase-api` package:
+
+```typescript
+import { CBAdvancedTradeClient } from 'coinbase-api';
+
+const client = new CBAdvancedTradeClient({
+  apiKey: process.env.COINBASE_API_KEY,
+  apiSecret: process.env.COINBASE_API_SECRET,
+});
+```
+
+## Execution Workflow
+
+```
+- [ ] Step 1: Read LEARNING.md
+- [ ] Step 2: Verify balances and account status
+- [ ] Step 3: Get current price and market data
+- [ ] Step 4: Preview the order (estimate fees/slippage)
+- [ ] Step 5: Execute the order
+- [ ] Step 6: Verify order fill and record result
+- [ ] Step 7: Update LEARNING.md
+```
+
+### Step 2: Check Balances
+
+```typescript
+const accounts = await client.getAccounts();
+for (const acct of accounts.accounts) {
+  if (parseFloat(acct.available_balance.value) > 0) {
+    console.log(`${acct.currency}: ${acct.available_balance.value}`);
+  }
+}
+```
+
+### Step 3: Get Price Data
+
+```typescript
+// Current price
+const product = await client.getProduct({ product_id: 'BTC-USD' });
+console.log(`Price: $${product.price}, 24h change: ${product.price_percentage_change_24h}%`);
+
+// Best bid/ask spread
+const spread = await client.getBestBidAsk({ product_ids: ['BTC-USD'] });
+
+// OHLCV candles (last 24h, 1-hour granularity)
+const candles = await client.getProductCandles({
+  product_id: 'BTC-USD',
+  start: String(Math.floor(Date.now() / 1000) - 86400),
+  end: String(Math.floor(Date.now() / 1000)),
+  granularity: 'ONE_HOUR',
+});
+```
+
+### Step 4: Preview Order
+
+**Always preview before executing.** This shows estimated fees and slippage:
+
+```typescript
+const preview = await client.previewOrder({
+  product_id: 'BTC-USD',
+  side: 'BUY',
+  order_configuration: {
+    market_market_ioc: { quote_size: '100.00' },
+  },
+});
+// Shows: quote_size, base_size, best_bid, best_ask, total_fees, slippage
+```
+
+### Step 5: Place Orders
+
+See [references/order-types.md](references/order-types.md) for all order types and configurations.
+
+**Market Buy** (spend $X of quote currency):
+```typescript
+const order = await client.submitOrder({
+  client_order_id: crypto.randomUUID(),
+  product_id: 'BTC-USD',
+  side: 'BUY',
+  order_configuration: {
+    market_market_ioc: { quote_size: '100.00' },  // spend $100
+  },
+});
+```
+
+**Market Sell** (sell X units of base asset):
+```typescript
+const order = await client.submitOrder({
+  client_order_id: crypto.randomUUID(),
+  product_id: 'BTC-USD',
+  side: 'SELL',
+  order_configuration: {
+    market_market_ioc: { base_size: '0.001' },  // sell 0.001 BTC
+  },
+});
+```
+
+**Limit Buy** (Good Till Cancel):
+```typescript
+const order = await client.submitOrder({
+  client_order_id: crypto.randomUUID(),
+  product_id: 'BTC-USD',
+  side: 'BUY',
+  order_configuration: {
+    limit_limit_gtc: {
+      base_size: '0.001',
+      limit_price: '95000.00',
+      post_only: false,
+    },
+  },
+});
+```
+
+### Step 6: Verify Order
+
+```typescript
+// Check response immediately
+if (order.success) {
+  const orderId = order.success_response.order_id;
+  // Get fill details
+  const status = await client.getOrder({ order_id: orderId });
+  console.log(`Status: ${status.status}, Filled: ${status.filled_size} @ ${status.average_filled_price}`);
+} else {
+  console.error(`Order failed: ${order.error_response.message}`);
+}
+```
+
+**IMPORTANT:** Coinbase returns HTTP 200 even on order failure. Always check `order.success === true`.
+
+### Step 7: Update LEARNING.md
+
+After every trade, record: asset, side, type, size, fill price, fees, outcome, and any API quirks encountered.
+
+## Order Management
+
+```typescript
+// List open orders
+const orders = await client.getOrders({ order_status: ['OPEN', 'PENDING'] });
+
+// Cancel specific orders
+const cancel = await client.cancelOrders({ order_ids: ['order-id-here'] });
+
+// Get fills (trade executions)
+const fills = await client.getFills({ order_id: 'order-id-here' });
+```
+
+## Portfolio & Fees
+
+```typescript
+// Portfolio breakdown
+const portfolios = await client.getPortfolios({});
+const breakdown = await client.getPortfolioBreakdown({ portfolio_id: portfolios.portfolios[0].uuid });
+
+// Fee tier info
+const fees = await client.getTransactionSummary({});
+// Shows: fee_tier, total_volume, maker_fee_rate, taker_fee_rate
+```
+
+## Critical Rules
+
+1. **ALWAYS preview orders before executing** — know the fees and slippage
+2. **All values are STRINGS** — `"100.00"` not `100`. The API rejects numbers.
+3. **client_order_id must be unique** — always use `crypto.randomUUID()`
+4. **Check `order.success`** — HTTP 200 doesn't mean order succeeded
+5. **Product ID format** — always `BASE-QUOTE` e.g. `BTC-USD`, `ETH-USD`, `SOL-USD`
+6. **Minimum order sizes vary** — check product details before ordering
+7. **Rate limits** — ~10 requests/second for private endpoints
+8. **Never place orders in a loop without delays** — respect rate limits
+9. **Log everything in LEARNING.md** — every trade, every error, every quirk
+
+## Reference Files
+
+- [references/order-types.md](references/order-types.md) — All order configurations with examples
+- [references/api-reference.md](references/api-reference.md) — Complete API endpoint list
+- [references/products.md](references/products.md) — Common trading pairs and their details
+
+## Self-Evolution
+
+You can modify any file in this skill:
+- Found an API quirk? Update LEARNING.md and references
+- Built a reusable script? Save it in `scripts/`
+- Discovered a better workflow? Update this SKILL.md
+- New order type pattern? Add to `references/order-types.md`

package/skills/coinbase/references/api-reference.md

@@ -0,0 +1,124 @@
+# Coinbase Advanced Trade API Reference
+
+> Agent-editable. Add notes and quirks as you discover them.
+> Last updated: Initial version
+
+## Base URL
+
+`https://api.coinbase.com/api/v3/brokerage/`
+
+## SDK Methods (coinbase-api package)
+
+### Accounts & Balances
+
+| Method | Description |
+|--------|-------------|
+| `client.getAccounts()` | List all accounts with balances |
+| `client.getAccount({ account_id })` | Get specific account |
+
+### Market Data
+
+| Method | Description |
+|--------|-------------|
+| `client.getProducts({})` | List all trading pairs |
+| `client.getProduct({ product_id })` | Get product details + current price |
+| `client.getProductCandles({ product_id, start, end, granularity })` | OHLCV candle data |
+| `client.getProductBook({ product_id, limit })` | Order book depth |
+| `client.getBestBidAsk({ product_ids: [...] })` | Best bid/ask spread |
+| `client.getMarketTrades({ product_id, limit })` | Recent market trades |
+
+### Orders
+
+| Method | Description |
+|--------|-------------|
+| `client.submitOrder({ ... })` | Place an order |
+| `client.previewOrder({ ... })` | Preview order (estimate fees/slippage) |
+| `client.getOrder({ order_id })` | Get order details |
+| `client.getOrders({ order_status, product_id, ... })` | List orders with filters |
+| `client.cancelOrders({ order_ids: [...] })` | Cancel one or more orders |
+| `client.getFills({ order_id, product_id, ... })` | Get trade fills |
+
+### Portfolios
+
+| Method | Description |
+|--------|-------------|
+| `client.getPortfolios({})` | List portfolios |
+| `client.getPortfolioBreakdown({ portfolio_id })` | Detailed breakdown with positions |
+
+### Fees
+
+| Method | Description |
+|--------|-------------|
+| `client.getTransactionSummary({})` | Fee tier, volume, maker/taker rates |
+
+## Candle Granularity Options
+
+| Value | Period |
+|-------|--------|
+| `ONE_MINUTE` | 1 min |
+| `FIVE_MINUTE` | 5 min |
+| `FIFTEEN_MINUTE` | 15 min |
+| `THIRTY_MINUTE` | 30 min |
+| `ONE_HOUR` | 1 hr |
+| `TWO_HOUR` | 2 hr |
+| `SIX_HOUR` | 6 hr |
+| `ONE_DAY` | 1 day |
+
+## Candle Timestamps
+
+- `start` and `end` are **Unix timestamps in seconds** (as strings)
+- Example: last 24 hours
+```typescript
+start: String(Math.floor(Date.now() / 1000) - 86400),
+end: String(Math.floor(Date.now() / 1000)),
+```
+
+## Rate Limits
+
+| Type | Limit |
+|------|-------|
+| Private endpoints | ~10 requests/second |
+| Private endpoints | ~5,000 requests/hour |
+| Public endpoints | ~10,000 requests/hour |
+
+Public endpoints have 1-second cache. Use WebSocket for real-time data.
+
+## Error Handling
+
+The API returns HTTP 200 for most responses, including failures. Always check:
+
+```typescript
+if (order.success) {
+  // order.success_response.order_id
+} else {
+  // order.error_response.error, order.error_response.message
+  // Common: INSUFFICIENT_FUND, INVALID_LIMIT_PRICE_POST_ONLY, UNKNOWN_FAILURE_REASON
+}
+```
+
+## Common Error Codes
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| `INSUFFICIENT_FUND` | Not enough balance | Check available balance first |
+| `INVALID_LIMIT_PRICE_POST_ONLY` | Post-only order would immediately fill | Adjust price or set `post_only: false` |
+| `UNKNOWN_FAILURE_REASON` | Generic failure | Check order params, product status |
+| `UNSUPPORTED_ORDER_CONFIGURATION` | Invalid order config | Check order type and required fields |
+| `INVALID_PRODUCT_ID` | Product doesn't exist | Verify product_id with `getProducts()` |
+
+## WebSocket Channels (Real-Time)
+
+| Channel | Auth | Description |
+|---------|------|-------------|
+| `ticker` | Public | Real-time price per trade |
+| `ticker_batch` | Public | Batched price updates |
+| `level2` | Public | Order book updates |
+| `market_trades` | Public | Trade executions |
+| `candles` | Public | OHLCV updates |
+| `status` | Public | Product status changes |
+| `user` | Private | Your order fills and updates |
+| `heartbeats` | Public | Connection keepalive |
+
+WebSocket endpoints:
+- Market data: `wss://advanced-trade-ws.coinbase.com`
+- User data: `wss://advanced-trade-ws-user.coinbase.com`

package/skills/coinbase/references/order-types.md

@@ -0,0 +1,150 @@
+# Coinbase Order Types — Complete Reference
+
+> Agent-editable. Update with patterns and quirks discovered from real trading.
+> Last updated: Initial version
+
+## Order Configuration Keys
+
+Every order uses `order_configuration` with exactly ONE of these keys:
+
+### Market Orders (Immediate Execution)
+
+**`market_market_ioc`** — Market Immediate-or-Cancel (most common)
+```typescript
+// Buy by dollar amount (quote currency)
+order_configuration: {
+  market_market_ioc: { quote_size: '100.00' }  // spend $100
+}
+
+// Sell by quantity (base currency)
+order_configuration: {
+  market_market_ioc: { base_size: '0.5' }  // sell 0.5 ETH
+}
+```
+- Use `quote_size` for BUY (how much USD to spend)
+- Use `base_size` for SELL (how many units to sell)
+- Can use `base_size` for BUY too (buy exact amount of asset)
+
+### Limit Orders
+
+**`limit_limit_gtc`** — Good Till Cancelled
+```typescript
+order_configuration: {
+  limit_limit_gtc: {
+    base_size: '0.001',
+    limit_price: '95000.00',
+    post_only: false,  // true = maker only (lower fees)
+  }
+}
+```
+
+**`limit_limit_gtd`** — Good Till Date (expires)
+```typescript
+order_configuration: {
+  limit_limit_gtd: {
+    base_size: '0.001',
+    limit_price: '95000.00',
+    end_time: '2026-03-01T00:00:00Z',  // RFC3339
+    post_only: false,
+  }
+}
+```
+
+**`limit_limit_fok`** — Fill or Kill (all or nothing)
+```typescript
+order_configuration: {
+  limit_limit_fok: {
+    base_size: '0.001',
+    limit_price: '95000.00',
+  }
+}
+```
+
+### Stop-Limit Orders
+
+**`stop_limit_stop_limit_gtc`** — Stop-Limit GTC
+```typescript
+// Stop-loss sell: triggers when price drops to stop_price
+order_configuration: {
+  stop_limit_stop_limit_gtc: {
+    base_size: '0.001',
+    limit_price: '93000.00',    // limit order price after trigger
+    stop_price: '94000.00',     // trigger price
+    stop_direction: 'STOP_DIRECTION_STOP_DOWN',  // triggers when price goes DOWN
+  }
+}
+
+// Stop-buy: triggers when price rises to stop_price
+order_configuration: {
+  stop_limit_stop_limit_gtc: {
+    base_size: '0.001',
+    limit_price: '101000.00',
+    stop_price: '100000.00',
+    stop_direction: 'STOP_DIRECTION_STOP_UP',
+  }
+}
+```
+
+**`stop_limit_stop_limit_gtd`** — Stop-Limit with expiry (same fields + `end_time`)
+
+### Bracket Orders (Entry + Take-Profit + Stop-Loss)
+
+**`trigger_bracket_gtc`** — Bracket GTC
+```typescript
+order_configuration: {
+  trigger_bracket_gtc: {
+    base_size: '0.001',
+    limit_price: '105000.00',        // take-profit price
+    stop_trigger_price: '93000.00',  // stop-loss trigger
+  }
+}
+```
+
+**`trigger_bracket_gtd`** — Bracket with expiry (same fields + `end_time`)
+
+### Smart Order Router
+
+**`sor_limit_ioc`** — SOR Limit IOC (routes across venues for best price)
+```typescript
+order_configuration: {
+  sor_limit_ioc: {
+    base_size: '0.001',
+    limit_price: '100000.00',
+  }
+}
+```
+
+## Stop Direction Values
+
+| Value | Meaning | Use Case |
+|-------|---------|----------|
+| `STOP_DIRECTION_STOP_DOWN` | Trigger when price drops below stop | Stop-loss for long positions |
+| `STOP_DIRECTION_STOP_UP` | Trigger when price rises above stop | Stop-loss for shorts, breakout buys |
+
+## Order Sides
+
+| Side | Meaning |
+|------|---------|
+| `BUY` | Buy base currency, spend quote currency |
+| `SELL` | Sell base currency, receive quote currency |
+
+## Order Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `PENDING` | Order received, not yet on book |
+| `OPEN` | Active on order book |
+| `FILLED` | Completely filled |
+| `CANCELLED` | Cancelled by user or system |
+| `EXPIRED` | GTD order expired |
+| `FAILED` | Order rejected |
+| `UNKNOWN_ORDER_STATUS` | Unknown |
+
+## Key Gotchas
+
+1. **All numeric values must be strings**: `"100.00"` not `100`
+2. **Market buys use `quote_size`** (dollar amount), **market sells use `base_size`** (quantity)
+3. **HTTP 200 doesn't mean success**: Always check `response.success === true`
+4. **Duplicate `client_order_id`**: Returns existing order, doesn't create new one
+5. **`post_only: true`**: Ensures you're a maker (lower fees) but order may be rejected if it would immediately fill
+6. **Minimum order sizes**: Vary by product. Check `base_min_size` in product details.

package/skills/coinbase/references/products.md

@@ -0,0 +1,93 @@
+# Coinbase Trading Products
+
+> Agent-editable. Add notes about products as you trade them.
+> Last updated: Initial version
+
+## Product ID Format
+
+Always `{BASE}-{QUOTE}`, e.g. `BTC-USD`, `ETH-USD`
+
+## Common Trading Pairs
+
+### Major Crypto (High Liquidity)
+
+| Product ID | Base | Quote | Notes |
+|-----------|------|-------|-------|
+| `BTC-USD` | Bitcoin | USD | Most liquid, tightest spreads |
+| `ETH-USD` | Ethereum | USD | Second most liquid |
+| `SOL-USD` | Solana | USD | High volatility |
+| `DOGE-USD` | Dogecoin | USD | Meme coin, volatile |
+| `XRP-USD` | Ripple | USD | |
+| `ADA-USD` | Cardano | USD | |
+| `AVAX-USD` | Avalanche | USD | |
+| `LINK-USD` | Chainlink | USD | |
+| `DOT-USD` | Polkadot | USD | |
+| `MATIC-USD` | Polygon | USD | |
+| `UNI-USD` | Uniswap | USD | |
+| `LTC-USD` | Litecoin | USD | |
+
+### Stablecoins
+
+| Product ID | Base | Quote | Notes |
+|-----------|------|-------|-------|
+| `USDT-USD` | Tether | USD | |
+| `BTC-USDT` | Bitcoin | Tether | |
+| `ETH-USDT` | Ethereum | Tether | |
+
+### Crypto-to-Crypto
+
+| Product ID | Base | Quote | Notes |
+|-----------|------|-------|-------|
+| `ETH-BTC` | Ethereum | Bitcoin | ETH/BTC ratio trading |
+| `SOL-BTC` | Solana | Bitcoin | |
+
+## Discovering Products
+
+Always verify product availability before trading:
+
+```typescript
+// List all products
+const products = await client.getProducts({});
+
+// Filter for USD pairs
+const usdPairs = products.products.filter(p => p.quote_currency_id === 'USD');
+
+// Get specific product details
+const btc = await client.getProduct({ product_id: 'BTC-USD' });
+// Returns: price, volume_24h, price_percentage_change_24h,
+//          base_min_size, base_max_size, quote_min_size, quote_increment, etc.
+```
+
+## Key Product Fields
+
+| Field | Description | Important For |
+|-------|-------------|---------------|
+| `price` | Current price | All orders |
+| `base_min_size` | Minimum base order size | Validating order size |
+| `base_max_size` | Maximum base order size | Validating order size |
+| `quote_min_size` | Minimum quote order size | Market buy minimum |
+| `quote_increment` | Price precision | Formatting limit prices |
+| `base_increment` | Size precision | Formatting order sizes |
+| `status` | Product trading status | Check before ordering |
+| `trading_disabled` | Whether trading is halted | Check before ordering |
+| `volume_24h` | 24-hour trading volume | Liquidity assessment |
+
+## Pre-Trade Checklist
+
+Before placing any order on a product:
+
+1. **Verify product exists**: `getProduct({ product_id })`
+2. **Check `trading_disabled !== true`**
+3. **Check `status === 'online'`**
+4. **Verify order size >= `base_min_size`** (for base_size orders)
+5. **Verify order size >= `quote_min_size`** (for quote_size orders)
+6. **Round to correct precision** using `base_increment` / `quote_increment`
+
+## Product Notes from Trading
+
+*(Add observations as you trade different pairs)*
+<!--
+- [DATE] PRODUCT: observation about spreads, liquidity, or behavior
+Example:
+- [2026-02-14] BTC-USD: Spreads widen significantly during weekends. Avoid large market orders Sat/Sun.
+-->