Hoox Docs

📦 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"; // Margin 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
}
{
  "exchange": "bybit",
  "action": "LONG",
  "symbol": "BTCUSDT",
  "quantity": 0.01,
  "leverage": 10,
  "orderType": "MARKET"
}

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"
}

Tip: Adding new fields to a payload schema? Remember to update the corresponding type interfaces in @jango-blockchained/hoox-shared/types to ensure complete type safety across all workers!

🔗 Next Steps