Merge pull request #7 from BitMEX-private/fix/skills-accuracy-review

fix: address skill accuracy issues from Kris' review

Author: Quentin-M

skills/bitmex-alert-patterns/SKILL.md

@@ -101,10 +101,12 @@ bitmex ws --auth wallet margin -o json 2>/dev/null | \
   '
 ```
 
-## Position PnL Alert
+## Position Unrealised PnL Alert
+
+> **Note:** This monitors `unrealisedPnl` only — mark-to-market movement. Funding costs accumulate separately every 8 hours and are not reflected until charged. For a full position P&L view, also monitor the funding rate.
 
 ```bash
-PNL_THRESHOLD=-50000  # in satoshis
+PNL_THRESHOLD=-50000  # in satoshis (XBt instruments); use appropriate units for USDT instruments
 bitmex ws --auth position -o json 2>/dev/null | \
   jq -c --argjson t "$PNL_THRESHOLD" '
     .data[]? | select(.unrealisedPnl != null and .unrealisedPnl < $t) |

skills/bitmex-basis-trading/SKILL.md

@@ -130,3 +130,6 @@ echo "scale=4; $BASIS / $DAYS * 365" | bc -l
 - Margin risk: each leg consumes margin independently
 - Roll risk: if the future expires before exit, roll the position
 - Basis can widen before converging — maintain margin buffer
+- Funding risk: the perpetual leg accrues funding every 8 hours; in positive-funding environments the long perp leg pays, eroding carry — model funding into your breakeven calculation
+- Instrument scope: this guide uses inverse pairs (XBTUSD/XBTM25); linear-linear pairs (e.g. XBTUSDT/XBTUSDTM26) work similarly provided lot sizes and multipliers match, but P&L is denominated in USDT rather than XBT
+- Spot-future basis: the classic version uses spot BTC (off-exchange) vs a fixed-date future rather than a perpetual; this eliminates funding risk but requires managing spot custody separately and is not covered here

skills/bitmex-dca-strategy/SKILL.md

@@ -86,17 +86,21 @@ done
 
 ## Track Average Entry Price
 
+> For **inverse** instruments (e.g. XBTUSD), the correct average entry is a cost-weighted harmonic mean: `total_qty / sum(qty/price)`. Standard VWAP (`sum(qty*price) / total_qty`) overstates the average slightly and diverges from the exchange-reported figure.
+> For **linear** instruments (e.g. XBTUSDT), standard VWAP is correct.
+
 ```bash
+# Inverse instruments (XBTUSD, etc.)
 bitmex execution trade-history --symbol XBTUSD --reverse --count 100 -o json 2>/dev/null | \
   jq '
     [.[] | select(.side == "Buy" and .execType == "Trade")] |
     {
       count: length,
       total_qty: (map(.lastQty) | add),
       avg_entry: (
-        (map(.lastQty * .lastPx) | add) /
-        (map(.lastQty) | add)
-        | round / 100
+        (map(.lastQty) | add) /
+        (map(.lastQty / .lastPx) | add)
+        | (. * 100 | round) / 100
       )
     }
   '

skills/bitmex-fee-optimization/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 # bitmex-fee-optimization
 
-BitMEX charges taker fees and pays maker rebates. The difference is meaningful at scale. Always default to limit orders with `ParticipateDoNotInitiate`.
+BitMEX charges taker fees and pays maker rebates. The difference is meaningful at scale. Default to limit orders with `ParticipateDoNotInitiate` for passive entries. For aggressive fills where immediate execution matters more than fee savings, use a limit order at the ask/bid price without this flag — see *Avoid Market Orders* below.
 
 ## Fee Structure
 

skills/bitmex-liquidation-guard/SKILL.md

@@ -37,7 +37,7 @@ bitmex position list -o json 2>/dev/null | jq '
     symbol,
     markPrice,
     liquidationPrice,
-    buffer_pct: (((.markPrice - .liquidationPrice) / .markPrice * 100) | round / 100)
+    buffer_pct: (((.markPrice - .liquidationPrice) / .markPrice * 100) | fabs | (. * 100 | round) / 100)
   }]
 '
 ```

skills/bitmex-order-types/SKILL.md

@@ -122,6 +122,18 @@ bitmex order buy XBTUSD 100 --price 50000 --order-type Limit \
   --tif ImmediateOrCancel --validate -o json 2>/dev/null
 ```
 
+## Contingency / Linked Orders
+
+BitMEX supports paired order logic via `contingencyType` and a shared `clOrdLinkID`. The CLI does not currently expose these as flags; use the REST API for these order types.
+
+| Type | Behavior |
+|---|---|
+| `OneCancelsTheOther` | OCO: when one order fills or triggers, the linked order is cancelled |
+| `OneTriggersTheOther` | OTO: when the first order fills, the linked order becomes active |
+| `OneUpdatesTheOtherAbsolute` | OUO: amending one order propagates the change to the linked order |
+
+Typical use: a stop-loss + take-profit pair as OCO so that one filling automatically cancels the other. These must currently be submitted directly via the BitMEX REST API with matching `clOrdLinkID` values.
+
 ## Amending Orders
 
 Change price or qty on an open order without cancelling and re-placing:

skills/bitmex-position-risk/SKILL.md

@@ -117,8 +117,8 @@ bitmex position list --symbol XBTUSD -o json 2>/dev/null | jq '
   if .markPrice == null or .liquidationPrice == null then
     {symbol, markPrice, liquidationPrice, gap_pct: null}
   else
-    ((.markPrice - .liquidationPrice) / .markPrice * 100) as $pct |
-    {symbol, markPrice, liquidationPrice, gap_pct: ($pct | round / 100)}
+    ((.markPrice - .liquidationPrice) / .markPrice * 100 | fabs) as $pct |
+    {symbol, markPrice, liquidationPrice, gap_pct: (($pct * 100 | round) / 100)}
   end
 '
 ```

skills/bitmex-recipe-basis-trade-entry/SKILL.md

@@ -82,3 +82,5 @@ Exit both legs when basis narrows to under 0.1% or at futures expiry.
 
 - Size both legs equally in USD notional to maintain delta neutrality.
 - Account for maker/taker fees on both entry and exit when calculating the net carry.
+- The perpetual leg exposes you to funding rate volatility; net carry = basis − cumulative funding over hold period. Check `bitmex market funding --symbol XBTUSD` before entering.
+- For carry estimates, exit logic, and roll procedures, see the `bitmex-basis-trading` skill.

skills/bitmex-recipe-daily-pnl-report/SKILL.md

@@ -27,14 +27,17 @@ bitmex execution trade-history --reverse --count 500 -o json \
   > /tmp/trades_today.json
 ```
 
-### 2. Sum realised P&L (in satoshis)
+### 2. Sum realised P&L by currency
+
+> P&L units depend on the instrument's settlement currency. XBt-settled instruments (e.g. XBTUSD) report in satoshis; divide by 1e8 for XBT. USDT-settled instruments (e.g. XBTUSDT) report in USDT units. Always group by `homeNotional` currency rather than summing across all symbols.
 
 ```bash
-jq '[.[].realisedPnl] | add // 0' /tmp/trades_today.json
+jq 'group_by(.currency) | map({
+  currency: .[0].currency,
+  realisedPnl: ([.[].realisedPnl] | add // 0)
+})' /tmp/trades_today.json
 ```
 
-Convert to XBT: divide by `100000000`.
-
 ### 3. Total fees paid today
 
 ```bash
@@ -76,4 +79,4 @@ bitmex position list -o json \
 ## Tips
 
 - Automate with a cron at 23:55 UTC and append to a CSV for trend analysis.
-- BitMEX P&L is denominated in XBt (satoshis). Always divide by 1e8 before displaying in XBT.
+- XBt-settled instruments (inverse, e.g. XBTUSD) report P&L in satoshis; divide by 1e8 for XBT. USDT-settled instruments report in USDT. Never sum across currencies.

skills/bitmex-recipe-drawdown-circuit-breaker/SKILL.md

@@ -5,7 +5,7 @@ description: Halt trading when portfolio drawdown exceeds threshold.
 
 # Drawdown Circuit Breaker
 
-Monitor wallet balance against a high-water mark and automatically flatten all positions when drawdown exceeds your configured threshold.
+Monitor margin balance against a high-water mark and automatically flatten all positions when drawdown exceeds your configured threshold.
 
 ## Prerequisites
 
@@ -17,10 +17,10 @@ Monitor wallet balance against a high-water mark and automatically flatten all p
 
 ### 1. Record the high-water mark
 
-Capture wallet balance at the start of each session or daily:
+Capture margin balance at the start of each session or daily. `marginBalance` (not `walletBalance`) is used here because it includes `unrealisedPnl`, so a large adverse price move will trigger the breaker even before positions are closed.
 
 ```bash
-HIGH_WATER=$(bitmex wallet balance -o json | jq '.amount')
+HIGH_WATER=$(bitmex account margin --currency XBt -o json | jq '.marginBalance')
 echo "$HIGH_WATER" > /tmp/bitmex_hwm.txt
 ```
 
@@ -30,12 +30,14 @@ On subsequent checks, load it:
 HIGH_WATER=$(cat /tmp/bitmex_hwm.txt)
 ```
 
-### 2. Get current wallet balance
+### 2. Get current margin balance
 
 ```bash
-CURRENT=$(bitmex wallet balance -o json | jq '.amount')
+CURRENT=$(bitmex account margin --currency XBt -o json | jq '.marginBalance')
 ```
 
+> **Note:** This circuit breaker covers XBt-denominated positions only. USDT positions require a separate check using `--currency USDt`.
+
 ### 3. Calculate drawdown percentage
 
 ```bash