List account holdings / SnapTrade

List account holdings

get

https://api.snaptrade.com/api/v1/accounts/{accountId}/holdings

Returns a list of balances, positions, and recent orders for the specified account. The data returned is similar to the data returned over the more fine-grained balances, positions and orders endpoints. The finer-grained APIs are preferred. They are easier to work with, faster, and have better error handling than this coarse-grained API.

The data returned here is cached. How long the data is cached for varies by brokerage. Check the brokerage integrations doc and look for "Cache Expiry Time" to see the exact value for a specific brokerage. If you need real-time data, please use the manual refresh endpoint.

Execute an API Request

Path

accountIdstring (format: uuid)required

Unique identifier for the connected brokerage account. This is the UUID used to reference the account in SnapTrade.

Query

userIdstringrequired

SnapTrade User ID. This is chosen by the API partner and can be any string that is a) unique to the user, and b) immutable for the user. It is recommended to NOT use email addresses for this property because they are usually not immutable.

userSecretstringrequired

SnapTrade User Secret. This is a randomly generated string and should be stored securely. If compromised, please rotate it via the rotate user secret endpoint.

Authorization

clientId

consumerKey

Request

Installation

GitHub npm

npm install snaptrade-typescript-sdk

1
Loading...

Response fields

object

A wrapper object containing holdings information for a single account.

accountobject

A single account at a brokerage.

idstring (format: uuid)

Unique identifier for the connected brokerage account. This is the UUID used to reference the account in SnapTrade. This ID should not change for as long as the connection stays active. If the connection is deleted and re-added, a new account ID will be generated.

brokerage_authorizationstring (format: uuid)

Unique identifier for the connection. This is the UUID used to reference the connection in SnapTrade.

namestring or null

A display name for the account. Either assigned by the user or by the brokerage itself. For certain brokerages, SnapTrade appends the brokerage name to the account name for clarity.

numberstring

The account number assigned by the brokerage. For some brokerages, this field may be masked for security reasons.

institution_namestring

The name of the brokerage that holds the account.

created_datestring (format: date-time)

Timestamp in ISO 8601 format indicating when the account was created in SnapTrade. This is not the account opening date at the brokerage.

sync_statusobject

Contains status update for the account sync process between SnapTrade and the brokerage.

balanceobject

Contains balance related information for the account.

metaobject

Deprecated

Refrain from usage of this field

Additional information about the account, such as account type, status, etc. This information is specific to the brokerage and there's no standard format for this data. This field is deprecated and subject to removal in a future version.

portfolio_groupstring (format: uuid)

Deprecated

Refrain from usage of this field

Portfolio Group ID. Portfolio Groups have been deprecated. Please contact support if you have a usecase for it.

cash_restrictionsarray of strings

Deprecated

Refrain from usage of this field

This field is deprecated.

balancesarray of objects or null

List of balances for the account. Each element of the list has a distinct currency. Some brokerages like Questrade allows holding multiple currencies in the same account.

positionsarray of objects or null

List of stock/ETF/crypto/mutual fund positions in the account.

symbolobject

Uniquely describes a security for the position within an account. The distinction between this and the symbol child property is that this object is specific to a position within an account, while the symbol child property is universal across all brokerage accounts. The caller should rely on the symbol child property for most use cases.

symbolobject

Uniquely describes a single security + exchange combination across all brokerages.

idstring (format: uuid)

Unique identifier for the symbol within SnapTrade. This is the ID used to reference the symbol in SnapTrade API calls.

symbolstring

The security's trading ticker symbol. For example "AAPL" for Apple Inc. We largely follow the Yahoo Finance ticker format(click on "Yahoo Finance Market Coverage and Data Delays"). For example, for securities traded on the Toronto Stock Exchange, the symbol has a '.TO' suffix. For securities traded on NASDAQ or NYSE, the symbol does not have a suffix.

raw_symbolstring

The raw symbol is symbol with the exchange suffix removed. For example, if symbol is "VAB.TO", then raw_symbol is "VAB".

descriptionstring or null

A human-readable description of the security. This is usually the company name or ETF name.

currencyobject

The currency in which the security is traded.

exchangeobject

The exchange on which the security is listed and traded.

typeobject

The type of security. For example, "Common Stock" or "ETF".

figi_codestring or null

This identifier is unique per security per trading venue. See section 1.4.1 of the FIGI Standard for more information. This value should be the same as the figi_code in the figi_instrument child property.

figi_instrumentobject or null

Financial Instrument Global Identifier (FIGI) information for the security. See OpenFIGI for more information.

currenciesarray of objects

Deprecated

Refrain from usage of this field

This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid usecase for this.

idstring (format: uuid)

Deprecated

Refrain from usage of this field

A unique ID for the security within SnapTrade, scoped to the brokerage account that the security belongs to. This is a legacy field and should not be used. Do not rely on this being a stable ID as it can change.

descriptionstring

Deprecated

Refrain from usage of this field

This field is deprecated and the caller should use the symbol child property's description instead.

local_idstring or null

Deprecated

Refrain from usage of this field

This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid usecase for this.

is_quotableboolean

Deprecated

Refrain from usage of this field

This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid usecase for this.

is_tradableboolean

Deprecated

Refrain from usage of this field

This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid usecase for this.

unitsnumber or null

The number of shares of the position. This can be fractional or integer units.

pricenumber or null

Last known market price for the symbol. The freshness of this price depends on the brokerage. Some brokerages provide real-time prices, while others provide delayed prices. It is recommended that you rely on your own third-party market data provider for most up to date prices.

open_pnlnumber or null

The profit or loss on the position since it was opened. This is calculated as the difference between the current market value of the position and the total cost of the position. It is recommended to calculate this value using the average purchase price and the current market price yourself, instead of relying on this field.

average_purchase_pricenumber or null

Cost basis per share of this position.

fractional_unitsnumber or null

Deprecated

Refrain from usage of this field

Deprecated, use the units field for both fractional and integer units going forward

option_positionsarray of objects or null

List of option positions in the account.

symbolobject

Uniquely describes a security for the option position within an account. The distinction between this and the option_symbol child property is that this object is specific to a position within an account, while the option_symbol child property is universal across all brokerage accounts. The caller should rely on the option_symbol child property for most use cases.

option_symbolobject

Uniquely describes an option security + exchange combination across all brokerages.

idstring (format: uuid)

Unique identifier for the option symbol within SnapTrade. This is the ID used to reference the symbol in SnapTrade API calls.

tickerstring

The OCC symbol for the option.

option_typestring

The type of option. Either "CALL" or "PUT".

strike_pricenumber

The option strike price.

expiration_datestring (format: date)

The option expiration date.

is_mini_optionboolean

Whether the option is a mini option. Mini options have 10 underlying shares per contract instead of the standard 100.

underlying_symbolobject

Symbol object for the underlying security of an option.

idstring (format: uuid)

Unique identifier for the symbol within SnapTrade. This is the ID used to reference the symbol in SnapTrade API calls.

symbolstring

raw_symbolstring

The raw symbol is symbol with the exchange suffix removed. For example, if symbol is "VAB.TO", then raw_symbol is "VAB".

descriptionstring or null

A human-readable description of the security. This is usually the company name or ETF name.

currencyobject

The currency in which the security is traded.

exchangeobject

The exchange on which the security is listed and traded.

typeobject

The type of security. For example, "Common Stock" or "ETF".

figi_codestring or null

figi_instrumentobject or null

Financial Instrument Global Identifier (FIGI) information for the security. See OpenFIGI for more information.

currenciesarray of objects

Deprecated

Refrain from usage of this field

This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid usecase for this.

idstring (format: uuid)

Deprecated

Refrain from usage of this field

descriptionstring

Deprecated

Refrain from usage of this field

This field is deprecated and the caller should use the option_symbol child property's description instead.

pricenumber or null

Last known market price per share of the option contract. The freshness of this price depends on the brokerage. Some brokerages provide real-time prices, while others provide delayed prices. It is recommended that you rely on your own third-party market data provider for most up to date prices.

unitsnumber

The number of contracts for this option position. A positive number indicates a long position, while a negative number indicates a short position.

average_purchase_pricenumber or null

Cost basis per contract of this option position. To get the cost basis per share, divide this value by the number of shares per contract (usually 100).

currencyobject or null

The currency of the price. This field is deprecated and will be removed in a future version. The currency of the price is determined by the currency of the underlying security.

ordersarray of objects or null

List of recent orders in the account, including both pending and executed orders. Note that option orders are included in this list. Option orders will have a null universal_symbol field and a non-null option_symbol field.

brokerage_order_idstring

Order ID returned by brokerage. This is the unique identifier for the order in the brokerage system.

statusstring

Indicates the status of an order. SnapTrade does a best effort to map brokerage statuses to statuses in this enum.

universal_symbolobject

Contains information about the security that the order is for. This field is only present for stock/ETF/crypto/mutual fund orders. For option orders, this field will be null and the option_symbol field will be populated.

option_symbolobject

Contains information about the option contract that the order is for. This field is only present for option orders. For stock/ETF/crypto/mutual fund orders, this field will be null and the universal_symbol field will be populated.

actionstring

The action describes the intent or side of a trade. This is usually BUY or SELL but can include other potential values like the following depending on the specific brokerage.

BUY
SELL
BUY_COVER
SELL_SHORT
BUY_OPEN
BUY_CLOSE
SELL_OPEN
SELL_CLOSE

total_quantitynumber or null

The total number of shares or contracts of the order. This should be the sum of the filled, canceled, and open quantities. Can be a decimal number for fractional shares.

open_quantitynumber or null

The number of shares or contracts that are still open (waiting for execution). Can be a decimal number for fractional shares.

canceled_quantitynumber or null

The number of shares or contracts that have been canceled. Can be a decimal number for fractional shares.

filled_quantitynumber or null

The number of shares or contracts that have been filled. Can be a decimal number for fractional shares.

execution_pricenumber or null

The price at which the order was executed.

limit_pricenumber or null

The limit price is maximum price one is willing to pay for a buy order or the minimum price one is willing to accept for a sell order. Should only apply to Limit and StopLimit orders.

stop_pricenumber or null

The stop price is the price at which a stop order is triggered. Should only apply to Stop and StopLimit orders.

order_typestring or null

The type of order placed. The most common values are Market, Limit, Stop, and StopLimit. We try our best to map brokerage order types to these values. When mapping fails, we will return the brokerage's order type value.

time_in_forcestring

The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. We try our best to map brokerage time in force values to the following. When mapping fails, we will return the brokerage's time in force value.

Day - Day. The order is valid only for the trading day on which it is placed.
GTC - Good Til Canceled. The order is valid until it is executed or canceled.
FOK - Fill Or Kill. The order must be executed in its entirety immediately or be canceled completely.
IOC - Immediate Or Cancel. The order must be executed immediately. Any portion of the order that cannot be filled immediately will be canceled.
GTD - Good Til Date. The order is valid until the specified date.
MOO - Market On Open. The order is to be executed at the day's opening price.
EHP - Extended Hours P.M. The order is to be placed during extended hour trading, after markets close.

time_placedstring (format: date-time)

The time the order was placed. This is the time the order was submitted to the brokerage.

time_updatedstring (format: date-time) or null

The time the order was last updated in the brokerage system. This value is not always available from the brokerage.

time_executedstring (format: date-time) or null

The time the order was executed in the brokerage system. This value is not always available from the brokerage.

expiry_datestring (format: date-time) or null

The time the order expires. This value is not always available from the brokerage.

symbolstring (format: uuid)

Deprecated

Refrain from usage of this field

total_valueobject

Deprecated

Refrain from usage of this field

This field is deprecated. To get the brokerage reported total market value of the account, please refer to account.balance.total.

The total market value of the account. Note that this field is calculated based on the sum of the values of account positions and cash balances known to SnapTrade. It may not be accurate if the brokerage account has holdings that SnapTrade is not aware of. For example, if the brokerage account holds assets that SnapTrade does not support, the total value may be underreported. In certain cases, this value may also be double-counting cash-equivalent assets if those assets are represented as both cash and positions in the account.

1
{
2
  "account": {
3
    "id": "917c8734-8470-4a3e-a18f-57c3f2ee6631",
4
    "brokerage_authorization": "87b24961-b51e-4db8-9226-f198f6518a89",
5
    "name": "Robinhood Individual",
6
    "number": "Q6542138443",
7
    "institution_name": "Robinhood",
8
    "created_date": "2024-07-23T22:50:22.761Z",
9
    "sync_status": {
10
      "transactions": {
11
        "initial_sync_completed": true,
12
        "last_successful_sync": "2022-01-24",
13
        "first_transaction_date": "2022-01-24"
14
      },
15
      "holdings": {
16
        "initial_sync_completed": true,
17
        "last_successful_sync": "2024-06-28 18:42:46.561408+00:00"
18
      }
19
    },
20
    "balance": {
21
      "total": {
22
        "amount": 15363.23,
23
        "currency": "USD"
24
      }
25
    },
26
    "meta": {
27
      "type": "Margin",
28
      "status": "ACTIVE",
29
      "institution_name": "Robinhood"
30
    },
31
    "portfolio_group": "2bcd7cc3-e922-4976-bce1-9858296801c3",
32
    "cash_restrictions": []
33
  },
34
  "balances": [
35
    {
36
      "currency": {
37
        "id": "87b24961-b51e-4db8-9226-f198f6518a89",
38
        "code": "USD",
39
        "name": "US Dollar"
40
      },
41
      "cash": 300.71,
42
      "buying_power": 410.71
43
    }
44
  ],
45
  "positions": [
46
    {
47
      "symbol": {
48
        "symbol": {
49
          "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
50
          "symbol": "VAB.TO",
51
          "raw_symbol": "VAB",
52
          "description": "VANGUARD CDN AGGREGATE BOND INDEX ETF",
53
          "currency": {
54
            "id": "87b24961-b51e-4db8-9226-f198f6518a89",
55
            "code": "USD",
56
            "name": "US Dollar"
57
          },
58
          "exchange": {
59
            "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
60
            "code": "TSX",
61
            "mic_code": "XTSE",
62
            "name": "Toronto Stock Exchange",
63
            "timezone": "America/New_York",
64
            "start_time": "09:30:00",
65
            "close_time": "16:00:00",
66
            "suffix": ".TO"
67
          },
68
          "type": {
69
            "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
70
            "code": "cs",
71
            "description": "Common Stock",
72
            "is_supported": true
73
          },
74
          "figi_code": "BBG000B9XRY4",
75
          "figi_instrument": {
76
            "figi_code": "BBG000B9Y5X2",
77
            "figi_share_class": "BBG001S5N8V8"
78
          },
79
          "currencies": [
80
            {
81
              "id": "87b24961-b51e-4db8-9226-f198f6518a89",
82
              "code": "USD",
83
              "name": "US Dollar"
84
            }
85
          ]
86
        },
87
        "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
88
        "description": "VANGUARD CDN AGGREGATE BOND INDEX ETF",
89
        "local_id": "3291231",
90
        "is_quotable": true,
91
        "is_tradable": true
92
      },
93
      "units": 40,
94
      "price": 113.15,
95
      "open_pnl": 0.44,
96
      "average_purchase_price": 108.3353,
97
      "fractional_units": 1.44
98
    }
99
  ],
100
  "option_positions": [
101
    {
102
      "symbol": {
103
        "option_symbol": {
104
          "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
105
          "ticker": "AAPL  261218C00240000",
106
          "option_type": "CALL",
107
          "strike_price": 240,
108
          "expiration_date": "2026-12-18",
109
          "is_mini_option": false,
110
          "underlying_symbol": {
111
            "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
112
            "symbol": "SPY",
113
            "raw_symbol": "VAB",
114
            "description": "SPDR S&P 500 ETF Trust",
115
            "currency": {
116
              "id": "87b24961-b51e-4db8-9226-f198f6518a89",
117
              "code": "USD",
118
              "name": "US Dollar"
119
            },
120
            "exchange": {
121
              "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
122
              "code": "ARCX",
123
              "mic_code": "ARCA",
124
              "name": "NYSE ARCA",
125
              "timezone": "America/New_York",
126
              "start_time": "09:30:00",
127
              "close_time": "16:00:00",
128
              "suffix": "None",
129
              "allows_cryptocurrency_symbols": false
130
            },
131
            "type": {
132
              "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
133
              "code": "cs",
134
              "description": "Common Stock",
135
              "is_supported": true
136
            },
137
            "figi_code": "BBG000B9XRY4",
138
            "figi_instrument": {
139
              "figi_code": "BBG000B9Y5X2",
140
              "figi_share_class": "BBG001S5N8V8"
141
            },
142
            "currencies": [
143
              {
144
                "id": "87b24961-b51e-4db8-9226-f198f6518a89",
145
                "code": "USD",
146
                "name": "US Dollar"
147
              }
148
            ]
149
          }
150
        },
151
        "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
152
        "description": "SPY CALL 7/17 200"
153
      },
154
      "price": 38.4,
155
      "units": -50,
156
      "average_purchase_price": 4126,
157
      "currency": {
158
        "id": "87b24961-b51e-4db8-9226-f198f6518a89",
159
        "code": "USD",
160
        "name": "US Dollar"
161
      }
162
    }
163
  ],
164
  "orders": [
165
    {
166
      "brokerage_order_id": "66a033fa-da74-4fcf-b527-feefdec9257e",
167
      "status": "NONE",
168
      "universal_symbol": {
169
        "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
170
        "symbol": "VAB.TO",
171
        "raw_symbol": "VAB",
172
        "description": "VANGUARD CDN AGGREGATE BOND INDEX ETF",
173
        "currency": {
174
          "id": "87b24961-b51e-4db8-9226-f198f6518a89",
175
          "code": "USD",
176
          "name": "US Dollar"
177
        },
178
        "exchange": {
179
          "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
180
          "code": "TSX",
181
          "mic_code": "XTSE",
182
          "name": "Toronto Stock Exchange",
183
          "timezone": "America/New_York",
184
          "start_time": "09:30:00",
185
          "close_time": "16:00:00",
186
          "suffix": ".TO"
187
        },
188
        "type": {
189
          "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
190
          "code": "cs",
191
          "description": "Common Stock",
192
          "is_supported": true
193
        },
194
        "figi_code": "BBG000B9XRY4",
195
        "figi_instrument": {
196
          "figi_code": "BBG000B9Y5X2",
197
          "figi_share_class": "BBG001S5N8V8"
198
        },
199
        "currencies": [
200
          {
201
            "id": "87b24961-b51e-4db8-9226-f198f6518a89",
202
            "code": "USD",
203
            "name": "US Dollar"
204
          }
205
        ]
206
      },
207
      "option_symbol": {
208
        "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
209
        "ticker": "AAPL  261218C00240000",
210
        "option_type": "CALL",
211
        "strike_price": 240,
212
        "expiration_date": "2026-12-18",
213
        "is_mini_option": false,
214
        "underlying_symbol": {
215
          "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
216
          "symbol": "SPY",
217
          "raw_symbol": "VAB",
218
          "description": "SPDR S&P 500 ETF Trust",
219
          "currency": {
220
            "id": "87b24961-b51e-4db8-9226-f198f6518a89",
221
            "code": "USD",
222
            "name": "US Dollar"
223
          },
224
          "exchange": {
225
            "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
226
            "code": "ARCX",
227
            "mic_code": "ARCA",
228
            "name": "NYSE ARCA",
229
            "timezone": "America/New_York",
230
            "start_time": "09:30:00",
231
            "close_time": "16:00:00",
232
            "suffix": "None",
233
            "allows_cryptocurrency_symbols": false
234
          },
235
          "type": {
236
            "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
237
            "code": "cs",
238
            "description": "Common Stock",
239
            "is_supported": true
240
          },
241
          "figi_code": "BBG000B9XRY4",
242
          "figi_instrument": {
243
            "figi_code": "BBG000B9Y5X2",
244
            "figi_share_class": "BBG001S5N8V8"
245
          },
246
          "currencies": [
247
            {
248
              "id": "87b24961-b51e-4db8-9226-f198f6518a89",
249
              "code": "USD",
250
              "name": "US Dollar"
251
            }
252
          ]
253
        }
254
      },
255
      "action": "string",
256
      "total_quantity": 100,
257
      "open_quantity": 10,
258
      "canceled_quantity": 10,
259
      "filled_quantity": 80,
260
      "execution_price": 12.34,
261
      "limit_price": 12.34,
262
      "stop_price": 12.5,
263
      "order_type": "Market",
264
      "time_in_force": "string",
265
      "time_placed": "2024-07-30T22:51:49.746Z",
266
      "time_updated": "2024-08-05T00:05:57.409Z",
267
      "time_executed": "2024-08-05T00:05:57.409Z",
268
      "expiry_date": "2024-08-05T00:05:57.409Z",
269
      "symbol": "2bcd7cc3-e922-4976-bce1-9858296801c3"
270
    }
271
  ],
272
  "total_value": {
273
    "value": 32600.71,
274
    "currency": "USD"
275
  }
276
}

Made with Konfig