Hoox Docs

📈 trade-worker Isolate Profile

The trade-worker is the execution engine of the Hoox trading platform. Deployed as a private compute isolate behind the edge firewall, this worker is responsible for calculating order parameters, executing leverage scaling, performing cryptographic HMAC-SHA256 signature calculations, placing trades on Bybit, Binance, and MEXC, and offloading transactional metrics.

⚡ 1. Declared Wrangler Configurations & Bindings

The trade-worker does not expose a public URL, communicating internally via V8 Service Bindings. Its wrangler.jsonc maps out its critical storage, queue, and database hooks:

{
  "name": "trade-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-19",
  "compatibility_flags": ["nodejs_compat"],
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "placement": {
    "mode": "smart",
  },
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "trade-data-db",
      "database_id": "c5917667a21745e390ff969f32b1847a",
    },
  ],
  "r2_buckets": [
    { "binding": "REPORTS_BUCKET", "bucket_name": "trade-reports" },
    { "binding": "SYSTEM_LOGS_BUCKET", "bucket_name": "hoox-system-logs" },
  ],
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
  ],
  "queues": {
    "consumers": [
      {
        "queue": "trade-execution",
        "max_batch_size": 10,
        "max_batch_timeout": 1,
      },
    ],
  },
  "secrets": [
    "INTERNAL_KEY_BINDING",
    "BYBIT_API_KEY",
    "BYBIT_API_SECRET",
    "BINANCE_API_KEY",
    "BINANCE_API_SECRET",
    "MEXC_API_KEY",
    "MEXC_SECRET_BINDING",
  ],
}

🔀 2. The Provider-Based ExchangeRouter Pattern

To support multiple centralized exchanges with different API schemas while maintaining a clean code structure, trade-worker implements a Provider Composition Pattern:

A. Generic Exchange Provider Interface

The client abstraction is defined inside the shared monorepo package @jango-blockchained/hoox-shared/types:

export interface IExchangeProvider<TClient, TEnv> {
  readonly name: string;
  createClient(env: TEnv): TClient;
  hasCredentials(env: TEnv): boolean;
}

B. Dynamic Runtime Routing

The ExchangeRouter evaluates the incoming symbol and parses settings in CONFIG_KV in sub-milliseconds:

  1. Default Path: Routes trades to the default CEX declared in exchanges:default_routing (typically bybit).
  2. Dynamic Symbol Redirects: Parses overrides in KV (e.g. exchanges:routing:SOLUSDT = binance). If present, the router bypasses Bybit and instantiates the BinanceProvider instantly without redeploying code.

🔌 3. Internal REST API Specification

A. Process Order Pipeline

Invoked by the hoox gateway or the TRADE_QUEUE consumer batch runner.

  • Endpoint: /process
  • Method: POST
  • Headers: X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>
  • JSON Payload: 
    {
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "payload": {
    "exchange": "bybit",
    "action": "LONG",
    "symbol": "BTCUSDT",
    "quantity": 0.005,
    "leverage": 10
  }
}
  • Success Response (200 OK): 
    {
  "success": true,
  "result": {
    "orderId": "18049284739",
    "status": "Filled",
    "price": 68425.5
  },
  "error": null
}

🛡️ 4. Standardized Exception Handling

All execution rejects and validation failures are intercepted by the trade-worker error middleware and formatted using the shared Errors factory from @jango-blockchained/hoox-shared/errors:

import { Errors } from "@jango-blockchained/hoox-shared/errors";

// 1. Parameter Validation Failure
if (quantity <= 0) {
  return Errors.badRequest("Quantity parameter must be greater than zero.");
}

// 2. Exchange Signature Timeout
if (timestampExpired) {
  return Errors.unauthorized(
    "Timestamp verification failed. Check system NTP sync."
  );
}

// 3. API Execution Rejects
try {
  await exchange.placeOrder(order);
} catch (err: any) {
  return Errors.internal(`Exchange API Reject: ${err.message}`);
}

Tip: If the exchange API rejects an order due to account rate-limiting, the queue consumer automatically returns a retry flag. Cloudflare Queues will back off and re-route the batch at intervals starting at 30 seconds, protecting your strategy from missed fills.

🔗 Next Steps