Request Payload Schemas

To maintain robust data routing and prevent runtime failures, Hoox enforces a strict payload contract across all internal and public service boundaries. All incoming requests are validated by active JSON Schema or Zod middleware before entering V8 execution loops.

This document details the exact JSON schemas, TypeScript interfaces, and validation rules for all primary request payloads.

---

🛡️ 1. Standard Request Envelope

Every service-to-service invocation (via Service Bindings) wraps its business parameters inside a standardized Request Envelope containing distributed tracing indices:

export interface RequestEnvelope<T> {
  requestId: string; // Unique UUIDv4 distributed trace ID
  payload: T; // Service-specific payload
}

{
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "payload": {
    "symbol": "BTCUSDT",
    "quantity": 0.005
  }
}

---

📈 2. Trade Execution Payloads (trade-worker)

The execution engine processes two primary types of order payloads:

A. Centralized Exchange Order Payload (/webhook & /process)

export interface CexOrderPayload {
  exchange: "binance" | "bybit" | "mexc"; // Target exchange
  action: "LONG" | "SHORT" | "CLOSE_LONG" | "CLOSE_SHORT"; // Position action
  symbol: string; // Standardized asset ticker (e.g. "BTCUSDT")
  quantity: number; // Order size in contracts or tokens
  leverage?: number; // Optional margin leverage multiplier
  price?: number; // Optional execution limit price
  orderType?: "MARKET" | "LIMIT"; // Default: MARKET
  /**
   * When true, route the order to the exchange testnet/sandbox API
   * (Binance Futures testnet, Bybit testnet). MEXC has no public REST
   * sandbox and rejects with TEST_TRADING_UNSUPPORTED.
   * Live trading is the default when omitted or false.
   */
  test?: boolean;
}

{
  "exchange": "bybit",
  "action": "LONG",
  "symbol": "BTCUSDT",
  "quantity": 0.01,
  "leverage": 10,
  "orderType": "MARKET",
  "test": true
}

Side effects when test: true:

See Test Trading for operator setup.

---

B. On-Chain DeFi Swap Payload (/dex)

export interface DexSwapPayload {
  chain: "ethereum" | "arbitrum" | "polygon"; // EVM target network
  to: string; // Recipient address or Uniswap Router
  value: string; // Transaction value in Wei (as string)
  data: string; // Encoded contract call data bytes
  gasLimit?: number; // Optional transaction gas limit
}

{
  "chain": "arbitrum",
  "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
  "value": "100000000000000000",
  "data": "0xa9059cbb000000000000000000000000..."
}

---

🗄️ 3. Database SQL Query Payloads (d1-worker)

The SQLite database proxy accepts parameterized SQL statements to protect against SQL injections:

A. Execute Single SQL Statement

export interface SqlQueryPayload {
  query: string; // Parameterized SQL statement
  params: Array<string | number | boolean | null>; // Binding values
}

{
  "query": "SELECT * FROM trades WHERE symbol = ? AND status = ?",
  "params": ["BTCUSDT", "Filled"]
}

---

💬 4. Telegram Notification Payloads (telegram-worker)

Used to push structured alerts and charts to your mobile device:

export interface TelegramAlertPayload {
  chatId: string; // Target Telegram Chat ID
  message: string; // Formatted message content
  parseMode?: "HTML" | "MarkdownV2"; // Default: HTML
}

{
  "chatId": "987654321",
  "message": "<b>Alert:</b> Position filled at 68,420.",
  "parseMode": "HTML"
}

---

🔗 Next Steps

• API Endpoint Directory — Analyze REST routes, headers, and endpoints mappings.
• Standard Response Schemas — Check success envelopes and error models.