Request Payload Schemas
High-integrity JSON request payload specifications, TypeScript interfaces, and validation rules across Hoox microservices.
This page
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"
| "uniswap-ethereum"
| "uniswap-arbitrum"
| "jupiter-solana";
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 and spot DEX venues
* reject 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
}
| Field | Type | Required | Notes |
|---|---|---|---|
test | boolean | No | true → testnet host for Binance/Bybit; rejected for MEXC and spot DEX |
symbol | string | Yes | CEX compact ticker or DEX BASE/QUOTE (ETH/USDC) |
DEX venues (uniswap-ethereum, uniswap-arbitrum, jupiter-solana) are ExactIn spots through web3-wallet-worker. See DEX spot swaps.
Side effects when test: true:
| System | Effect |
|---|---|
| REST host | Binance testnet.binancefuture.com · Bybit api-testnet.bybit.com |
| Secrets | Prefer BINANCE_TESTNET_* / BYBIT_TESTNET_*; fall back to live bindings |
| D1 trades | status = 'TEST_EXECUTED' |
| D1 positions | id namespaced {exchange}-testnet-{symbol}-{side} |
| Telegram | Label includes [TEST] |
| Analytics | AE blob exchange = {exchange}:test |
| Queue | test is preserved on TradeQueueMessage; success notify is not duplicated |
| Agent | Skips *-testnet-* OPEN rows |
| Dashboard stats | Test fills/positions excluded from headline counts |
See Test Trading for operator setup.
B. Spot DEX signal (same /webhook envelope)
DEX venues use the CEX intent vocabulary. Pair syntax is BASE/QUOTE. test: true is rejected (TEST_TRADING_UNSUPPORTED).
{
"apiKey": "your-hoox-webhook-passkey",
"exchange": "uniswap-ethereum",
"action": "LONG",
"symbol": "ETH/USDC",
"quantity": 100
}
| Action | Swap |
|---|---|
LONG / CLOSE_SHORT | Spend QUOTE to buy BASE (ExactIn) |
SHORT / CLOSE_LONG | Sell BASE for QUOTE |
Operator-driven swaps (not webhook) go through the gateway wallet proxy (POST /wallet/swap) with Bearer OPERATOR_API_KEY.
🗄️ 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 @hoox-sh/hoox-shared/types to ensure complete type safety
across all workers!
🔗 Next Steps
- API Endpoint Directory — Analyze REST routes, headers, and endpoints mappings.
- Standard Response Schemas — Check success envelopes and error models.