Merge pull request #5 from BitMEX-private/docs/agent-discoverability

install, onboarding, and skills safety improvements

Author: byshing

README.md

@@ -42,8 +42,13 @@ Ask me to choose:
 ## Verify
 Run: bitmex account me -o json
 
+## MCP (optional)
+Ask me if I want to set up the built-in MCP server (`bitmex mcp`), which
+lets you (the AI agent) call bitmex commands directly as tools without subprocess wrappers
+— smoother integration for agents that support MCP.
+
 ## What's Next
-Read the skills in the skills/ folder and ask me what I want to do. Offer these:
+Use the bitmex-* skills available to you and ask me what I want to do. Offer these:
 - Morning market brief (prices, funding rates, positions)
 - Start a DCA bot (dollar-cost average into a position)
 - Launch a grid trading bot (buy dips, sell rallies automatically)
@@ -70,7 +75,7 @@ And suggest starting with --testnet to practice safely before using real funds.
 ### Install script (recommended)
 
 ```bash
-tmpfile="$(mktemp)" && curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh -o "$tmpfile" && sh "$tmpfile"
+curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh | sh
 ```
 
 Downloads a pre-built binary for your platform (macOS/Linux, x86_64/arm64), verifies the SHA256 checksum, and installs to `~/.local/bin`. No Rust or build tools needed. No `sudo` required. Requires `curl`, `tar`, and `sha256sum` (or `shasum`). Override the install location with `BITMEX_INSTALL_DIR`.
@@ -103,9 +108,8 @@ bitmex market orderbook XBTUSD --depth 10 -o json
 bitmex market trades --symbol XBTUSD --count 20 -o json
 bitmex market funding --symbol XBTUSD -o json
 
-# Set up credentials
-export BITMEX_API_KEY="your-key"
-export BITMEX_API_SECRET="your-secret"
+# Set up credentials (stored securely in OS keychain)
+bitmex auth add
 
 # Account data
 bitmex account me -o json

skills/bitmex-autonomy-levels/SKILL.md

@@ -27,7 +27,7 @@ bitmex market funding --symbol XBTUSD -o json 2>/dev/null
 # Account state — auth required, read-only
 bitmex account me -o json 2>/dev/null
 bitmex position list -o json 2>/dev/null
-bitmex order list -o json 2>/dev/null
+bitmex order list --reverse -o json 2>/dev/null
 bitmex wallet balance -o json 2>/dev/null
 ```
 
@@ -62,13 +62,15 @@ bitmex order buy XBTUSD 100 --price 50000 --order-type Limit --validate -o json
 bitmex order buy XBTUSD 100 --price 50000 --order-type Limit -o json 2>/dev/null
 
 # Confirm fill
-bitmex order list --symbol XBTUSD -o json 2>/dev/null | jq '.[] | {orderID, ordStatus, price, cumQty}'
+bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | jq '.[] | {orderID, ordStatus, price, cumQty}'
 ```
 
 Constraints: max qty per order, no compounding without approval, stop loss required.
 
 ## Level 4: Autonomous
 
+> ⚠️ Even at this level, active monitoring is required. Dead man's switch failure, position cap misconfiguration, or network outages can result in unprotected positions or runaway accumulation. You remain responsible for all outcomes.
+
 Pre-approved strategy parameters. Position limits enforced in code. Dead man's switch active on every session.
 
 ```bash
@@ -92,6 +94,8 @@ Requirements: strategy approved in writing, position limits in config, automated
 
 ## Level 5: Fund Management
 
+> ⚠️ Even at this level, active monitoring is required. Dead man's switch failure, position cap misconfiguration, or network outages can result in unprotected positions or runaway accumulation. You remain responsible for all outcomes.
+
 Multi-account, risk budget per strategy. Each strategy has an independent margin allocation.
 
 ```bash

skills/bitmex-basis-trading/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 Basis trading captures the spread between a perpetual and a fixed-date future on the same underlying. The spread converges to zero at expiry, yielding a predictable return when entered at a wide basis.
 
+Always validate on testnet first: prefix commands with `bitmex --testnet` until the strategy behaves as expected.
+
 ## What Is the Basis?
 
 ```

skills/bitmex-dca-strategy/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 # bitmex-dca-strategy
 
-DCA on BitMEX perpetuals: buy a fixed quantity at regular intervals regardless of price, using limit orders to earn maker rebates.
+DCA on BitMEX perpetuals: buy a fixed quantity at regular intervals regardless of price, using limit orders to potentially reduce costs with maker orders.
 
 **Always test with `--testnet` first for at least 5 cycles before using real funds.**
 
@@ -87,7 +87,7 @@ done
 ## Track Average Entry Price
 
 ```bash
-bitmex execution trade-history --symbol XBTUSD --count 100 -o json 2>/dev/null | \
+bitmex execution trade-history --symbol XBTUSD --reverse --count 100 -o json 2>/dev/null | \
   jq '
     [.[] | select(.side == "Buy" and .execType == "Trade")] |
     {

skills/bitmex-error-recovery/SKILL.md

@@ -73,7 +73,7 @@ bitmex order buy XBTUSD 100 --price 50000 \
   --cl-ord-id "$CL_ORD_ID" -o json 2>/dev/null
 
 # On network error, check if order exists before retrying
-EXISTING=$(bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+EXISTING=$(bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq --arg id "$CL_ORD_ID" '[.[] | select(.clOrdID == $id)]')
 
 COUNT=$(echo "$EXISTING" | jq 'length')
@@ -102,11 +102,11 @@ done
 
 ```bash
 ORDER_ID="<id>"
-STATUS=$(bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+STATUS=$(bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq -r --arg id "$ORDER_ID" '.[] | select(.orderID == $id) | .ordStatus')
-FILLED=$(bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+FILLED=$(bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq -r --arg id "$ORDER_ID" '.[] | select(.orderID == $id) | .cumQty')
-REMAINING=$(bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+REMAINING=$(bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq -r --arg id "$ORDER_ID" '.[] | select(.orderID == $id) | .leavesQty')
 
 echo "Status: $STATUS | Filled: $FILLED | Remaining: $REMAINING"

skills/bitmex-fee-optimization/SKILL.md

@@ -101,7 +101,7 @@ bitmex account commission -o json 2>/dev/null | jq '.XBTUSD'
 
 ```bash
 # Sum fees paid over last 500 executions
-bitmex execution trade-history --count 500 -o json 2>/dev/null | \
+bitmex execution trade-history --reverse --count 500 -o json 2>/dev/null | \
   jq '
     {
       total_fee: (map(.commission // 0) | add),
@@ -115,7 +115,7 @@ bitmex execution trade-history --count 500 -o json 2>/dev/null | \
 ## Maker vs Taker Split
 
 ```bash
-bitmex execution trade-history --count 500 -o json 2>/dev/null | \
+bitmex execution trade-history --reverse --count 500 -o json 2>/dev/null | \
   jq '
     {
       maker_count: (map(select(.commission < 0)) | length),

skills/bitmex-funding-carry/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: bitmex-funding-carry
 version: 1.0.0
-description: "Earn funding payments on BitMEX perpetuals: scan rates, entry, monitoring, yield calculation, and exit."
+description: "Capture funding rate payments on BitMEX perpetuals: scan rates, entry, monitoring, yield calculation, and exit."
 metadata:
   openclaw:
     category: "finance"
@@ -113,6 +113,8 @@ fi
 
 ## Annualized Yield Calculation
 
+> Note: annualized yield is illustrative only. Funding rates change every 8 hours and can flip from payment to cost. Past rates are not indicative of future returns.
+
 ```bash
 # Per 8h rate → annualized
 # 3 payments/day × 365 days = 1095 periods/year

skills/bitmex-market-intel/SKILL.md

@@ -51,7 +51,7 @@ bitmex market orderbook XBTUSD --depth 1 -o json 2>/dev/null | \
 
 ```bash
 # Last 100 trades
-bitmex market trades --symbol XBTUSD --count 100 -o json 2>/dev/null | \
+bitmex market trades --symbol XBTUSD --reverse --count 100 -o json 2>/dev/null | \
   jq '[.[] | {timestamp, side, price, size}]'
 
 # Bucketed candles (OHLCV)

skills/bitmex-order-execution/SKILL.md

@@ -26,7 +26,7 @@ bitmex account margin --currency XBt -o json 2>/dev/null | \
   jq '{availableMargin, marginBalance, marginLeverage}'
 
 # 3. Check for stale open orders
-bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq '[.[] | select(.ordStatus == "New" or .ordStatus == "PartiallyFilled") | {orderID, side, price, leavesQty}]'
 ```
 
@@ -67,7 +67,7 @@ ORDER_ID=$(echo "$ORDER" | jq -r '.orderID')
 Via REST polling:
 
 ```bash
-bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq --arg id "$ORDER_ID" '.[] | select(.orderID == $id) | {ordStatus, cumQty, leavesQty, avgPx}'
 ```
 

skills/bitmex-order-types/SKILL.md

@@ -127,7 +127,7 @@ bitmex order buy XBTUSD 100 --price 50000 --order-type Limit \
 Change price or qty on an open order without cancelling and re-placing:
 
 ```bash
-ORDER_ID=$(bitmex order list --symbol XBTUSD -o json 2>/dev/null | \
+ORDER_ID=$(bitmex order list --reverse --symbol XBTUSD -o json 2>/dev/null | \
   jq -r '[.[] | select(.ordStatus=="New")][0].orderID')
 
 bitmex order amend --order-id "$ORDER_ID" --price 50500 -o json 2>/dev/null