# AGY.md — Google Antigravity (`agy`) & Gemini Agent Spec for GaiaEx API

Place this file at `.agy/AGY.md` or load it into your Antigravity (`agy`) / Gemini workspace when building quantitative strategies, data pipelines, or trading agents on **GaiaEx** (`https://openapi.gaiaex.com`).

## 1. Platform Overview
- **Exchange**: GaiaEx — AI-Native Self-Custody Derivatives, Spot & RWA Exchange.
- **Clearinghouses**:
  - **Hyperliquid L1 (`*USDC`)**: `BTCUSDC`, `ETHUSDC`, `SOLUSDC`, `HYPEUSDC`, `GOLDUSDC`, `NVDAUSDC`, `XAUTUSDC` (Spot).
  - **Aster DEX (`*USDT`)**: `BTCUSDT`, `ETHUSDT`, `SOLUSDT`, `BNBUSDT`.
- **API Standard**: GaiaEx Unified Futures API (`/fapi/v1/*`, `/fapi/v2/*`) and Spot API (`/sapi/v1/*`) at `https://openapi.gaiaex.com`.

## 2. Agent Execution Contract
1. **Verify Connectivity First**: Always run `GET https://openapi.gaiaex.com/fapi/v1/ping` and `GET https://openapi.gaiaex.com/fapi/v1/time` before starting an execution loop.
2. **Symbol Formatting**: Concatenate base and quote assets in uppercase (`BTCUSDC`, `ETHUSDT`). If an endpoint returns `{"code": -1121, "msg": "Invalid symbol."}`, append `USDC` or `USDT` to the base ticker.
3. **HMAC-SHA256 Signing**:
   - Header: `X-MBX-APIKEY: <GAIAEX_API_KEY>`
   - Sign the exact query string (`key1=val1&timestamp=1792840000000`) using `HMAC-SHA256` with `GAIAEX_API_SECRET` and append `&signature=<hex_digest>`.
   - Wallet address resolution is automatic on the server from `X-MBX-APIKEY`.
4. **Secret Redaction**: Never log or output `GAIAEX_API_SECRET`.

## 3. Ready-to-Run Async Python Template (`agy` Verified)
```python
import asyncio, json, requests, websockets

REST_BASE = "https://openapi.gaiaex.com"

def get_orderbook(symbol: str = "BTCUSDC", limit: int = 5) -> dict:
    r = requests.get(f"{REST_BASE}/fapi/v1/depth", params={"symbol": symbol, "limit": limit}, timeout=5)
    r.raise_for_status()
    return r.json()

async def stream_top_of_book(coin: str = "BTC", ticks: int = 5):
    uri = f"wss://openapi.gaiaex.com/ws/market/{coin}"
    async with websockets.connect(uri) as ws:
        for _ in range(ticks):
            msg = json.loads(await ws.recv())
            if msg.get("type") == "orderbook":
                bid = msg.get("bids", [["N/A"]])[0][0]
                ask = msg.get("asks", [["N/A"]])[0][0]
                print(f"[{coin}] Best Bid: {bid} | Best Ask: {ask}")

if __name__ == "__main__":
    print("Snapshot:", get_orderbook("BTCUSDC", 3))
    asyncio.run(stream_top_of_book("BTC", 3))
```