# Perps trading for Grokbot

Deploy the matching wagmi-api and wagmi-web Perps bot changes before using these endpoints. The gateway uses the same WAGMI bot credential and platform service connection as the existing bot API. A browser session or wallet password must never be given to Grokbot.

## Owner setup

1. In `/perps`, fund the Main-wallet account, approve the WAGMI builder fee, and configure isolated margin/leverage for each desired market.
2. In Settings → API & bots → Unattended trading, select the existing key and Main wallet. Explicitly enable Perps, choose mainnet/testnet and allowed coin symbols, and set maximum order notional, daily opening notional, account exposure and leverage. Confirm with the wallet password in Settings only.
3. Give the bot its existing API key with `assets:read`, `balances:read` and `executions:read`. An approved live grant adds `perps:trade`; a key alone cannot grant itself trading permission. Existing grants are unchanged until the owner enables Perps.

Perps budgets are separate from spot/Earn budgets. Amounts are total position values in USDC, not margin. Opening reservations use the larger of requested notional and order size × bounded price. Daily usage is shared across the wallet's bot keys/grants and is not reset by grant replacement. Reservations remain counted even after a failed attempt; this is deliberately conservative. Account exposure includes all current positions and resting orders, including manual ones. Exposure/leverage limits are admission checks, not stop-loss orders or a guarantee of maximum loss. Risk-reducing closes and cancellations do not consume opening budgets.

## Endpoints (relative to `/v1`)

| Method | Path | Permission |
|---|---|---|
| GET | `/perps/markets` | `assets:read` |
| GET | `/perps/account?wallet_id=…` | `balances:read` |
| POST | `/perps/quote` | `perps:trade` |
| POST | `/perps/execute` | `perps:trade`, `Idempotency-Key` |
| GET | `/perps/operations/{id}` | `executions:read` |

Use the configured API host as `WAGMI_API_BASE` (including `/v1`). These are account-service routes, not direct Hyperliquid requests.

Open a long (use `sell` for a short):

```json
{
  "wallet_id": "YOUR_MAIN_WALLET_ID",
  "intent": {
    "action": "order",
    "coin": "BTC",
    "marginMode": "isolated",
    "side": "buy",
    "kind": "market",
    "notional": "100",
    "expectedLeverage": 3,
    "slippageBps": 30
  }
}
```

Send that body to `POST /perps/quote`. Persist the returned `quote_id`, original request and an idempotency key **before** sending `POST /perps/execute`:

```json
{"wallet_id":"YOUR_MAIN_WALLET_ID","quote_id":"RETURNED_UUID"}
```

Include `Authorization: Bearer YOUR_WAGMI_BOT_KEY`, `Content-Type: application/json`, and `Idempotency-Key: YOUR_PERSISTED_UNIQUE_KEY`. Reviews expire after two minutes. Reusing the same quote/key never signs a replacement order; using a different key for the same quote or reusing a key for another quote returns a conflict.

Close the current position through the same quote → execute flow:

```json
{"wallet_id":"YOUR_MAIN_WALLET_ID","intent":{"action":"close","coin":"BTC","slippageBps":30}}
```

The server derives the current position size and opposite side and enforces reduce-only. To cancel a resting order:

```json
{"wallet_id":"YOUR_MAIN_WALLET_ID","intent":{"action":"cancel","coin":"BTC","oid":123456}}
```

## Polling and recovery

Persist `quote_id` before submission. On timeout, poll `/perps/operations/{quote_id}` or retry the exact execute request with the original key. `signing`, `submitted` or `uncertain` must never trigger a replacement request. The signed payload and order identifier are checkpointed before exchange transmission. Crashed or uncertain operations are reconciled, not blindly broadcast again.

`operation.state=complete` means the exchange action was acknowledged; it is **not** proof that an IOC market order fully filled or the position closed. Read `/perps/account` to check positions and orders. IOC orders can partially fill; if a close leaves a residual position, first resolve the previous operation, then deliberately request a new reduce-only close. A `failed` operation requires a new quote after correcting the reported issue. Never retry it as a new trade merely because the HTTP request timed out.

This version supports isolated market opens, reduce-only market closes, and cancellation. It does not support bot funding/withdrawals, fee approvals, leverage changes, limit opens, TP/SL or alternate wallets. Closing can reduce an existing cross-margin position but cannot increase or reverse it. Global bot-disable, revoked/expired grants and keys stop new bot signing; an owner can still manage positions through the website.
