@farazirfan/costar-server-executor 1.7.28 → 1.7.30

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

@@ -0,0 +1,201 @@
+# OKX API Reference
+
+> Agent-editable. Add notes and quirks as you discover them.
+> Last updated: Initial version
+
+## SDK: okx-api (npm)
+
+```bash
+npm install okx-api
+```
+
+Three client classes:
+- `RestClient` — REST API calls
+- `WebsocketClient` — Event-driven streaming (tickers, candles, book, orders, positions)
+- `WebsocketAPIClient` — Promise-based order placement over WebSocket
+
+## REST Client — Key Methods
+
+### Account & Balance
+
+| Method | Description |
+|--------|-------------|
+| `client.getBalance()` | All currency balances (available, frozen, equity) |
+| `client.getPositions()` | Open positions (margin/futures) |
+| `client.getPositionsHistory()` | Closed positions history |
+| `client.getAccountPositionRisk()` | Position risk details |
+| `client.getAccountConfiguration()` | Account mode, level, position mode |
+| `client.setLeverage(params)` | Set leverage for an instrument |
+| `client.getLeverage(params)` | Get current leverage |
+| `client.getMaxBuySellAmount(params)` | Max buy/sell for an instrument |
+| `client.getMaxAvailableTradableAmount(params)` | Max available to trade |
+| `client.getMaxWithdrawals()` | Max withdrawal amounts |
+| `client.getFeeRates({ instType })` | Fee tier — maker/taker rates |
+| `client.getAccountRateLimit()` | Current rate limit usage |
+
+### Market Data
+
+| Method | Description |
+|--------|-------------|
+| `client.getTicker({ instId })` | Current price, volume, bid/ask |
+| `client.getTickers({ instType })` | All tickers for an instrument type |
+| `client.getOrderBook({ instId, sz })` | Order book depth (sz = levels) |
+| `client.getCandles({ instId, bar, limit })` | OHLCV candlestick data |
+| `client.getCandlesHistory({ instId, bar, limit })` | Historical candles |
+| `client.getTrades({ instId, limit })` | Recent trades |
+| `client.getTradesHistory({ instId })` | Historical trades |
+| `client.get24hrTotalVolume()` | Platform-wide 24h volume |
+
+### Orders
+
+| Method | Description |
+|--------|-------------|
+| `client.submitOrder(params)` | Place a single order |
+| `client.submitMultipleOrders(params[])` | Place up to 20 orders at once |
+| `client.cancelOrder(params)` | Cancel a single order |
+| `client.cancelMultipleOrders(params[])` | Cancel multiple orders |
+| `client.amendOrder(params)` | Modify an existing order |
+| `client.amendMultipleOrders(params[])` | Modify multiple orders |
+| `client.closePositions(params)` | Close an open position |
+| `client.getOrderDetails({ instId, ordId })` | Get single order details |
+| `client.getOrderList({ instType })` | Open/pending orders |
+| `client.getOrderHistory({ instType })` | 7-day order history |
+| `client.getOrderHistoryArchive({ instType })` | 3-month history |
+| `client.getFills({ instType })` | Recent trade fills |
+| `client.getFillsHistory({ instType })` | Historical fills |
+
+### Algo Orders
+
+| Method | Description |
+|--------|-------------|
+| `client.placeAlgoOrder(params)` | Place TP/SL, trailing stop, trigger, iceberg, TWAP |
+| `client.cancelAlgoOrder(params)` | Cancel algo order |
+| `client.amendAlgoOrder(params)` | Modify algo order |
+| `client.getAlgoOrderDetails(params)` | Algo order details |
+| `client.getAlgoOrderList(params)` | Active algo orders |
+| `client.getAlgoOrderHistory(params)` | Algo order history |
+
+### Public / Instrument Data
+
+| Method | Description |
+|--------|-------------|
+| `client.getInstruments({ instType })` | List all instruments of a type |
+| `client.getFundingRate({ instId })` | Current funding rate (perpetuals) |
+| `client.getFundingRateHistory({ instId })` | Historical funding rates |
+| `client.getMarkPrice({ instType })` | Mark prices |
+| `client.getOpenInterest({ instType })` | Open interest data |
+| `client.getExchangeRate()` | USD/CNY exchange rate |
+| `client.getIndexTickers({ instId })` | Index tickers |
+
+### Asset Management
+
+| Method | Description |
+|--------|-------------|
+| `client.getCurrencies()` | All supported currencies |
+| `client.fundsTransfer(params)` | Transfer between accounts |
+| `client.getDepositHistory()` | Deposit history |
+| `client.getWithdrawalHistory()` | Withdrawal history |
+
+## Candlestick Bar Values
+
+| Value | Period |
+|-------|--------|
+| `1m` | 1 minute |
+| `3m` | 3 minutes |
+| `5m` | 5 minutes |
+| `15m` | 15 minutes |
+| `30m` | 30 minutes |
+| `1H` | 1 hour |
+| `2H` | 2 hours |
+| `4H` | 4 hours |
+| `6H` | 6 hours |
+| `12H` | 12 hours |
+| `1D` | 1 day |
+| `1W` | 1 week |
+| `1M` | 1 month |
+
+## Response Format
+
+OKX REST API wraps all responses:
+```json
+{
+  "code": "0",
+  "msg": "",
+  "data": [...]
+}
+```
+
+The `okx-api` package unwraps this — methods return the `data` array directly. On failure, it throws the full error response.
+
+For order submission, check `response[0].sCode`:
+```typescript
+const result = await client.submitOrder({...});
+if (result[0].sCode === '0') {
+  // Success — result[0].ordId has the order ID
+} else {
+  // Failed — result[0].sCode is error code, result[0].sMsg is message
+}
+```
+
+## Common Error Codes
+
+| sCode | Meaning | Fix |
+|-------|---------|-----|
+| `0` | Success | — |
+| `51000` | Parameter error | Check required params |
+| `51001` | Instrument ID doesn't exist | Verify instId |
+| `51004` | Insufficient balance | Check available balance |
+| `51008` | Order placement not allowed | Check account mode/permissions |
+| `51010` | Order size below minimum | Check instrument minimum |
+| `51020` | Order count exceeds limit | Reduce concurrent orders |
+| `51100` | Margin account issue | Check margin settings |
+| `51400` | Position doesn't exist | Verify position before closing |
+
+## Rate Limits
+
+| Category | Limit |
+|----------|-------|
+| Order placement | 60 requests/2s per instrument |
+| Batch orders | 300 orders/2s |
+| Order cancel | 60 requests/2s per instrument |
+| Market data | 20 requests/2s |
+| Account data | 10 requests/2s |
+
+Rate limits are per-instrument for trading endpoints. Use `getAccountRateLimit()` to check current usage.
+
+## WebSocket Channels
+
+### Public (no auth)
+
+| Channel | Description |
+|---------|-------------|
+| `tickers` | Real-time price/volume |
+| `candle1m`, `candle5m`, `candle1H`, etc. | Candlestick updates |
+| `books`, `books5`, `books50-l2` | Order book depth |
+| `trades` | Real-time trades |
+| `funding-rate` | Funding rate updates |
+| `mark-price` | Mark price updates |
+| `open-interest` | Open interest |
+| `instruments` | Instrument changes |
+| `liquidation-orders` | Liquidation events |
+
+### Private (auth required)
+
+| Channel | Description |
+|---------|-------------|
+| `account` | Balance updates |
+| `positions` | Position changes |
+| `balance_and_position` | Combined balance + position |
+| `orders` | Order status changes |
+| `orders-algo` | Algo order updates |
+| `liquidation-warning` | Liquidation warnings |
+
+## Multi-Region Support
+
+```typescript
+// Global (default)
+const client = new RestClient({ apiKey, apiSecret, apiPass });
+
+// European Economic Area
+const client = new RestClient({ apiKey, apiSecret, apiPass, market: 'EEA' });
+```

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

@@ -0,0 +1,251 @@
+# OKX Order Types — Complete Reference
+
+> Agent-editable. Update with patterns and quirks discovered from real trading.
+> Last updated: Initial version
+
+## Core Order Parameters
+
+Every order requires these fields:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `instId` | string | Instrument ID (e.g., `'BTC-USDT'`) |
+| `tdMode` | string | Trade mode: `'cash'`, `'cross'`, `'isolated'` |
+| `side` | string | `'buy'` or `'sell'` |
+| `ordType` | string | Order type (see below) |
+| `sz` | string | Size/quantity |
+
+## Trade Modes
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `cash` | Spot trading, no leverage | Simple buy/sell |
+| `cross` | Cross margin — all balance as collateral | Futures, margin trading |
+| `isolated` | Isolated margin — set per position | Risk-limited margin positions |
+
+## Order Types
+
+### Market Orders
+
+```typescript
+// Market buy — spend 100 USDT
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'market',
+  sz: '100',
+  tgtCcy: 'quote_ccy',  // sz is in USDT
+});
+
+// Market buy — buy exactly 0.001 BTC
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'market',
+  sz: '0.001',
+  tgtCcy: 'base_ccy',  // sz is in BTC
+});
+
+// Market sell — sell 0.001 BTC
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'sell',
+  ordType: 'market',
+  sz: '0.001',
+});
+```
+
+- `tgtCcy: 'quote_ccy'` — size is in quote currency (USDT). Use for "spend X dollars" buys.
+- `tgtCcy: 'base_ccy'` — size is in base currency (BTC). Use for exact quantity.
+- For sells, `tgtCcy` defaults to `base_ccy`.
+
+### Limit Orders
+
+```typescript
+// Limit buy
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'limit',
+  sz: '0.001',
+  px: '95000',
+});
+
+// Post-only limit (maker only — lower fees)
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'post_only',
+  sz: '0.001',
+  px: '95000',
+});
+```
+
+### Fill-or-Kill / Immediate-or-Cancel
+
+```typescript
+// FOK — fill entire order or cancel
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'fok',
+  sz: '0.001',
+  px: '100000',
+});
+
+// IOC — fill what you can, cancel the rest
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'ioc',
+  sz: '0.001',
+  px: '100000',
+});
+
+// Optimal limit IOC — best available price
+await client.submitOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'optimal_limit_ioc',
+  sz: '0.001',
+});
+```
+
+## Algo Orders (TP/SL, Trailing Stop, Trigger)
+
+Algo orders use `placeAlgoOrder()` instead of `submitOrder()`.
+
+### Take-Profit / Stop-Loss (OCO)
+
+```typescript
+// TP at 105k, SL at 93k (market execution on trigger)
+await client.placeAlgoOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'sell',
+  ordType: 'oco',
+  sz: '0.001',
+  tpTriggerPx: '105000',
+  tpOrdPx: '-1',          // -1 = market price at trigger
+  slTriggerPx: '93000',
+  slOrdPx: '-1',
+});
+```
+
+### Take-Profit Only
+
+```typescript
+await client.placeAlgoOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'sell',
+  ordType: 'conditional',
+  sz: '0.001',
+  tpTriggerPx: '105000',
+  tpOrdPx: '-1',
+});
+```
+
+### Stop-Loss Only
+
+```typescript
+await client.placeAlgoOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'sell',
+  ordType: 'conditional',
+  sz: '0.001',
+  slTriggerPx: '93000',
+  slOrdPx: '-1',
+});
+```
+
+### Trigger Order (Stop Order)
+
+```typescript
+await client.placeAlgoOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'buy',
+  ordType: 'trigger',
+  sz: '0.001',
+  triggerPx: '100000',
+  orderPx: '-1',           // -1 = market, or set limit price
+  triggerPxType: 'last',    // 'last', 'index', or 'mark'
+});
+```
+
+### Trailing Stop
+
+```typescript
+await client.placeAlgoOrder({
+  instId: 'BTC-USDT',
+  tdMode: 'cash',
+  side: 'sell',
+  ordType: 'move_order_stop',
+  sz: '0.001',
+  callbackRatio: '0.05',   // 5% trailing distance
+  // or callbackSpread: '500' for fixed $ distance
+  activePx: '100000',      // activation price (optional)
+});
+```
+
+## Order States
+
+| State | Meaning |
+|-------|---------|
+| `live` | Active on order book |
+| `partially_filled` | Partially executed |
+| `filled` | Completely executed |
+| `canceled` | Cancelled |
+| `mmp_canceled` | Market maker protection cancelled |
+
+## Response Handling
+
+```typescript
+const result = await client.submitOrder({...});
+
+// result is an array — check first element
+if (result[0].sCode === '0') {
+  console.log(`Order placed: ${result[0].ordId}`);
+
+  // Get full order details
+  const details = await client.getOrderDetails({
+    instId: 'BTC-USDT',
+    ordId: result[0].ordId,
+  });
+  console.log(`State: ${details[0].state}, Filled: ${details[0].fillSz} @ ${details[0].avgPx}`);
+} else {
+  console.error(`Failed: [${result[0].sCode}] ${result[0].sMsg}`);
+}
+```
+
+## Batch Orders (Up to 20)
+
+```typescript
+const results = await client.submitMultipleOrders([
+  { instId: 'BTC-USDT', tdMode: 'cash', side: 'buy', ordType: 'limit', sz: '0.001', px: '94000' },
+  { instId: 'BTC-USDT', tdMode: 'cash', side: 'buy', ordType: 'limit', sz: '0.001', px: '93000' },
+  { instId: 'ETH-USDT', tdMode: 'cash', side: 'buy', ordType: 'limit', sz: '0.01', px: '3000' },
+]);
+// Each result[i] has its own sCode/sMsg
+```
+
+## Key Gotchas
+
+1. **All values are strings**: `'100'` not `100`
+2. **`tgtCcy` matters for market buys**: `'quote_ccy'` = spend X USDT, `'base_ccy'` = buy X BTC
+3. **Check `sCode === '0'`**: Non-zero means failure, even if no exception thrown
+4. **`tdMode` is always required**: `'cash'` for spot, `'cross'`/`'isolated'` for margin
+5. **OKX uses USDT pairs**: `BTC-USDT` not `BTC-USD`
+6. **Algo orders use `placeAlgoOrder()`**: NOT `submitOrder()`
+7. **`-1` as price**: Means market execution for algo order trigger prices
+8. **Batch limit**: Up to 20 orders per batch request

package/skills/okx/references/products.md

@@ -0,0 +1,128 @@
+# OKX Trading Products
+
+> Agent-editable. Add notes about products as you trade them.
+> Last updated: Initial version
+
+## Instrument ID Format
+
+- Spot: `{BASE}-{QUOTE}` → `BTC-USDT`, `ETH-USDT`
+- Perpetual swap: `{BASE}-{QUOTE}-SWAP` → `BTC-USDT-SWAP`
+- Futures: `{BASE}-{QUOTE}-{EXPIRY}` → `BTC-USDT-250328`
+- Options: `{BASE}-{QUOTE}-{EXPIRY}-{STRIKE}-{C/P}` → `BTC-USD-250328-100000-C`
+
+## Instrument Types
+
+| instType | Description |
+|----------|-------------|
+| `SPOT` | Spot trading |
+| `MARGIN` | Margin trading |
+| `SWAP` | Perpetual swaps |
+| `FUTURES` | Delivery futures |
+| `OPTION` | Options |
+
+## Common Spot Pairs (High Liquidity)
+
+| Instrument ID | Base | Quote | Notes |
+|---------------|------|-------|-------|
+| `BTC-USDT` | Bitcoin | USDT | Most liquid on OKX |
+| `ETH-USDT` | Ethereum | USDT | Second most liquid |
+| `SOL-USDT` | Solana | USDT | High volatility |
+| `DOGE-USDT` | Dogecoin | USDT | |
+| `XRP-USDT` | Ripple | USDT | |
+| `ADA-USDT` | Cardano | USDT | |
+| `AVAX-USDT` | Avalanche | USDT | |
+| `LINK-USDT` | Chainlink | USDT | |
+| `DOT-USDT` | Polkadot | USDT | |
+| `MATIC-USDT` | Polygon | USDT | |
+| `UNI-USDT` | Uniswap | USDT | |
+| `LTC-USDT` | Litecoin | USDT | |
+| `OP-USDT` | Optimism | USDT | |
+| `ARB-USDT` | Arbitrum | USDT | |
+| `PEPE-USDT` | Pepe | USDT | Meme coin |
+| `WIF-USDT` | dogwifhat | USDT | Meme coin |
+
+### BTC Pairs
+
+| Instrument ID | Notes |
+|---------------|-------|
+| `ETH-BTC` | ETH/BTC ratio |
+| `SOL-BTC` | SOL/BTC ratio |
+
+### USDC Pairs
+
+| Instrument ID | Notes |
+|---------------|-------|
+| `BTC-USDC` | BTC against USDC |
+| `ETH-USDC` | ETH against USDC |
+
+## Common Perpetual Swaps
+
+| Instrument ID | Notes |
+|---------------|-------|
+| `BTC-USDT-SWAP` | BTC perpetual (USDT settled) |
+| `ETH-USDT-SWAP` | ETH perpetual (USDT settled) |
+| `SOL-USDT-SWAP` | SOL perpetual |
+| `BTC-USD-SWAP` | BTC perpetual (coin-margined) |
+
+## Discovering Instruments
+
+Always verify instrument availability before trading:
+
+```typescript
+// List all spot instruments
+const instruments = await client.getInstruments({ instType: 'SPOT' });
+
+// Filter for USDT pairs
+const usdtPairs = instruments.filter(i => i.quoteCcy === 'USDT' && i.state === 'live');
+
+// Get specific instrument details
+const btcUsdt = instruments.find(i => i.instId === 'BTC-USDT');
+// Returns: lotSz, minSz, tickSz, state, etc.
+```
+
+## Key Instrument Fields
+
+| Field | Description | Important For |
+|-------|-------------|---------------|
+| `instId` | Instrument ID | Order placement |
+| `minSz` | Minimum order size | Validating order size |
+| `lotSz` | Size increment / lot size | Rounding order size |
+| `tickSz` | Price tick size | Rounding limit prices |
+| `state` | `live`, `suspend`, `preopen` | Check before ordering |
+| `quoteCcy` | Quote currency | Identifying pair type |
+| `baseCcy` | Base currency | Identifying pair type |
+| `ctVal` | Contract value (derivatives) | Calculating position size |
+| `lever` | Max leverage | Margin trading limits |
+
+## Pre-Trade Checklist
+
+Before placing any order on an instrument:
+
+1. **Verify instrument exists**: `getInstruments({ instType: 'SPOT' })` and find it
+2. **Check `state === 'live'`** — suspended instruments can't be traded
+3. **Verify order size >= `minSz`**
+4. **Round size to `lotSz` precision** — OKX rejects orders with wrong precision
+5. **Round price to `tickSz` precision** — same for limit prices
+6. **For perpetuals**: check funding rate and open interest before entry
+
+## OKX vs Coinbase — Key Differences
+
+| Aspect | OKX | Coinbase |
+|--------|-----|----------|
+| Quote currency | USDT (mostly) | USD |
+| Instrument format | `BTC-USDT` | `BTC-USD` |
+| Perpetuals | Yes (`BTC-USDT-SWAP`) | No |
+| Options | Yes | No |
+| Margin trading | Yes (cross/isolated) | Limited |
+| Fees | Lower (maker ~0.08%, taker ~0.1%) | Higher (maker ~0.4%, taker ~0.6%) |
+| Algo orders | TP/SL, trailing, trigger, iceberg, TWAP | Stop-limit, bracket |
+| Batch orders | Up to 20 | No |
+
+## Product Notes from Trading
+
+*(Add observations as you trade different pairs)*
+<!--
+- [DATE] INSTRUMENT: observation about spreads, liquidity, or behavior
+Example:
+- [2026-02-18] BTC-USDT: Excellent liquidity, tight spreads even during high vol.
+-->