Skip to content

SKILL.md

Latest commit

 

History

History
106 lines (77 loc) · 3.16 KB

SKILL.md

File metadata and controls

106 lines (77 loc) · 3.16 KB
name bitmex-shared
version 1.0.0
description Shared runtime contract for bitmex-cli: auth, invocation, parsing, and safety.
metadata
openclaw requires
category
finance
bins
bitmex

bitmex-shared

This tool is experimental. Commands execute real financial transactions on BitMEX. Use --testnet before using real funds. See DISCLAIMER.md for full terms.

Invocation Contract

Always call:

bitmex <command-group> <subcommand> [args...] -o json 2>/dev/null

Rules:

  • Parse stdout only.
  • Treat stderr as diagnostics.
  • Exit code 0 = success.
  • Non-zero exit = failure; stdout contains a JSON error envelope.

Authentication

export BITMEX_API_KEY="your-key"
export BITMEX_API_SECRET="your-secret"

Public market data (market, announce, chat read) requires no credentials. All account, order, position, wallet, and staking commands require auth.

Testnet

Use --testnet for all testing. Connects to testnet.bitmex.com. No real money at risk. Obtain testnet API keys from testnet.bitmex.com/app/apiKeys.

bitmex --testnet market instrument --active -o json
bitmex --testnet order buy XBTUSD 100 --price 50000 --validate -o json
bitmex --testnet position list -o json

Error Envelope

{ "error": "<category>", "message": "<description>" }

Categories: api, auth, network, rate_limit, validation, config, websocket, io, parse.

Rate limit errors include suggestion, retryable, and docs_url fields:

{ "error": "rate_limit", "message": "...", "suggestion": "Wait 47s", "retryable": true }

Auth Mechanism

BitMEX uses HMAC-SHA256 signatures. Every authenticated request includes api-key, api-expires, and api-signature headers. The CLI handles this automatically when BITMEX_API_KEY and BITMEX_API_SECRET are set.

# Verify credentials are working
bitmex account me -o json 2>/dev/null | jq '.username'

Config File

Configuration is stored at ~/.config/bitmex/config.toml. Use bitmex auth set to write credentials:

bitmex auth set --api-key <key> --api-secret <secret>
bitmex auth show   # confirm (secret is masked)
bitmex auth reset  # clear stored credentials

Safety Rules

  1. Never place orders without explicit user approval.
  2. Always use --validate before live order submission.
  3. Use --testnet for all new strategies.
  4. Never log or print BITMEX_API_SECRET.
  5. Gate withdrawals, transfers, and cancellations behind --yes or explicit user confirmation.
  6. Always check exit code before acting on output.

Dangerous Commands

Any command that modifies state is considered dangerous: order buy/sell/amend/cancel/cancel-all/close-position, position leverage/isolate/transfer-margin/risk-limit, wallet withdraw/transfer, staking unstake. Never execute these without explicit user confirmation.

Error Handling Pattern

RESULT=$(bitmex market instrument --symbol XBTUSD -o json 2>/dev/null)
if [ $? -ne 0 ]; then
  CATEGORY=$(echo "$RESULT" | jq -r '.error // "unknown"')
  MESSAGE=$(echo "$RESULT" | jq -r '.message // ""')
  echo "Error [$CATEGORY]: $MESSAGE"
  exit 1
fi
echo "$RESULT" | jq '.'