API Endpoint Directory

This directory provides the complete HTTP REST API specification for all public and internal endpoints exposed across the Hoox edge microservices stack.

🔒 Security & Authorization Headers

All internal calls between workers (via V8 Service Bindings) must provide the standard internal authentication header:

X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>

Public webhook and dashboard endpoints use cookie authorization or custom API keys:

• Webhook ingestion: Authenticated using the apiKey property inside the JSON payload.
• Telegram webhook: Authenticated via the Telegram secret token header plus inbound chat allowlist.
• Operator plane (/v1/*, /wallet/*): Authorization: Bearer <OPERATOR_API_KEY>. The client env is HOOX_API_TOKEN. The gateway injects mesh X-Internal-Auth-Key (WALLET_EXECUTE_KEY_BINDING preferred) when it proxies to web3-wallet-worker.

🚀 Ingress Webhook Endpoints (workers/hoox-worker)

The public gateway acts as the primary firewall and entry entryway for all external trade signals.

A. Ingest Signal Webhook

Receives TradingView® alerts or automated cURL signals.

• Path: /webhook
• Method: POST
• JSON Payload:
  json[ COPY ]

  {'{'}
    "apiKey": "secure_webhook_key_18305",
    "exchange": "bybit",
    "action": "LONG",
    "symbol": "BTCUSDT",
    "quantity": 0.002,
    "leverage": 10,
    "test": true,
    "idempotencyKey": "uuid-9b1deb4d-3b7d"
  {'}'}
  

• test (optional boolean): when true, routes to exchange testnet (Binance/Bybit). MEXC returns TEST_TRADING_UNSUPPORTED. Idempotency keys are mode-split (:live vs :test). Prefer BINANCE_TESTNET_* / BYBIT_TESTNET_* secrets. See Test Trading.
• Success Response (200 OK):
  json[ COPY ]

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

B. Proactive Health Diagnostics

• Path: /health
• Method: GET
• Success Response (200 OK):
  json[ COPY ]

  {'{'}
    "success": true,
    "status": "ok",
    "timestamp": 1779261050000,
    "service": "hoox",
    "bindings": {'{'}
      "kv": "configured",
      "sessions": "configured",
      "queue": "configured",
      "trade": "configured",
      "telegram": "configured",
      "wallet": "configured",
      "idempotency": "configured",
      "rateLimiter": "configured"
    {'}'}
  {'}'}
  

GET /health is unauthenticated. Values are configured or missing — the probe does not round-trip KV.

Operator management plane (/v1/*)

Bearer OPERATOR_API_KEY via requireOperatorAuth. Prefer a dedicated management hostname (see Zero Trust).

Do not put operator Bearer on TradingView® /webhook.

Wallet operator proxy (/wallet/*)

The hoox gateway proxies allowlisted wallet paths to web3-wallet-worker (WEB3_WALLET_SERVICE). Callers authenticate with the operator Bearer; the gateway injects mesh auth. Idempotency-Key passes through. JSON bodies may carry an optional tenantId when tenant mode is on.

Allowlisted upstream paths (GET, POST, and PUT on each gateway path):

Any other /wallet/... path is not forwarded.

GET /wallet/status
Authorization: Bearer <OPERATOR_API_KEY>

POST /wallet/swap
Authorization: Bearer <OPERATOR_API_KEY>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "chain": "arbitrum",
  "tokenIn": "USDC",
  "tokenOut": "ETH",
  "amountIn": "100",
  "dexVersion": "v3"
}

Trade signals still go through POST /webhook with exchange set to uniswap-ethereum, uniswap-arbitrum, or jupiter-solana. See DEX spot swaps.

🗄️ Database Service Endpoints (workers/d1-worker)

The d1-worker serves as a private, internal SQL proxy database.

A. Execute Single SQL Statement

• Path: /query
• Method: POST
• JSON Payload:
  json[ COPY ]

  {'{'}
    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "query": "SELECT * FROM trades WHERE symbol = ? LIMIT ?",
    "params": ["BTCUSDT", 5]
  {'}'}
  

• Success Response (200 OK):
  json[ COPY ]

  {'{'}
    "success": true,
    "results": [{'{'} "id": "trade-1", "symbol": "BTCUSDT", "price": 68400 {'}'}],
    "meta": {'{'} "rows_read": 1, "duration": 3.5 {'}'}
  {'}'}
  

B. Execute Transactional Batch Statements

• Path: /batch
• Method: POST
• JSON Payload:
  json[ COPY ]

  {'{'}
    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "queries": [
      {'{'}
        "query": "INSERT INTO trades (id, symbol) VALUES (?, ?)",
        "params": ["t-1", "ETHUSDT"]
      {'}'},
      {'{'}
        "query": "UPDATE positions SET size = size + 0.05 WHERE symbol = 'ETHUSDT'",
        "params": []
      {'}'}
    ]
  {'}'}
  

• Success Response (200 OK):
  json[ COPY ]

  {'{'}
    "success": true,
    "results": [{'{'} "meta": {'{'} "changes": 1 {'}'} {'}'}, {'{'} "meta": {'{'} "changes": 1 {'}'} {'}'}]
  {'}'}
  

🧠 AI Risk & Chat Endpoints (workers/agent-worker)

Bridges background risk audits and multi-provider AI chat streams.

A. Conversational Chat Stream (Server-Sent Events)

• Path: /agent/chat
• Method: POST
• Headers: Accept: text/event-stream
• JSON Payload:
  json[ COPY ]

  {'{'}
    "prompt": "Summarize my trade history and average win rate today.",
    "stream": true,
    "provider": "anthropic"
  {'}'}
  

• Success Response: Emits standard text/event-stream updates, terminating with data: [DONE].

B. Multimodal AI Vision Audit

• Path: /agent/vision
• Method: POST
• JSON Payload:
  json[ COPY ]

  {'{'}
    "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "prompt": "Evaluate this trading chart image for support and resistance levels."
  {'}'}
  

• Success Response (200 OK):
  json[ COPY ]

  {'{'}
    "success": true,
    "analysis": "Based on the provided chart screenshot, there is strong horizontal support at $67,200..."
  {'}'}
  

🔗 Next Steps

• Request Payload Schemas — Analyze the complete JSON request schemas and type rules.
• Standard Response Schemas — Check error factories and normal JSON envelopes.