Hoox Docs

🌐 API Endpoint Specification

This document details the public REST API endpoints exposed by the Hoox gateway (workers/hoox). These endpoints are used to ingest automated trade signals, register Telegram bots, query AI metrics, and check serverless V8 isolate health status.

🔒 Request Headers & Security Policy

Every public HTTP request submitted to the Hoox gateway must include the following headers:

Content-Type: application/json
Accept: application/json

CORS & Origin Policies

For security, Cross-Origin Resource Sharing (CORS) is disabled by default on the /webhook route—it only accepts direct server-to-server POST requests (e.g. from TradingView or custom server scripts).

To interact with the dashboard, the gateway verifies active authorization cookies and tokens inside the V8 engine context.

🎯 1. Ingest Trade Signal Webhook

Receives, validates, and routes trade orders to exchange APIs.

  • Endpoint: /webhook
  • Method: POST

Request Payload (JSON Schema)

{
  "apiKey": "alpha_secure_key_18305",
  "exchange": "bybit",
  "action": "LONG",
  "symbol": "BTCUSDT",
  "quantity": 0.005,
  "leverage": 10,
  "idempotencyKey": "uuid-9b1deb4d-3b7d"
}

Response Models

A. Success Path (Order Filled Instantly - 200 OK)

{
  "success": true,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "exchange": "bybit",
  "symbol": "BTCUSDT",
  "action": "LONG",
  "result": {
    "orderId": "18049284739",
    "status": "Filled",
    "executedQty": 0.005,
    "price": 68425.5,
    "timestamp": 1779261050000
  }
}

B. Queue Failover Path (Exchange Offline / Rate-limited - 202 Accepted)

If the exchange is down, the signal is enqueued for guaranteed asynchronous delivery.

{
  "success": true,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "Enqueued",
  "message": "Signal enqueued in trade-execution Queue for background execution retry."
}

🟢 2. System Health Check

Probes the gateway isolate, validating connections to D1 databases and CONFIG_KV caches.

  • Endpoint: /health
  • Method: GET

Success Response (200 OK)

{
  "status": "ok",
  "timestamp": 1779261050000,
  "bindings": {
    "d1": "connected",
    "kv": "connected",
    "queue": "active"
  }
}

🤖 3. Conversational AI Chat & Telemetry

Integrates with the agent-worker Multi-Provider AI Gateway.

A. Conversational Chat Stream

  • Endpoint: /agent/chat
  • Method: POST
  • Headers: Accept: text/event-stream (Supports Server-Sent Events)

Request Payload

{
  "prompt": "Evaluate my trade performance over the last 24 hours.",
  "stream": true,
  "provider": "anthropic"
}

B. AI Gateway Telemetry

  • Endpoint: /agent/usage
  • Method: GET

Response Payload (200 OK)

{
  "success": true,
  "timestamp": 1779261050000,
  "usage": {
    "openai": { "inputTokens": 45180, "outputTokens": 8920, "costUSD": 0.183 },
    "anthropic": {
      "inputTokens": 18240,
      "outputTokens": 4010,
      "costUSD": 0.081
    },
    "workersAi": { "neuronsUsed": 842000, "costUSD": 0.0 }
  }
}

🚨 4. Standard Platform Error Models

When an API check fails, the gateway uses the shared @jango-blockchained/hoox-shared package to return a standardized JSON error format:

A. 400 Bad Request (Payload Validation Failure)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid JSON payload structure.",
    "details": [
      { "field": "quantity", "issue": "Must be greater than zero." },
      {
        "field": "exchange",
        "issue": "Invalid exchange router. Options: binance, bybit, mexc."
      }
    ]
  }
}

B. 401 Unauthorized (Invalid API Key / IP Address)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed. Mismatched apiKey or unauthorized origin IP."
  }
}

C. 409 Conflict (Duplicate Request Intercepted)

{
  "success": false,
  "error": {
    "code": "DUPLICATE_REQUEST",
    "message": "Order rejected. Durable Object locked: trace ID already processed in the last 24 hours."
  }
}

D. 503 Service Unavailable (Kill Switch Engaged)

{
  "success": false,
  "error": {
    "code": "KILL_SWITCH_ACTIVE",
    "message": "Trading halted globally. The emergency Global Kill Switch is currently turned ON in CONFIG_KV."
  }
}

Tip: Every error code is designed to map directly to a readable prompt in the Telegram bot and Next.js dashboard UI, allowing you to instantly diagnose execution problems.

🔗 Next Steps