API Endpoint Specification

This document details the HTTP routes on the hoox gateway (workers/hoox-worker). TradingView® and other signal sources hit /webhook. Operator tools (TUI, dashboard, CLI health) use Bearer OPERATOR_API_KEY on /v1/* and /wallet/*.

agent-worker chat/vision/usage routes are not public gateway paths — they stay on that isolate (dashboard / TUI reach them via Service Bindings).

🔒 Request headers

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

Operator routes also require:

Authorization: Bearer <OPERATOR_API_KEY>

Optional on webhook and wallet writes: Idempotency-Key (max 256 chars). Prefer this over the auto fingerprint when you need cross-minute uniqueness.

CORS is disabled on /webhook — server-to-server POST only.

🎯 1. Ingest trade signal webhook

Receives, validates, and routes trade orders.

• Endpoint: /webhook (also POST /)
• Method: POST
• Auth: JSON apiKey must match WEBHOOK_API_KEY_BINDING on the hoox gateway

Request payload

{
  "apiKey": "your-hoox-webhook-passkey",
  "exchange": "bybit",
  "action": "LONG",
  "symbol": "BTCUSDT",
  "quantity": 0.005,
  "leverage": 10,
  "test": true,
  "idempotencyKey": "uuid-9b1deb4d-3b7d"
}

DEX example (BASE/QUOTE required; "test": true is rejected):

{
  "apiKey": "your-hoox-webhook-passkey",
  "exchange": "uniswap-ethereum",
  "action": "LONG",
  "symbol": "ETH/USDC",
  "quantity": 100
}

exchange: binance, bybit, mexc, uniswap-ethereum, uniswap-arbitrum, jupiter-solana. Full field table: Signals & trades. Testnet: Test Trading. DEX: DEX spot swaps.

Response models

A. Success (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 (202 Accepted)

If the exchange is down and webhook:queue_mode is queue_failover or queue_everywhere, the signal is enqueued.

{
  "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

Liveness probe. No auth. Reports binding presence, not a KV round-trip.

• Endpoint: /health
• Method: GET

{
  "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"
  }
}

CLI: hoox check health.

🛡️ 3. Operator plane (/v1/*)

Bearer OPERATOR_API_KEY. Fail-closed if the secret is missing.

💱 4. Wallet proxy (/wallet/*)

Forwards allowlisted paths to web3-wallet-worker with operator Bearer auth. The gateway injects mesh X-Internal-Auth-Key (WALLET_EXECUTE_KEY_BINDING / INTERNAL_KEY_BINDING). Idempotency-Key is passed through. Unknown paths are not forwarded.

Signal-driven DEX swaps still go POST /webhook → trade-worker → WEB3_WALLET_SERVICE /swap. The /wallet proxy is the operator surface.

🚨 5. Standard platform errors

A. 400 Bad Request

Invalid JSON, missing fields, unsupported test: true on MEXC/DEX (TEST_TRADING_UNSUPPORTED), or DEX symbol not BASE/QUOTE.

{
  "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. Options: binance, bybit, mexc, uniswap-ethereum, uniswap-arbitrum, jupiter-solana."
      }
    ]
  }
}

B. 403 Forbidden (invalid apiKey or IP)

{
  "success": false,
  "error": "Forbidden"
}

IP allowlist rejects return { "success": false, "error": "Access denied" } with 403.

C. 409 Conflict (duplicate idempotency key)

{
  "success": false,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "error": "Duplicate trade request. This trade was already processed."
}

Auto fingerprints include a per-minute time bucket. Prefer a client idempotencyKey.

D. 503 Service Unavailable (kill switch or missing DO)

{
  "success": false,
  "error": "Trading paused: global kill switch is enabled",
  "code": "KILL_SWITCH"
}

Missing IDEMPOTENCY_STORE binding is fail-closed (503).

🔗 Next Steps

• Signals & trades — webhook JSON schema and side mapping.
• CLI Commands Reference — CLI commands, options, and JSON flags.