Hoox Docs

🧠 How Hoox Works

At its core, Hoox functions as a highly resilient, low-latency pipeline that intercepts trading signals from external sources, validates and decodes the payloads, and converts them into cryptographically signed order placements on global exchanges in milliseconds.

Here is the exact lifecycle of an edge trade execution, from alert trigger to brokerage fill.

🗺️ The Execution Pipeline

sequenceDiagram
    autonumber
    actor Trigger as Signal Source (TradingView / Email / Telegram)
    participant GW as hoox Gateway (Public WAF + V8 Isolate)
    participant DO as Durable Object (Idempotency Lock)
    participant Q as Cloudflare Queue (Asynchronous Backup)
    participant TW as trade-worker (Execution Engine)
    participant CEX as Exchange API (Bybit / Binance / MEXC)
    participant D1 as D1 Database (Edge-SQLite)
    participant TG as telegram-worker (Notifications)

    Trigger->>GW: HTTP POST /webhook (JSON payload with Auth Passkey)
    GW->>DO: Lock Idempotency Key (Verify Trace ID)
    alt Already Processed (Duplicate Request)
        DO-->>GW: Fail: Duplicate Intercepted
        GW-->>Trigger: 409 Conflict (Duplicate Request)
    else Unique Request (Success Path)
        DO->>GW: Lock Acquired
        GW->>TW: Service Binding invoke (Fast Path)
        alt Direct Edge Call Succeeds
            TW->>CEX: Send Signed HMAC-SHA256 REST API Order
            CEX-->>TW: Order Executed (Fill Status + Details)
            TW->>D1: Write Transaction Record to SQLite Table
            TW->>TG: Service Binding invoke (Alert Notification)
            TG-->>Trigger: Send telegram alert to user mobile
            TW-->>GW: Return Executed JSON Payload
            GW-->>Trigger: 200 OK (Fill Result)
        else Direct Edge Call Fails (Exchange Offline / Rate Limited)
            GW->>Q: Enqueue Trade Payload (Guaranteed Delivery)
            GW-->>Trigger: 202 Accepted (Status: Enqueued)
            Note over Q, TW: Queue worker retries execution w/ exponential backoff
        end
    end

🔍 Detailed Pipeline Phase Analysis

1. Signal Arrival & Ingestion

Signals represent specific instructions to buy, sell, or close positions. Hoox ingests these instructions through three primary channels:

  • TradingView Webhooks: High-integrity trade alerts configured via Pine Script that issue JSON POST payloads to your gateway’s public /webhook route.
  • Telegram Commands: Direct user commands sent to your private Telegram Bot (e.g. /trade buy btc quantity=0.01 exchange=bybit), parsed via your webhook router.
  • Email Signals: Secure email triggers forwarded from specialized alerts (e.g. TradingView email alerts), parsed natively by email-worker.

2. Edge Firewall & Gateway Validation

When a signal hits your public endpoint, the hoox gateway interceptor immediately evaluates the request inside a sandboxed V8 isolate:

  1. API Key Authorization: Authenticates the payload’s apiKey property against your secure manifest stored in Cloudflare KV.
  2. IP Allow-listing: Verifies that the client IP matches a authorized IP range in KV (essential for restricting access solely to TradingView’s known webhook IPs).
  3. Global Kill Switch check: Ensures trade:kill_switch is false. If true, the pipeline aborts immediately to protect your capital.
  4. Rate Limiting: Verifies that signal frequency does not exceed safe execution thresholds (default: 10 orders/minute).
  5. Idempotency Check: Locks a unique transaction trace ID using a SQLite-backed Durable Object. If the DO detects that the exact same signal hash was already processed, it drops the request to prevent double-ordering.

3. Service Binding Order Routing

Once validated, the gateway bypasses public internet routing and calls the internal trade-worker directly via Service Bindings:

  • Zero Latency: Communication occurs within a microsecond inside the V8 engine, with zero TCP handshakes or TLS decryption overhead.
  • Private Isolation: The trade-worker does not expose any public URL, remaining completely isolated from external attacks.
  • Dynamic Exchange Routing: The worker parses the symbol (e.g. BTCUSDT) and evaluates your KV config. If Bybit is undergoing maintenance, you can instantly redirect trades to MEXC or Binance with one command.

4. Exchange Execution & Cryptographic Signing

The trade-worker loads your encrypted API credentials from Cloudflare Secrets, computes the HMAC-SHA256 signature for the order parameters, and pushes the signed request to the exchange’s nearest API gateway:

  • Smart Placement: Because Smart Placement is enabled, Cloudflare automatically runs your worker on the physical edge node located geographically closest to the exchange’s servers (e.g. Frankfurt for Bybit, Tokyo for Binance), cutting network transit time by up to 60%.

5. Persistent D1 Logging & Telemetry

Upon receipt of the order response (e.g. Filled, Partial, or Rejected), Hoox updates your ledger:

  • D1 SQLite Database: Writes transaction logs, filled prices, execution fees, and order IDs to your D1 database.
  • R2 Log Offloading: Offloads full JSON request-response packets to your secure R2 storage bucket to keep D1 database footprints compact.

6. User Notifications & Alerts

Finally, the trade-worker pings telegram-worker via an internal binding:

  • You receive an immediate Telegram notification on your phone detailing the symbol, filled price, order status, and transaction ID.
  • Twice-daily, report-worker uses Browser Rendering to compile beautiful HTML reports of your trading metrics, generating PDFs and dropping the link directly in your chat.

Tip: If the exchange API experiences transient network dropouts or severe rate limits, the Hoox Gateway automatically transfers the payload to Cloudflare Queues with an exponential retry schedule (30s → 1m → 5m → 15m), keeping your strategy fully reliable even during periods of heavy market volatility.

🔗 Next Steps