Merge pull request #8 from BitMEX-private/docs/tick-lot-size-guidance

docs: add tick size and lot size alignment guidance for order placement

Author: Quentin-M

AGENTS.md

@@ -273,13 +273,37 @@ bitmex execution trade-history --count 20 -o json
 bitmex wallet balance -o json
 ```
 
+### Tick size and lot size alignment
+
+Every instrument enforces a minimum price increment (`tickSize`) and minimum quantity increment (`lotSize`). Submitting a price or quantity that isn't a multiple of these will return a `400 Invalid price` or `400 Invalid quantity` error.
+
+Fetch constraints before placing:
+
+```bash
+constraints=$(bitmex market instrument --symbol XBTUSD -o json | jq '.[0] | {tickSize, lotSize}')
+tick_size=$(echo "$constraints" | jq -r '.tickSize')
+lot_size=$(echo "$constraints" | jq -r '.lotSize')
+```
+
+Round before submitting:
+
+```bash
+# round price to nearest tick
+price=$(echo "$raw_price $tick_size" | awk '{printf "%g", int($1/$2+0.5)*$2}')
+# round qty down to nearest lot
+qty=$(echo "$raw_qty $lot_size" | awk '{printf "%g", int($1/$2)*$2}')
+```
+
 ### Safe order placement workflow
 
 ```bash
-# 1. Validate
+# 1. Fetch tick/lot constraints and align price/qty before submitting
+constraints=$(bitmex market instrument --symbol XBTUSD -o json | jq '.[0] | {tickSize, lotSize}')
+
+# 2. Preview the constructed request body (local only — does not validate against exchange)
 bitmex order buy XBTUSD 100 --price 50000 --validate -o json
 
-# 2. Confirm with user, then execute
+# 3. Confirm with user, then execute (--yes skips interactive prompt for agent use)
 bitmex order buy XBTUSD 100 --price 50000 --yes -o json
 ```
 

CLAUDE.md

@@ -91,12 +91,19 @@ bitmex execution trade-history -o json
 
 ### Place orders (auth required, dangerous)
 
+Prices must be multiples of `tickSize`; quantities must be multiples of `lotSize`. Fetch these from `bitmex market instrument --symbol <SYMBOL> -o json | jq '.[0] | {tickSize, lotSize}'` before placing. Misaligned values return `400 Invalid price` or `400 Invalid quantity`.
+
 ```bash
-# Validate first
+# Fetch constraints
+constraints=$(bitmex market instrument --symbol XBTUSD -o json | jq '.[0] | {tickSize, lotSize}')
+tick_size=$(echo "$constraints" | jq -r '.tickSize')
+lot_size=$(echo "$constraints" | jq -r '.lotSize')
+
+# Preview request body (local dry-run only — no exchange-side validation)
 bitmex order buy XBTUSD 100 --price 50000 --validate -o json
 
-# Then execute (requires user confirmation)
-bitmex order buy XBTUSD 100 --price 50000 -o json
+# Execute (--yes required for non-interactive/agent use)
+bitmex order buy XBTUSD 100 --price 50000 --yes -o json
 ```
 
 ### Testnet

CONTEXT.md

@@ -195,6 +195,32 @@ bitmex ws trade:XBTUSD orderBookL2_25:XBTUSD
 bitmex ws --auth position order execution
 ```
 
+## Order Constraints: Tick Size and Lot Size
+
+Before placing an order, fetch the instrument's constraints:
+
+```bash
+constraints=$(bitmex market instrument --symbol XBTUSD -o json | jq '.[0] | {tickSize, lotSize}')
+tick_size=$(echo "$constraints" | jq -r '.tickSize')
+lot_size=$(echo "$constraints" | jq -r '.lotSize')
+```
+
+| Field | Meaning | Violation error |
+|-------|---------|----------------|
+| `tickSize` | Minimum price increment — price must be a multiple | `400 Invalid price` |
+| `lotSize` | Minimum quantity increment — qty must be a multiple | `400 Invalid quantity` |
+
+Round before submitting:
+
+```bash
+# price rounded to nearest tick
+price=$(echo "$raw_price $tick_size" | awk '{printf "%g", int($1/$2+0.5)*$2}')
+# qty rounded down to nearest lot
+qty=$(echo "$raw_qty $lot_size" | awk '{printf "%g", int($1/$2)*$2}')
+```
+
+`--validate` is a local dry-run that prints the constructed order JSON without submitting to the exchange. It does not perform server-side price/qty validation — alignment must be correct before live submission.
+
 ## MCP Server
 
 ```bash