{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/alpaca/json-schema/alpaca-trade-update-event-schema.json",
  "title": "TradeUpdateEvent",
  "description": "Represents an update to an order/trade, sent over the events streaming api.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/alpaca-events-api-openapi.yml#/components/schemas/TradeUpdateEvent",
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "minLength": 1,
      "description": "Account UUID",
      "format": "uuid"
    },
    "at": {
      "type": "string",
      "minLength": 1,
      "description": "Timestamp of event",
      "format": "date-time"
    },
    "event": {
      "$ref": "#/$defs/TradeUpdateEventType"
    },
    "event_id": {
      "type": "integer",
      "format": "int64",
      "description": "Monotonically increasing 64bit integer"
    },
    "execution_id": {
      "type": "string",
      "description": "Corresponding execution of an order. If an order gets filled over two executions (a partial_fill for example), you will receive two events with different IDs.",
      "format": "uuid"
    },
    "order": {
      "$ref": "#/$defs/Order"
    },
    "timestamp": {
      "type": "string",
      "description": "Has various different meanings depending on the value of `event`, please see the [Trading Events](https://alpaca.markets/docs/api-references/broker-api/events/#trade-events)\nEnum in the documentation or the TradeUpdateEventType model for more details on when it means different things.\n",
      "format": "date-time"
    }
  },
  "required": [
    "account_id",
    "at",
    "event",
    "event_id",
    "execution_id",
    "order",
    "timestamp"
  ],
  "$defs": {
    "AssetClass": {
      "type": "string",
      "enum": [
        "us_equity",
        "crypto"
      ]
    },
    "Order": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "client_order_id": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "submitted_at": {
          "type": "string",
          "format": "date-time"
        },
        "filled_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "expired_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "canceled_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "failed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "replaced_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "replaced_by": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "replaces": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "asset_id": {
          "type": "string",
          "format": "uuid"
        },
        "symbol": {
          "type": "string"
        },
        "asset_class": {
          "$ref": "#/$defs/AssetClass"
        },
        "notional": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "qty": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "filled_qty": {
          "type": "string",
          "format": "decimal"
        },
        "filled_avg_price": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "order_class": {
          "$ref": "#/$defs/OrderClass"
        },
        "order_type": {
          "$ref": "#/$defs/OrderType"
        },
        "type": {
          "$ref": "#/$defs/OrderType"
        },
        "side": {
          "$ref": "#/$defs/OrderSide"
        },
        "time_in_force": {
          "$ref": "#/$defs/TimeInForce"
        },
        "limit_price": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "stop_price": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "status": {
          "$ref": "#/$defs/OrderStatus"
        },
        "extended_hours": {
          "type": "boolean"
        },
        "legs": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/Order"
          }
        },
        "trail_price": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "trail_percent": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "hwm": {
          "type": [
            "string",
            "null"
          ],
          "format": "decimal"
        },
        "commission": {
          "type": "string",
          "format": "decimal"
        }
      },
      "required": [
        "id",
        "symbol"
      ]
    },
    "OrderClass": {
      "type": "string",
      "enum": [
        "simple",
        "bracket",
        "oco",
        "oto"
      ]
    },
    "OrderSide": {
      "type": "string",
      "enum": [
        "buy",
        "sell",
        "buy_minus",
        "sell_plus",
        "sell_short",
        "sell_short_exempt",
        "undisclosed",
        "cross",
        "cross_short"
      ],
      "description": "Represents what side of the transaction an order was on."
    },
    "OrderStatus": {
      "type": "string",
      "enum": [
        "new",
        "partially_filled",
        "filled",
        "done_for_day",
        "canceled",
        "expired",
        "replaced",
        "pending_cancel",
        "pending_replace",
        "accepted",
        "pending_new",
        "accepted_for_bidding",
        "stopped",
        "rejected",
        "suspended",
        "calculated"
      ]
    },
    "OrderType": {
      "type": "string",
      "enum": [
        "market",
        "limit",
        "stop",
        "stop_limit",
        "trailing_stop"
      ]
    },
    "TimeInForce": {
      "type": "string",
      "enum": [
        "day",
        "gtc",
        "opg",
        "cls",
        "ioc",
        "fok"
      ]
    },
    "TradeUpdateEventType": {
      "type": "string",
      "description": "**Common events**\n\nThese are the events that are the expected results of actions you may have taken by sending API requests.\n\nThe meaning of the `timestamp` field changes for each type; the meanings have been specified here for which types the\ntimestamp field will be present.\n\n- `new`: Sent when an order has been routed to exchanges for execution.\n- `fill`: Sent when your order has been completely filled.\n  - `timestamp`: The time at which the order was filled.\n- `partial_fill`: Sent when a number of shares less than the total remaining quantity on your order has been filled.\n  - `timestamp`: The time at which the shares were filled.\n- `canceled`: Sent when your requested cancellation of an order is processed.\n  - `timestamp`: The time at which the order was canceled.\n- `expired`: Sent when an order has reached the end of its lifespan, as determined by the order’s time in force value.\n  - `timestamp`: The time at which the order expired.\n- `done_for_day`: Sent when the order is done executing for the day, and will not receive further updates until the next trading day.\n- `replaced`: Sent when your requested replacement of an order is processed.\n  - `timestamp`: The time at which the order was replaced.\n\n**Rarer events**\n\nThese are events that may rarely be sent due to unexpected circumstances on the exchanges. It is unlikely you will need to design your code around them, but you may still wish to account for the possibility that they will occur.\n\n- `rejected`: Sent when your order has been rejected.\n  - `timestamp`: The time at which the rejection occurred.\n- `pending_new`: Sent when the order has been received by Alpaca and routed to the exchanges, but has not yet been accepted for execution.\n- `stopped`: Sent when your order has been stopped, and a trade is guaranteed for the order, usually at a stated price or better, but has not yet occurred.\n- `pending_cancel`: Sent when the order is awaiting cancellation. Most cancellations will occur without the order entering this state.\n- `pending_replace`: Sent when the order is awaiting replacement.\n- `calculated`: Sent when the order has been completed for the day - it is either `filled` or `done_for_day` - but remaining settlement calculations are still pending.\n- `suspended`: Sent when the order has been suspended and is not eligible for trading.\n- `order_replace_rejected`: Sent when the order replace has been rejected.\n- `order_cancel_rejected`: Sent when the order cancel has been rejected.\n",
      "enum": [
        "new",
        "fill",
        "partial_fill",
        "canceled",
        "expired",
        "done_for_day",
        "replaced",
        "rejected",
        "pending_new",
        "stopped",
        "pending_cancel",
        "pending_replace",
        "calculated",
        "suspended",
        "order_replace_rejected",
        "order_cancel_rejected"
      ]
    }
  }
}