Get Trade Events

GET /api/v1/trades/{tradeID}/events

Scope: trades:read

Returns the trade's durable execution log — the authoritative record of every fill and hedge. This is the write-ahead log the engine itself uses, exposed read-only.

Response

200 OK

{
  "trade_id": "00000000-0000-0000-0000-000000000000",
  "events": [
    {
      "sequence": 1,
      "event_type": "maker_fill",
      "data": {
        "exchange": "lighter",
        "market": "HYPE",
        "side": "buy",
        "price": "24.50",
        "size": "1.0",
        "order_id": "123456",
        "client_order_id": "abc-1",
        "fully_filled": false,
        "timestamp_ms": 1780000000000
      },
      "worker_id": "worker-123",
      "created_at": "2026-03-12T13:07:15Z"
    },
    {
      "sequence": 2,
      "event_type": "hedge_sent",
      "data": { "exchange": "extended", "side": "sell", "size": "1.0" },
      "worker_id": "worker-123",
      "created_at": "2026-03-12T13:07:15Z"
    }
  ]
}

Event types

Event	Recorded when
`maker_fill`	A maker order filled (partial or full)
`hedge_sent`	The corresponding hedge order was sent to the hedger exchange
`hedge_filled`	The hedge order confirmed filled
`hedge_outcome`	Final outcome of a hedge attempt (including retries/rejections)
`hedge_timeout`	A hedge failed to confirm within the expected window
`chunk_started` / `chunk_completed`	Trade execution started / finished (legacy naming)
`recovery_completed`	A replacement worker finished reconciling after a crash/restart

Lifecycle events live on the WebSocket, not here. Status transitions (trade.started, trade.completed, trade.failed, trade.canceled, trade.paused, trade.resumed) are pushed in real time over the WebSocket API — they are not part of this endpoint's execution log. To reconstruct status history after the fact, poll Get Trade.

Event ordering

Events are append-only, ordered by sequence. Sequence numbers are unique within a trade and monotonically increasing. You can use sequence for incremental polling — query, note the highest sequence, query again later filtering for events with sequence > last seen.

Example

curl -H "X-API-Key: sprdr_..." \
  https://api.spreadr.xyz/api/v1/trades/{tradeID}/events

events = requests.get(f"{API_URL}/trades/{trade_id}/events", headers=headers).json()
for e in events["events"]:
    print(f"[seq {e['sequence']}] {e['event_type']} — {e.get('data', {})}")

Get Amend