# Trading guide This guide covers the full lifecycle of a trade on HermesTrade: reading the live order book, selecting the right order type, placing single and batch orders, canceling and replacing orders, and monitoring your fills and position history. {% hint style="info" %} HermesTrade is a central limit order book (CLOB). All prices come from real buy and sell orders. If you are new to order books, read [Core Concepts](/core-concepts/core-concepts.md) first. {% endhint %} *** ## Reading the order book Before placing any order, fetch a live snapshot of the book for the outcome token you want to trade. ``` GET /book?token_id= ``` The response is an `OrderBookSummary`: | Field | Description | | ----------------------------------- | ------------------------------------------------------------ | | `bids` | Array of `{price, size}` — buyers ranked highest price first | | `asks` | Array of `{price, size}` — sellers ranked lowest price first | | `last_trade_price` | Price of the most recent fill | | `tick_size` | Minimum price increment | | `min_order_size` / `max_order_size` | Size constraints for this token | **Example snapshot (abbreviated):** | Side | Price | Size | | ------- | -------- | ---- | | Ask | 0.72 | 150 | | Ask | 0.70 | 400 | | **Mid** | **0.68** | — | | Bid | 0.66 | 300 | | Bid | 0.64 | 500 | The **spread** is the gap between the best ask (0.70) and the best bid (0.66) — here, $0.04. A tighter spread means more liquid market and lower cost to enter or exit. Use `GET /spread?token_id=` to fetch the current spread in isolation before committing to a large order. For batch lookups across multiple tokens, use `POST /books` with an array of token IDs. *** ## Order type selection HermesTrade supports four order types. Choose based on how urgently you need the fill and whether a partial fill is acceptable. ### GTC — Good Till Canceled Your order rests on the book until it is filled or you cancel it. **Use this for most limit orders.** Set a price you're willing to pay and let the market come to you. * `expiration` field: set to `"0"` (no expiry) * Best for: patient position-building, liquid markets ### GTD — Good Till Date Like GTC, but the order automatically expires at a Unix timestamp you specify in the `expiration` field. **Use this when you want the order to disappear before an event starts** — for example, set expiration to 15 minutes before a sports match kickoff to avoid the auto-cancel risk described in [Sports markets](/guides/sports-markets.md). * `expiration` field: Unix timestamp in seconds * Best for: time-sensitive positions, sports markets, risk management ### FOK — Fill or Kill The order must be filled in its entirety immediately, or it is canceled outright. **Use this in automated strategies** where a partial position creates unwanted exposure. * No partial fills — either the full size transacts or nothing happens * Best for: bots, hedging legs, situations where you need guaranteed all-or-nothing execution ### FAK — Fill and Kill Fill as much as possible at the current moment, then cancel any unfilled remainder. **Use this when you want maximum immediate fill** but can tolerate a partial position. * Best for: entering a position quickly when you don't want a resting order * Equivalent to an aggressive "market-like" order: set a highly aggressive price (e.g., 0.99 for a buy) to sweep available asks {% hint style="info" %} HermesTrade has no explicit "market order" type. To simulate a market buy, place a FAK or FOK order at a price above the current best ask. To simulate a market sell, place FAK or FOK below the best bid. {% endhint %} *** ## Placing orders ### Single order ``` POST /order ``` Construct an order struct, sign it with EIP-712, then POST the signed object. See [Authentication](/reference/authentication.md) for the full signing flow. Key fields: | Field | Description | | ----------------------------- | ---------------------------------------------------------- | | `tokenID` | Outcome share token (from `clobTokenIds` on the market) | | `side` | `BUY` or `SELL` | | `price` | Limit price as a decimal string (e.g., `"0.66"`) | | `makerAmount` / `takerAmount` | Amounts for maker and taker | | `orderType` | `GTC`, `GTD`, `FOK`, or `FAK` | | `expiration` | Unix timestamp string; `"0"` for GTC | | `feeRateBps` | Fee in basis points — fetch from `GET /fee-rate/{tokenID}` | | `nonce` / `salt` | Uniqueness fields | The response is a `SendOrderResponse`: ``` success boolean orderID string status OrderStatus — LIVE, MATCHED, CANCELED, ... makingAmount string takingAmount string tradeIDs string[] transactionsHashes string[] errorMsg string ``` ### Batch orders (up to 15) ``` POST /orders ``` Send up to 15 signed order objects in a single request. Use batch orders to spread exposure across multiple outcomes, or to leg into a position across several price levels simultaneously. *** ## Canceling orders | Scope | Endpoint | Notes | | ---------------------- | ------------------------------ | ------------------------------------- | | Single order | `DELETE /order` | Cancel by order ID | | Batch (up to 3,000) | `DELETE /orders` | Pass an array of order IDs | | All orders in a market | `DELETE /cancel-market-orders` | Provide the market/condition ID | | All open orders | `DELETE /cancel-all` | Cancels everything across all markets | All cancellation endpoints require L2 API key authentication. *** ## Replacing orders ``` POST /orders/replace ``` Replace cancels an existing order and places a new one in a **single atomic operation**. This avoids the race condition that arises from separate `DELETE /order` and `POST /order` calls — the window between those two requests can result in a fill at the old price before the cancel lands. Use replace when you need to reprice an existing limit order while keeping your position in the queue. *** ## Monitoring your trades ### Fill history ``` GET /trades ``` Returns paginated user trade history. Each `Trade` record includes: | Field | Description | | ------------------ | ---------------------------------------------------------------------------------- | | `id` | Trade ID | | `asset_id` | Token ID of the outcome share | | `side` | `BUY` or `SELL` | | `price` | Fill price | | `size` | Fill size | | `status` | `MATCHED`, `SUBMITTED`, `MINED`, `CONFIRMED`, `RETRYING`, `FAILED`, or `SYNTHETIC` | | `match_type` | `COMPLEMENTARY`, `MINT`, `MERGE`, or `SYNTHETIC` | | `fee` | Fee charged | | `transaction_hash` | On-chain tx hash once mined | | `match_time` | Timestamp of the fill | Use the `next_cursor` query parameter for cursor-based pagination through large histories. For real-time streaming integrations, use the `from_id` parameter (a Snowflake-style trade ID) to fetch only trades newer than a known point. ### Open orders ``` GET /orders ``` Returns your open and historical orders filterable by `status`. Status values: `LIVE`, `MATCHED`, `CANCELED`, `CANCELED_MARKET_RESOLVED`, `SYSTEM_CLEARED`, `INVALID`. *** ## Price history and charting ``` GET /price-history?token_id=&interval=1D&fidelity=60 ``` Returns an array of time-bucketed `PricePoint` objects for charting: | Field | Type | Description | | ----- | ------ | ---------------------------------------- | | `p` | string | Price at the end of the bucket | | `t` | int64 | Bucket start as Unix timestamp (seconds) | **Interval options:** `1H`, `6H`, `1D`, `1W`, `1M`, `30D`, `ALL`, `MAX` **Fidelity:** bucket size in minutes (e.g., `60` = hourly candles within the interval) You can bound queries using `startTs` and `endTs` (Unix seconds). *** ## Heartbeat ``` POST /heartbeats ``` Some market-making integrations require periodic heartbeats to signal that the client is still alive. If your strategy places resting GTC orders that should be auto-canceled when your bot goes offline, configure the heartbeat interval in your integration and send this request regularly. Check with the HermesTrade team for the exact timeout window applicable to your account type. *** ## Slippage and spread management * **Check the spread before large orders:** Use `GET /spread?token_id=`. A wide spread (e.g., $0.05 or more) means you'll pay a significant entry cost relative to midpoint. * **For illiquid markets:** Set your limit price no more than $0.02 from the midpoint to avoid sweeping deep into the book. Use GTC and wait for the market to come to you. * **Use FAK to discover market depth:** Place a small FAK order first to see how much fills at your target price, then size up if the depth supports it. * **Batch price checks:** Use `POST /spreads` or `GET /midpoints` with multiple token IDs to survey several markets before committing capital. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hermestrade.xyz/guides/trading-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.