> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Payload Schemas

> High-integrity JSON request payload specifications, TypeScript interfaces, and validation rules across Hoox microservices.

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:

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

```json theme={null}
{
  "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`)

```typescript theme={null}
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
}
```

```json theme={null}
{
  "exchange": "bybit",
  "action": "LONG",
  "symbol": "BTCUSDT",
  "quantity": 0.01,
  "leverage": 10,
  "orderType": "MARKET"
}
```

***

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

```typescript theme={null}
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
}
```

```json theme={null}
{
  "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

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

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "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!
</Tip>

### 🔗 Next Steps

* **[API Endpoint Directory](endpoints)** — Analyze REST routes, headers, and endpoints mappings.
* **[Standard Response Schemas](responses)** — Check success envelopes and error models.