Payload schema

Spectra accepts a single JSON shape on webhook POSTs. Anything else returns 400 Bad Request with a schema-error body.

Minimal order

{
  "action": "buy",
  "symbol": "BTCUSDT",
  "qty": 1
}

Routes a market buy. The broker connection is decided by which secret the request was signed with.

Full schema

{
  "action": "buy" | "sell" | "close" | "flatten",
  "symbol": "string",
  "qty":    number,
  "type":   "market" | "limit" | "stop" | "stop_limit"
            | "trailing_stop",      // default: market
  "limit_price":   number,           // required for limit / stop_limit
  "stop_price":    number,           // required for stop / stop_limit
  "trail_offset":  number,           // required for trailing_stop
  "tp":     number | { "value": number, "kind": "abs" | "pct" | "atr" },
  "sl":     number | { "value": number, "kind": "abs" | "pct" | "atr" },
  "tif":    "day" | "gtc" | "ioc" | "fok", // default: day
  "client_id": "string"              // your idempotency key (≤ 64 chars)
}

flatten ignores qty and closes everything for the symbol. close closes a specific quantity (default = full position).

Idempotency

If client_id is set, Spectra dedupes. Re-POSTing the same client_id within 24 h returns 200 OK with the original outcome rather than placing a duplicate order. Recommended for any alert source that may retry on its own (most do — set a unique client_id per intended order).

Response

202 Accepted   →  body: { "order_id": "...", "client_id": "..." }
400 Bad Request →  schema or business-rule failure (loss-cap breach, ...)
401 Unauthorized →  signature/timestamp invalid
403 Forbidden  →  IP not in allowlist, or secret paused
429 Too Many Requests →  rate-limit (1 req/sec/secret default)