Events #

Events API provide event push as well as historical queries via SSE.

Some notes for Events Streaming

• If until is specified, since is required.
• If until_id is specified, since_id is required.
• Both since and since_id cannot be specified.
• If until or until_id is specified and the stream reaches to the end of queried range, the server disconnects the stream.
• Historical events are streamed immediately if queried, and updates are pushed as events occur.

Account Status #

You can listen to events related to change of account status, usually when sending in POST/accounts requests.

GET /v1/events/accounts/status

Request #

Parameters #

Response #

Sample Response #

data: {
  "account_id":"4db36989-6565-4011-9126-39fe6b3d9bf6",
  "account_number":"",
  "at":"2021-06-14T09:59:15.232782Z",
  "crypto_status_from":"SUBMITTED",
  "crypto_status_to":"APPROVED",
  "event_id":122039,
  "kyc_results":null,
  "status_from":"SUBMITTED",
  "status_to":"APPROVED"
  }

data: {
  "account_id":"4db36989-6565-4011-9126-39fe6b3d9bf6",
  "account_number":"937975699",
  "at":"2021-06-14T09:59:15.558338Z",
  "crypto_status_from":"APPROVED",
  "crypto_status_to":"ACTIVE",
  "event_id":122040,
  "kyc_results":null,
  "status_from":"APPROVED",
  "status_to":"ACTIVE"
  }

data: {
    "account_id": "081781bb-a9a0-4bde-bd65-e14b703e092b",
    "account_number": "932473536",
    "at": "2021-06-14T10:00:00.000000Z",
    "crypto_status_from":"SUBMITTED",
    "crypto_status_to":"ACTION_REQUIRED",
    "event_id": 122041,
    "kyc_results": {
        "reject": {},
        "accept": {},
        "indeterminate": {
            "TAX_IDENTIFICATION": {}
        },
        "summary": "fail"
    },
    "status_from": "SUBMITTED",
    "status_to": "ACTION_REQUIRED"
}

{
  "account_id": "d9615f1c-3a2b-3b55-8f6e-0afb69c1e8c7",
  "account_number": "1234563SW",
  "admin_configurations": {
    "incoming_transfers_blocked": false,
    "outgoing_transfers_blocked": false
  },
  "at": "2022-12-12T11:52:18.983824Z",
  "event_id": 9,
  "kyc_results": null,
  "status_from": "APPROVED",
  "status_to": "APPROVED"
}

{
  "account_id": "d9615f1c-3a2b-3b55-8f6e-0afb69c1e8c7",
  "account_number": "1234563SW",
  "at": "2022-12-12T11:54:04.438328Z",
  "event_id": 12,
  "kyc_results": null,
  "pattern_day_trader": true,
  "status_from": "APPROVED",
  "status_to": "APPROVED"
}

Parameters #

KYCResults #

For partners who utilize Alpaca’s KYC service for opening brokerage accounts the results of the CIP check will be returned via the kyc_results object. If an account’s status is set to REJECTED, ACTION_REQUIRED, or APPROVAL_PENDING the specific KYC results that may require action from your end user will wind up in ACCEPT, INDETERMINATE, or REJECT.

ENUM.KYCResultType #

The following result codes may return for a CIP check.

Appeal #

The table below shows the documents required to appeal the various CIP rejection reasons:

The table below shows the additional information required to appeal the various CIP rejection reasons:

Admin Configurations #

For the detailed list of Admin Configurations please see the Accounts page.

For the events interface we are only broadcasting changes to admin configurations. In case nothing changed for a flag that will not be included in unrelated update events.

Depending on the type of the Admin Configurations the sent event will behave differently. For bool flags we are only sending the new value.

For example the following payload means, that the disable_shorting flag was set to true from false:

{
  "disable_shorting": false
}

For other data types, we are embeding the old and new values into the payload. For example changing the max_margin_multiplier from 4 to 1 will yield this payload:

{
  "max_margin_multiplier": {
    "old": 4,
    "new": 1,
  }
}

Introducing an override value from the default will yield a null value as old. For example restricting the max_margin_multipler to 1 from default will yield the following payload:

{
  "max_margin_multiplier": {
    "old": null,
    "new": 1,
  }
}

Trade Updates #

You can listen to events related to trade updates.

Most market trades sent during market hours are filled instantly; you can listen to limit order updates through this endpoint.

GET /v2beta1/events/trades

Request #

Parameters #

Message ordering #

For the messages received on the SSE stream we guarantee that the order of the received events is the same as the order they were happening on a per account basis.

Example: if event E1 has been received earlier then another event E2 for the same account, then E1 happened before E2 according to our bookkeeping.

We do not have this guarantee across accounts: if two events for different accounts are received it is the consumer’s responsibility to decide which event happened first based on the timestamp/ulid fields of the event.

Example: E1 happened for account A1 before E2 which was affecting A2. The streaming endpoint might return the events in E1, E2 or E2, E1 ordering. Both responses should be considered valid.

Note: since ULIDs contain a random part other events might have arrived in the same millisecond as the last event received being lexiographicly less than the previous event.

If the stream is used for recon purposes, we recommend to restart the stream from a since that is a few mintues before the time of latest event received.

This approach means that the consumer will receive some events twice when restarting a stream: it is the consumer’s responsibility to process the recevied messages in an idempotent manner so that duplicate messages get ignored on the consumer side.

Note: since and until parameters are parsing as RFC3339 where timezone can be specified (e.g 2006-01-02T15:04:05+07:00), however plus sign character (+) is a special character in HTTP, so use the URL encoded version instead, e.g. ...events/trades?since=2006-01-02T15:04:05%2B07:00

Response #

Sample Response #

data:
  {
    "account_id":"c8f1ef5d-edc0-4f23-9ee4-378f19cb92a4",
    "at":"2021-06-14T10:04:05.172241Z",
    "event":"new",
    "event_id": "01F84ZMVNMS3Z9140YCKV7H0Z1",
    "execution_id":"a829b698-da07-479f-91e6-f204c77573fc",
    "order":{
      "asset_class":"us_equity",
      "asset_id":"b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
      "canceled_at":null,
      "client_order_id":"d6499947-dacd-4f85-a728-81734dc39c27",
      "commission":"1.1",
      "created_at":"2021-06-14T10:04:05.150255Z",
      "expired_at":null,
      "extended_hours":false,
      "failed_at":null,
      "filled_at":null,
      "filled_avg_price":null,
      "filled_qty":"0",
      "hwm":null,
      "id":"d507255a-b072-4fb7-96f3-9ad5a9c02b2a",
      "legs":null,
      "limit_price":null,
      "notional":"10",
      "order_class":"",
      "order_type":"market",
      "qty":null,
      "replaced_at":null,
      "replaced_by":null,
      "replaces":null,
      "side":"buy",
      "status":"new",
      "stop_price":null,
      "submitted_at":"2021-06-14T10:04:05.0937Z",
      "symbol":"AAPL",
      "time_in_force":"day",
      "trail_percent":null,
      "trail_price":null,
      "type":"market",
      "updated_at":"2021-06-14T10:04:05.165088Z"
    },
    "timestamp": "2021-06-14T10:04:05.172241Z"
  }

Parameters #

The following Parameters are only present when event is either fill or partial_fill #

Legacy trade events API #

The legacy trade events API is available for compatibility reasons at:

GET /v1/events/trades

Broker partners are recommended to upgrade to the /v2beta1/events/trades endpoint, which provides faster event delivery times.

The legacy trade events api works the same way as the new one with the exception of the event_id which is an integer except of an ULID. This results in the request’s since_id and until_id are also being integers. This integer is monotonically increasing over time for events.

Trade Events #

Common events

These are the events that are the expected results of actions you may have taken by sending API requests.

The meaning of the timestamp field changes for each type; the meanings have been specified here for which types the timestamp field will be present.

• new: Sent when an order has been routed to exchanges for execution.
• fill: Sent when your order has been completely filled.
  • timestamp: The time at which the order was filled.
• partial_fill: Sent when a number of shares less than the total remaining quantity on your order has been filled.
  • timestamp: The time at which the shares were filled.
• canceled: Sent when your requested cancellation of an order is processed.
  • timestamp: The time at which the order was canceled.
• expired: Sent when an order has reached the end of its lifespan, as determined by the order’s time in force value.
  • timestamp: The time at which the order expired.
• done_for_day: Sent when the order is done executing for the day, and will not receive further updates until the next trading day.
• replaced: Sent when your requested replacement of an order is processed.
  • timestamp: The time at which the order was replaced.

Rarer events

These 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.

• rejected: Sent when your order has been rejected.
  • timestamp: The time at which the rejection occurred.
• accepted
• held For multi-leg orders, the secondary orders (stop loss, take profit) will enter this state while waiting to be triggered.
• pending_new: Sent when the order has been received by Alpaca and routed to the exchanges, but has not yet been accepted for execution.
• 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.
• pending_cancel: Sent when the order is awaiting cancellation. Most cancellations will occur without the order entering this state.
• pending_replace: Sent when the order is awaiting replacement.
• 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.
• suspended: Sent when the order has been suspended and is not eligible for trading.
• order_replace_rejected: Sent when the order replace has been rejected.
• order_cancel_rejected: Sent when the order cancel has been rejected.

Journal Status #

You can listen to journal status updates as they get processed by our backoffice.

GET /v1/events/journals/status

Request #

Parameters #

Response #

Sample Response #

data: {
  "at":"2021-05-07T10:28:23.163857Z",
  "entry_type":"JNLC",
  "event_id":1406,
  "journal_id":"2f144d2a-91e6-46ff-8e37-959a701cc58d",
  "status_from":"",
  "status_to":"queued"
  }

data: {
  "at":"2021-05-07T10:28:23.468461Z",
  "entry_type":"JNLC",
  "event_id":1407,
  "journal_id":"2f144d2a-91e6-46ff-8e37-959a701cc58d",
  "status_from":"queued",
  "status_to":"pending"
  }

data: {
  "at":"2021-05-07T10:28:23.522047Z",
  "entry_type":"JNLC",
  "event_id":1408,
  "journal_id":"2f144d2a-91e6-46ff-8e37-959a701cc58d",
  "status_from":"pending",
  "status_to":"executed"
  }

Parameters #

Transfer Events #

You can listen to transfer status updates as they get processed by our backoffice, for both end-user and firm accounts.

For more on what those transfer statuses represent please click here.

GET /v1/events/transfers/status

Request #

Parameters #

Response #

Sample Response #

data: {"account_id":"8e00606a-c9ac-409a-ba45-f55e8f77984a","at":"2021-06-10T19:49:12.579109Z","event_id":15960,"status_from":"","status_to":"QUEUED","transfer_id":"c4ed4206-697b-4859-ab71-b9de6649859d"}

data: {"account_id":"8e00606a-c9ac-409a-ba45-f55e8f77984a","at":"2021-06-10T19:52:24.066998Z","event_id":15961,"status_from":"QUEUED","status_to":"SENT_TO_CLEARING","transfer_id":"c4ed4206-697b-4859-ab71-b9de6649859d"}

data: {"account_id":"8e00606a-c9ac-409a-ba45-f55e8f77984a","at":"2021-06-10T20:02:24.280178Z","event_id":15962,"status_from":"SENT_TO_CLEARING","status_to":"COMPLETE","transfer_id":"c4ed4206-697b-4859-ab71-b9de6649859d"}

Parameters #

Non Trading Activities Events #

You can listen to when NTAs are pushed such as CSDs, JNLC (journals) or FEEs.

GET /v1/events/nta

Request #

Parameters #

Response #

Parameters #

Read more on what Non Trade Activities Events mean and the fields they include here.

Sample Responses #

Cash Dividend #

{
  "id": "{GUID}",
  "qty": 0,
  "price": null,
  "status": "executed",
  "symbol": "BNDX",
  "entry_type": "DIV",
  "net_amount": 0.01,
  "description": "Cash DIV @ 0.0541, Pos QTY: 0.131126008, Rec Date: 2022-11-02",
  "settle_date": "2022-11-04",
  "system_date": "2022-11-04",
  "per_share_amount": 0.0541
}

Stock Dividend #

{
  "id": "{GUID}",
  "qty": 0.60001863,
  "price": null,
  "status": "executed",
  "symbol": "CIG",
  "entry_type": "DIV",
  "net_amount": 0,
  "description": "Stock DIV @ 0.3, Pos QTY: 2.000062113, Rec Date: 2022-05-03",
  "settle_date": "2022-05-20",
  "system_date": "2022-05-24",
  "per_share_amount": 0.3
}

Special Cash Dividend #

{
  "id": "{GUID}",
  "qty": 0,
  "price": null,
  "status": "executed",
  "symbol": "FLNG",
  "entry_type": "DIV",
  "net_amount": 200,
  "description": "Special Cash DIV @ 0.50, Pos QTY: 400, Rec Date: 2022-09-08",
  "settle_date": "2022-09-13",
  "system_date": "2022-09-13",
  "per_share_amount": null
}

DIVNRA #

{
  "id": "{GUID}",
  "qty": 0,
  "price": null,
  "status": "executed",
  "symbol": "NHI",
  "entry_type": "DIVNRA",
  "net_amount": -0.03,
  "description": "DIV tax withholding on $0.2 at 15% for tax country THA; w8w9: w8",
  "settle_date": "2022-11-04",
  "system_date": "2022-11-04",
  "per_share_amount": null
}

SPLIT #

Received as 2 events.

{
  "id": "{GUID}",
  "qty": -15,
  "price": 0,
  "status": "executed",
  "symbol": "DBGI",
  "entry_type": "SPLIT",
  "net_amount": 0,
  "description": "REMOVE, From QTY:100, To QTY:1, Position Value:0",
  "settle_date": "2022-11-04",
  "system_date": "2022-11-04",
  "per_share_amount": null
}

{
  "id": "{GUID}",
  "qty": 0.15,
  "price": 0,
  "status": "executed",
  "symbol": "DBGI",
  "entry_type": "SPLIT",
  "net_amount": 0,
  "description": "ADD, From QTY:100, To QTY:1, Position Value:0",
  "settle_date": "2022-11-04",
  "system_date": "2022-11-04",
  "per_share_amount": null
}

SPIN #

{
  "id": "{GUID}",
  "qty": 0.000085109,
  "price": null,
  "status": "executed",
  "symbol": "OABI",
  "entry_type": "SPIN",
  "net_amount": 0,
  "description": "Target Symbol: OABI, Initiating Symbol: LGND, 4.90007 OABI for each 1 LGND",
  "settle_date": "2022-11-02",
  "system_date": "2022-11-03",
  "per_share_amount": null
}

Cash Merger #

{
  "id": "{GUID}",
  "qty": -1.319800728,
  "price": null,
  "status": "executed",
  "symbol": "CYBE",
  "entry_type": "MA",
  "net_amount": 71.27,
  "description": "Cash Merger $54.00 per share",
  "settle_date": "2022-11-04",
  "system_date": "2022-11-04",
  "per_share_amount": null
}

Stock Merger #

{
  "id": "{GUID}",
  "qty": -1.333333333,
  "price": null,
  "status": "executed",
  "symbol": "USWS",
  "entry_type": "MA",
  "net_amount": 0,
  "description": "Stock Merger 0.3366 PFHC for 1 USWS",
  "settle_date": "2022-11-02",
  "system_date": "2022-11-02",
  "per_share_amount": null
}

Reorganisation #

{
  "id": "{GUID}",
  "qty": 0,
  "price": null,
  "status": "executed",
  "symbol": "EPZM",
  "entry_type": "MA",
  "net_amount": 342.2,
  "description": "Reorganization $1.45 per share",
  "settle_date": "2022-08-17",
  "system_date": "2022-08-17",
  "per_share_amount": null
}

Other examples of REORG: #

Ex1:

{
  "id": "{GUID}", 
  "qty": -2550, 
  "price": null, 
  "status": "executed", 
  "symbol": "HEPS", 
  "entry_type": "REORG",
  "net_amount": 0, 
  "description": "ADR Cancellation - BNY Mellon - Physical Certificates Sent to Client - Symbol HEPS", "settle_date": "2023-01-17", "system_date": "2023-01-17", 
  "per_share_amount": null
  }

Ex2:

{
  "id": "{GUID}", 
  "qty": -13.826006069, 
  "price": null, 
  "status": "executed", 
  "symbol": "023CNT017", 
  "entry_type": "REORG", 
  "net_amount": 0, 
  "description": "Worthless Security Removal", 
  "settle_date": "2023-01-12", 
  "system_date": "2023-01-12", 
  "per_share_amount": null
  }

Ex3:

{
  "id": "{GUID}", 
  "qty": 1, 
  "price": null, 
  "status": "executed", 
  "symbol": "728RGT010", 
  "entry_type": "REORG", 
  "net_amount": 0, 
  "description": "Plby Group Inc (PLBY) rights distribution - expiration 01/17/23",
  "settle_date": "2022-12-29", 
  "system_date": "2023-01-09", 
  "per_share_amount": null
  }

Ex4:

{
  "id": "{GUID}", 
  "qty": 1, 
  "price": null, 
  "status": "executed", 
  "symbol": "368CVR015", 
  "entry_type": "REORG", 
  "net_amount": 0, 
  "description": "Reorganisation 1 368CVR015 for 1 GMTX", 
  "settle_date": "2022-12-30", 
  "system_date": "2022-12-30", 
  "per_share_amount": null
  }

Ex5 (in this case you shouldn’t do anything since it was canceled):

{
  "id": "{GUID}", 
  "qty": 200, 
  "price": null, 
  "status": "canceled", 
  "symbol": "MMTLP", 
  "entry_type": "REORG", 
  "net_amount": 0, 
  "description": "Stock Merger 1591994371 for 1 MMTLP", 
  "settle_date": "2022-12-30", 
  "system_date": "2022-12-30", 
  "per_share_amount": null
  }

Ex6:

{
  "id": "{GUID}", 
  "qty": 0, 
  "price": null, 
  "status": "executed", 
  "symbol": "PDLI", 
  "entry_type": "REORG", 
  "net_amount": 87.68, 
  "description": "Partial Liquidation $0.21 per share + interest", 
  "settle_date": "2022-11-15", 
  "system_date": "2022-12-13", 
  "per_share_amount": null
  }

REG FEE #

{
  "id": "{GUID}", 
  "qty": 0, 
  "status": "executed", 
  "symbol": "", 
  "entry_type": "FEE", 
  "net_amount": -0.01, 
  "description": "REG fee for proceed of $0.87 on 2021-06-03 by {Account Number}", 
  "settle_date": "2021-06-07", 
  "system_date": "2021-06-03", 
  "per_share_amount": null
  }

TAF FEE #

{
  "id": "{GUID}", 
  "qty": 0, 
  "status": "executed", 
  "symbol": "", 
  "entry_type": "FEE", 
  "net_amount": -0.02, 
  "description": "TAF fee for proceed of 114 shares (2 trades) on 2021-06-03 by {Account Number}",
  "settle_date": "2021-06-07", 
  "system_date": "2021-06-03", 
  "per_share_amount": null
  }