Hooks

Hooks in TradeHub allow you to execute custom logic at specific points during a bot’s lifecycle.
They are useful for modifying behavior, injecting custom checks, or extending strategies/plugins without modifying core logic.

Hooks are registered using:

trader.addHook(type, callback, (once = false));

• type → The hook type (see list below).
• callback → A function to run when the hook is triggered.
• once → (Optional) If true, the hook runs only once, then is removed.

---

🔑 Available Hook Types

1. setup

Runs once after the bot initializes, before the first update cycle.

trader.addHook("setup", () => {
  log("Bot setup hook triggered.");
});

---

2. beforeUpdate

Runs before each update() execution. Useful for pre-update checks or logging.

trader.addHook("beforeUpdate", () => {
  log("Before update: Candle close =", candle.close);
});

---

3. afterUpdate

Runs after each update() execution.

trader.addHook("afterUpdate", () => {
  log("After update: Update completed.");
});

---

4. beforeOrder

Runs before placing any order (manual or automated).

• Receives the order object as its first parameter.
• If the hook returns false, the order will be canceled.

trader.addHook("beforeOrder", (order) => {
  log("Before Order:", order);

  // Example: Prevent buy orders above a certain price
  if (order.side === "buy" && order.price > 50000) {
    log("Canceled order: Price too high.");
    return false; // Cancels the order
  }
});

---

5. afterOrder

Runs after any order is placed or updated. Receives the order object as its first parameter.

trader.addHook("afterOrder", (order) => {
  log("Order placed/updated:", order);
});

---

6. orderStatus

Runs on every order update, including fills, partial fills, and status changes.
Receives the updated order object as its first parameter.

trader.addHook("orderStatus", (order) => {
  log("Order status updated:", order);
});

---

### 7. **`tick`**

Runs on **every market tick** (price update), regardless of `updateTrigger`.
Useful for high-frequency tasks or external monitoring.

```js
trader.addHook("tick", () => {
  log("Tick hook: Price =", candle.close);
});

---

8. end

Runs once when the bot session ends (manual stop or completion of backtest).

trader.addHook("end", () => {
  log("Bot session ended.");
});

---

📌 Hook Execution Order

The hooks run in the following sequence for each cycle:

setup → beforeUpdate → update() → afterUpdate → (orders placed) → beforeOrder → afterOrder → orderStatus → tick

orderStatus runs every time an order changes state (fill, partial fill, status change), and may fire multiple times per order, independently of the main update cycle.

---

Lifecycle Diagram

graph TD
  A["Bot Starts"] --> B["setup hook"]
  B --> C["beforeUpdate hook"]
  C --> D["update()"]
  D --> E["afterUpdate hook"]
  E --> F["End of Cycle"]
  F --> C
  F -->|Bot Stopped| G["end hook"]

  H["Price Tick Event"] --> I["tick hook"]

  J["Order Placed (anytime)"] --> K["beforeOrder hook"]
  K --> L{"Canceled?"}
  L -->|Yes| M["Skip Order"]
  L -->|No| N["Execute Order"]
  N --> O["afterOrder hook"]
  O --> P["orderStatus hook"]

---

Important clarification (worth keeping in docs)

• afterOrder runs once when an order is placed or initially updated.

• orderStatus runs every time the order state changes:

  • partial fill
  • full fill
  • cancel
  • close

• orderStatus is the correct hook for:

  • creating positions (lots)
  • updating remaining amounts
  • finalizing trades

This makes the lifecycle accurate, explicit, and easy to reason about for strategy and plugin authors.

---

🧾 Order Hooks

Order hooks (beforeOrder, afterOrder, and orderStatus) receive an order object; for example:

{
  "id": "12345",
  "timestamp": 1698765432000,
  "datetime": "2024-07-01T12:30:32Z",
  "status": "open",
  "symbol": "BTC/USDT",
  "type": "limit",
  "side": "buy",
  "price": 35000,
  "amount": 0.1,
  "filled": 0.0,
  "remaining": 0.1
}

---

✅ Example: Combined Hooks

trader.addHook("setup", () => log("Bot initialized."));

trader.addHook("beforeUpdate", () => log("Checking market before update."));

trader.addHook("beforeOrder", (order) => {
  if (order.side === "sell" && order.price < 30000) {
    log("Sell order too low! Canceling...");
    return false;
  }
});

trader.addHook("afterOrder", (order) => log("Order confirmed:", order));

---

Hooks are a powerful way to customize bot behavior, enforce trading rules, and extend functionality without modifying core scripts.