Events

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 #

Attribute Type Requirement Notes
since string/date
Optional
Format: YYYY-MM-DD
until string/date
Optional
Format: YYYY-MM-DD
since_id int
Optional
until_id int
Optional

Response #

Sample Response #

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

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

Parameters #

Attribute Type Notes
account_id string UUID
account_number string Human readable
at string Timestamp of event
event_id int monotonically increasing 64bit integer
kyc_results string Results of KYC if applicable. Can be nullable.
status_from string Account status changed from
status_to string Account status changed to
reason string Optional

KYC Results #

For partners who utilize Alpaca’s KYC service for opening brokerage accounts and additional kyc_results object is represented on the account status updates.

Response #

Sample Response #
data: {
    "account_id": "081781bb-a9a0-4bde-bd65-e14b703e092b",
    "account_number": "932473536",
    "at": "2021-04-22T10:43:24.622749Z",
    "event_id": 3641,
    "kyc_results": {
        "reject": null,
        "accept": null,
        "indeterminate": {
            "TAX_IDENTIFICATION": {}
        }
    },
    "status_from": "ACTION_REQUIRED",
    "status_to": "ACTION_REQUIRED"
}
Parameters #
Attribute Type Notes
account_id string UUID
account_number string Human readable
at string Timestamp of event
event_id int monotonically increasing 64bit integer
kyc_results enum.KYCResults ACCEPT, INDETERMINATE or REJECT
status_from string Account status changed from
status_to string Account status changed to
reason string Optional

If an account request’s state is set to REJECTED or ACTION_REQUIRED the specific KYC results to take action on will wind up in one of three states:

  • ACCEPT - no further action required
  • INDETERMINATE - must be resolved by correspondent users, can be appealed by uploading new documents or by updating accounts on the Account API
  • REJECT - check failed

Result Codes #

The following result codes may return for a CIP check.

  • IDENTITY_VERIFICATION: identity needs to be verified
  • TAX_IDENTIFICATION: tax ID to be verified
  • ADDRESS_VERIFICATION: address needs to be verified
  • DATE_OF_BIRTH: date of birth needs to be verified
  • PEP: further information needs to be submitted if account is politically exposed person
  • FAMILY_MEMBER_PEP: further information needs to be submitted if family member is a politically exposed person
  • CONTROL_PERSON
  • AFFILIATED
  • OTHER

Appeal #

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

Result Code Government Issued ID Card Tax ID Card Statement (utility bill, etc.)
IDENTITY_VERIFICATION
Required
- -
TAX_IDENTIFICATION -
Required
-
ADDRESS_VERIFICATION
Required
-
Optional
DATE_OF_BIRTH
Required
- -

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

Result Code Additional information required
PEP Job title / occupation and address
FAMILY_MEMBER_PEP Name of politically exposed person if immediate family
CONTROL_PERSON Company name, company ticker, company address and company email
AFFILIATED Company / firm name, company / firm address, company / firm email, company / firm registration number
OTHER For specific cases our operational team might return with a customized message within the OTHER result code

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 /v1/events/trades

Request #

Parameters #

Attribute Type Requirement Notes
since string/date
Optional
Format: YYYY-MM-DD
until string/date
Optional
Format: YYYY-MM-DD
since_id int
Optional
until_id int
Optional

Response #

Sample Response #

data:
  {
    "account_id":"c8f1ef5d-edc0-4f23-9ee4-378f19cb92a4",
    "at":"2021-06-14T10:04:05.172241Z",
    "event":"new",
    "event_id":3014423,
    "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"
      }
  }

Parameters #

Attribute Type Notes
account_id string The UUID of the account
at string/timedate Timestamp of event
event string Events
event_id int monotonically increasing 64bit integer
execution_id string 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.

Trade Events #

Common events

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

  • 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.
    • price: The average price per share at which the order was filled.
    • position_qty: The size of your total position, after this fill event, in shares. Positive for long positions, negative for short positions.
  • 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.
    • price: The average price per share at which the shares were filled.
    • position_qty: The size of your total position, after this fill event, in shares. Positive for long positions, negative for short positions.
  • 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.
  • 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 #

Attribute Type Requirement Notes
since string
Optional
Format: YYYY-MM-DD
until string
Optional
Format: YYYY-MM-DD
since_id int
Optional
until_id int
Optional

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 #

Attribute Type Notes
at string Timestamp of event
entry_type string JNLC or JNLS
event_id int Monotonically increasing 64bit integer
journal_id string The UUID of the journal
status_from string Journal status
status_to string Journal status

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 #

Attribute Type Requirement Notes
since string/date
Optional
Format: YYYY-MM-DD
until string/date
Optional
Format: YYYY-MM-DD
since_id int
Optional
until_id int
Optional

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 #

Attribute Type Notes
account_id string Account UUID
at string Timedate of when the transfer status changed
event_id string Monotonically increasing 64bit integer
status_from string Transfer status
status_to string Transfer status
transfer_id string Transfer UUID

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 #

Attribute Type Requirement Notes
since string/date
Optional
Format: YYYY-MM-DD
until string/date
Optional
Format: YYYY-MM-DD
since_id int
Optional
until_id int
Optional

Response #

Sample Response #

data: {"account_id":"8e00606a-c9ac-409a-ba45-f55e8f77984a","at":"2021-06-11T10:46:59.265594Z","description":"","entry_type":"CSD","event_id":12437,"id":"f427a6da-248b-4dfb-ae8e-c9a844e39375","net_amount":49999,"per_share_amount":null,"price":"0","qty":0,"settle_date":"2021-06-10","status":"executed","symbol":"","system_date":"2021-06-10"}

data: {"account_id":"c96a5e16-7fca-425a-b67b-0814d064bfc0","at":"2021-06-09T10:45:43.636694Z","description":"ID: 347a459b-71f0-40bb-b451-31f32120b2cc - hi","entry_type":"JNLC","event_id":5019,"id":"d0aad3d1-710d-4461-a78f-7860a088ed4e","net_amount":200,"per_share_amount":null,"price":"0","qty":0,"settle_date":"2021-06-08","status":"correct","symbol":"","system_date":"2021-06-08"}

Parameters #

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