# AGENTS.md — OpenAI Codex CLI & Autonomous Agent Guide for GaiaEx API

Use these instructions whenever generating, reviewing, or executing trading, market-making, or analytics code against **GaiaEx** (`https://openapi.gaiaex.com`).

## 1. Environment & Non-Custodial Safety Rules
- **Base REST Endpoint**: `https://openapi.gaiaex.com`
- **Base WebSocket Endpoint**: `wss://openapi.gaiaex.com/ws/market/{COIN}`
- **Credentials**: Always read `GAIAEX_API_KEY` and `GAIAEX_API_SECRET` from environment variables. Never commit secrets, echo secrets in terminal commands, or paste secrets into external payloads.
- **Self-Custody Boundary**: GaiaEx API keys are strictly scoped to `read` and `trade`. Deposits, withdrawals, and initial wallet handshakes happen exclusively in the GaiaEx App / Web UI.

## 2. Canonical Request & Signing Pattern (`/fapi/v1` & `/fapi/v2`)
- **Public GET Endpoints** (`/fapi/v1/ping`, `/fapi/v1/time`, `/fapi/v1/exchangeInfo`, `/fapi/v1/depth`, `/fapi/v1/klines`, `/fapi/v1/ticker/24hr`, `/fapi/v1/premiumIndex`, `/sapi/v1/depth`):
  - Require zero authentication.
  - Symbol format is strictly concatenated uppercase: `BTCUSDC`, `ETHUSDC`, `SOLUSDC`, `GOLDUSDC` (Hyperliquid USDC clearinghouse) or `BTCUSDT`, `ETHUSDT` (Aster USDT clearinghouse).
- **Authenticated Endpoints** (`GET /fapi/v2/balance`, `GET /fapi/v2/positionRisk`, `POST /fapi/v1/order`, `DELETE /fapi/v1/order`, `GET /fapi/v1/openOrders`, `GET /fapi/v1/userTrades`):
  - Send header `X-MBX-APIKEY: $GAIAEX_API_KEY`.
  - Append `timestamp=$(date +%s%3N)` and `signature=$(printf "%s" "$QUERY" | openssl dgst -sha256 -hmac "$GAIAEX_API_SECRET" | awk '{print $2}')`.

## 3. Tick-Size, Lot-Size & Rate-Limit Discipline
1. Before placing limit orders via `POST /fapi/v1/order`, fetch `GET /fapi/v1/exchangeInfo` once and cache `PRICE_FILTER.tickSize` and `LOT_SIZE.stepSize` for the target symbol.
2. Monitor response header `x-mbx-used-weight-1m`. Keep public polling below `20 req/s` per IP and prefer WebSocket streams for real-time orderbook updates.
3. For post-only maker rebates, use `type=LIMIT` with `timeInForce=ALO` (Add Liquidity Only / Post-Only).

## 4. Verification Smoke Test Command
```bash
curl -sS "https://openapi.gaiaex.com/fapi/v1/depth?symbol=BTCUSDC&limit=5" | jq .
```