SnapTrade Reference Data API

openapi: 3.2.0
info:
  description: 'Connect brokerage accounts to your app for live positions and trading.


    ## Rate limiting


    Two limits apply to requests signed with your `clientId`. The stricter one

    wins, and exceeding either returns `429 Too Many Requests`.


    - **Customer-level** — 250 requests/minute by default, scoped to your

    `clientId` and applied across all endpoints. Reported in

    `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.

    - **Account-level** — 10 requests/minute per account, scoped to

    (`clientId`, `accountId`). All covered operations for one account draw on

    the same bucket — reading balances and reading positions share it — and

    enforcement does not depend on the HTTP method, so updating an account

    consumes the same bucket as reading it. Only enforced for Personal users,

    and only for integrations it has been rolled out to — it is not yet in

    force for every Personal integration. It also does not apply on every

    operation that documents a 429 below. Where it applies it is reported in

    `X-RateLimit-Account-Limit`, `X-RateLimit-Account-Remaining` and

    `X-RateLimit-Account-Reset`. Do not read the absence of those headers as

    proof the limit is off — some configurations omit the rate limit headers

    while still enforcing the limit, so header absence tells you nothing

    about your allowance.


    On a 429, `X-RateLimit-Remaining: 0` means you hit the customer-level limit

    and `X-RateLimit-Account-Remaining: 0` means the account-level one. Wait for

    the corresponding `*-Reset` value (seconds) before retrying, or fall back to

    exponential backoff with jitter.


    Not every 429 is explained by those headers. A separate

    per-authenticated-user limit, reported in no `X-RateLimit-*` header, covers

    OAuth-authenticated requests and signed requests in configurations where the

    customer-level limit is not in effect — on the operations that use the

    default throttles. A few operations override those and are governed by the

    customer-level limit alone. The two do not stack: a signed request

    governed by the customer-level limit above is not additionally subject to the

    per-user one. If a 429 arrives with no header at zero — or with no

    `X-RateLimit-*` headers at all — honour `Retry-After` and back off. Treat the

    remaining counts as a hint, not a guarantee that the next request will

    succeed.


    Because the customer-level limit applies everywhere, any signed request can

    return 429.


    **OAuth-authenticated requests are an exception.** They are not subject to

    the customer-level limit and do not receive `X-RateLimit-Limit`,

    `X-RateLimit-Remaining` or `X-RateLimit-Reset` — do not wait on those headers

    or design around a customer-level allowance on this path. The account-level

    limit still applies to them on the account-data endpoints above, reported in

    the `X-RateLimit-Account-*` headers. On operations using the default

    throttles the per-user limit above applies to them as well, so an OAuth

    request can be rejected while the account headers still show capacity; on

    the few operations that override those throttles, OAuth callers have no

    per-user ceiling at all. Drive retries from `Retry-After` and exponential

    backoff with jitter rather than from the headers.


    See https://docs.snaptrade.com/docs/ratelimiting.'
  version: 1.0.0
  title: SnapTrade Reference Data API
  termsOfService: N/A
  contact:
    email: api@snaptrade.com
  x-konfig-ignore:
    potential-incorrect-type: true
  x-readme:
    explorer-enabled: false
servers:
- description: SnapTrade Production API
  url: https://api.snaptrade.com
security:
- PartnerSignature: []
  PartnerClientId: []
  PartnerTimestamp: []
tags:
- name: Reference Data
  description: Retrieve basic information for API use, such as supported brokerages, exchanges, currencies, etc.
paths:
  /snapTrade/partners:
    get:
      tags:
      - Reference Data
      summary: Get Client Info
      description: Returns configurations for your SnapTrade Client ID, including allowed brokerages and data access.
      operationId: ReferenceData_getPartnerInfo
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerData'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400FailedRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401FailedRequestResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404FailedRequestResponse'
        '500':
          description: Unexpected Error
  /accounts/{accountId}/symbols:
    post:
      tags:
      - Reference Data
      summary: Search account symbols
      description: 'Returns a list of Universal Symbol objects that match the given query. The matching takes into consideration both the ticker and the name of the symbol. Only the first 20 results are returned.


        The search results are further limited to the symbols supported by the brokerage for which the account is under.'
      operationId: ReferenceData_symbolSearchUserAccount
      parameters:
      - in: query
        required: true
        name: userId
        schema:
          $ref: '#/components/schemas/UserID'
      - in: query
        required: true
        name: userSecret
        schema:
          $ref: '#/components/schemas/UserSecret'
      - in: path
        name: accountId
        required: true
        schema:
          $ref: '#/components/schemas/AccountID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SymbolQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: A list of Universal Symbol objects that match the given query.
                items:
                  $ref: '#/components/schemas/UniversalSymbol'
        default:
          description: Unexpected Error
  /brokerages/{slug}/instruments:
    get:
      tags:
      - Reference Data
      summary: Get brokerage instruments
      description: Returns a list of all brokerage instruments available for a given brokerage. Not all brokerages support this. The ones that don't will return an empty list.
      operationId: ReferenceData_listAllBrokerageInstruments
      parameters:
      - in: path
        name: slug
        required: true
        description: A short, unique identifier for the brokerage. It is usually the name of the brokerage in capital letters and will never change.
        schema:
          type: string
          example: QUESTRADE
      responses:
        '200':
          description: A list of brokerage instruments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrokerageInstrumentsResponse'
        default:
          description: Unexpected error.
  /symbols:
    post:
      tags:
      - Reference Data
      summary: Search symbols
      description: Returns a list of Universal Symbol objects that match the given query. The matching takes into consideration both the ticker and the name of the symbol. Only the first 20 results are returned.
      operationId: ReferenceData_getSymbols
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: A list of Universal Symbol objects that match the given query.
                items:
                  $ref: '#/components/schemas/UniversalSymbol'
        default:
          description: Unexpected Error
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SymbolQuery'
  /symbols/{query}:
    get:
      tags:
      - Reference Data
      summary: Get symbol detail
      description: 'Returns the Universal Symbol object specified by the ticker or the Universal Symbol ID. When a ticker is specified, the first matching result is returned. 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. Share classes and preferred series use SnapTrade''s canonical dotted form: use `HBND.U.TO` (not Yahoo''s `HBND-U.TO`), `FTN.PR.A.TO` (not `FTN-PA.TO`), and `ECF.PRA` (not `ECF-P-A`). Please use the ticker with the proper suffix and canonical share-class notation for the best results.'
      operationId: ReferenceData_getSymbolsByTicker
      parameters:
      - in: path
        name: query
        required: true
        description: The ticker or Universal Symbol ID to look up the symbol with.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniversalSymbol'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404FailedRequestResponse'
        default:
          description: Unexpected Error
components:
  schemas:
    AccountID:
      description: Unique identifier for the connected brokerage account. This is the UUID used to reference the account in SnapTrade.
      type: string
      format: uuid
      example: 917c8734-8470-4a3e-a18f-57c3f2ee6631
    BrokerageInstrument:
      type: object
      required:
      - symbol
      properties:
        symbol:
          description: The instrument's trading symbol / ticker.
          type: string
          example: AAPL
        exchange_mic:
          description: The MIC code of the exchange where the instrument is traded.
          type:
          - string
          - 'null'
          example: XNAS
        tradeable:
          description: Whether the instrument is tradeable through the brokerage. `null` if the tradeability is unknown.
          type:
          - boolean
          - 'null'
          example: true
        fractionable:
          description: Whether the instrument allows fractional units. `null` if the fractionability is unknown.
          type:
          - boolean
          - 'null'
          example: true
        universal_symbol_id:
          description: The universal symbol ID of the instrument. This is the ID used to reference the instrument in SnapTrade API calls.
          type:
          - string
          - 'null'
          format: uuid
          example: 2bcd7cc3-e922-4976-bce1-9858296801c3
    Exchange:
      description: Describes a single stock or crypto exchange.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ExchangeID'
        code:
          description: A short name for the exchange. For standardized exchange code, please use the `mic_code` field.
          type: string
          example: TSX
        mic_code:
          description: The [Market Identifier Code](https://en.wikipedia.org/wiki/Market_Identifier_Code) (MIC) for the exchange.
          type:
          - string
          - 'null'
          example: XTSE
        name:
          description: The full name of the exchange.
          type: string
          example: Toronto Stock Exchange
        timezone:
          description: The timezone for the trading hours (`start_time` and `close_time`) of the exchange.
          type: string
          example: America/New_York
        start_time:
          description: The time when the exchange opens for trading.
          type: string
          example: 09:30:00
        close_time:
          description: The time when the exchange closes for trading.
          type: string
          example: '16:00:00'
        suffix:
          description: The suffix to be appended to the symbol when trading on this exchange. For example, the suffix for the Toronto Stock Exchange is `.TO`. See `UniversalSymbol->symbol` and `UniversalSymbol->raw_symbol` for more detail.
          type:
          - string
          - 'null'
          example: .TO
    UniversalSymbol:
      description: Uniquely describes a single security + exchange combination across all brokerages.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UniversalSymbolID'
        symbol:
          description: The security's trading ticker symbol. For example "AAPL" for Apple Inc. We largely follow the [Yahoo Finance ticker format](https://help.yahoo.com/kb/SLN2310.html)(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. Share classes and preferred series use SnapTrade's canonical dotted form, for example `HBND.U.TO`, `FTN.PR.A.TO`, and `ECF.PRA`.
          type: string
          example: VAB.TO
        raw_symbol:
          description: The raw symbol is `symbol` with the exchange suffix removed. For example, if `symbol` is "VAB.TO", then `raw_symbol` is "VAB".
          type: string
          example: VAB
        description:
          description: A human-readable description of the security. This is usually the company name or ETF name.
          type:
          - string
          - 'null'
          example: VANGUARD CDN AGGREGATE BOND INDEX ETF
        currency:
          description: The currency in which the security is traded.
          allOf:
          - $ref: '#/components/schemas/Currency'
        exchange:
          description: The exchange on which the security is listed and traded.
          allOf:
          - $ref: '#/components/schemas/Exchange'
        type:
          $ref: '#/components/schemas/SecurityType'
        figi_code:
          description: This identifier is unique per security per trading venue. See section 1.4.1 of the [FIGI Standard](https://www.openfigi.com/assets/local/figi-allocation-rules.pdf) for more information. This value should be the same as the `figi_code` in the `figi_instrument` child property.
          type:
          - string
          - 'null'
          example: BBG000B9XRY4
        figi_instrument:
          allOf:
          - $ref: '#/components/schemas/FigiInstrument'
        currencies:
          deprecated: true
          description: This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid use case for this.
          type: array
          items:
            $ref: '#/components/schemas/Currency'
      required:
      - id
      - symbol
      - raw_symbol
      - currency
      - type
      - currencies
    UniversalSymbolID:
      description: Unique identifier for the symbol within SnapTrade. This is the ID used to reference the symbol in SnapTrade API calls.
      type: string
      format: uuid
      example: 2bcd7cc3-e922-4976-bce1-9858296801c3
    Currency:
      description: Describes a currency object.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CurrencyID'
        code:
          type: string
          description: The ISO-4217 currency code for the currency.
          example: USD
        name:
          type: string
          description: A human-friendly name of the currency.
          example: US Dollar
    400FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: Unable to verify data sent
        default_code:
          example: 1076
    UserSecret:
      description: 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](/reference/Authentication/Authentication_resetSnapTradeUserSecret).
      type: string
      example: adf2aa34-8219-40f7-a6b3-60156985cc61
    Id:
      type: string
      format: uuid
      example: 2bcd7cc3-e922-4976-bce1-9858296801c3
    404FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: The requested resource does not exist.
        default_code:
          example: 1011
    BrokerageType:
      description: Type of brokerage. Currently supports traditional brokerages and crypto exchanges.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          type: string
          example: Traditional Brokerage
    UserID:
      description: 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.
      type: string
      example: snaptrade-user-123
    PartnerData:
      description: Configurations for your SnapTrade Client ID, including allowed brokerages and data access.
      type: object
      properties:
        slug:
          type: string
          description: A short, unique identifier for your company or product.
          example: WEALTHLY
        name:
          type: string
          description: Your company or product name.
          example: Wealthly
        logo_url:
          type:
          - string
          - 'null'
          description: URL to your company or product logo. Returns null if no logo has been configured (always the case for personal access clients).
          example: https://example.com/logo.png
        allowed_brokerages:
          type: array
          description: Brokerages that can be accessed by your Client ID.
          items:
            $ref: '#/components/schemas/Brokerage'
        can_access_trades:
          type: boolean
          description: Whether trading is enabled for your SnapTrade Client ID.
          example: true
        can_access_holdings:
          type: boolean
          description: Whether holdings data is enabled for your SnapTrade Client ID.
          example: true
        can_access_account_history:
          type: boolean
          description: Whether account historical transactions is enabled for your SnapTrade Client ID.
          example: true
        can_access_reference_data:
          type: boolean
          description: Whether reference data is enabled for your SnapTrade Client ID.
          example: true
        can_access_portfolio_management:
          type: boolean
          description: Whether portfolio management is enabled for your SnapTrade Client ID.
          example: true
        can_access_orders:
          type: boolean
          description: Whether recent order history is enabled for your SnapTrade Client ID.
          example: true
        redirect_uri:
          type:
          - string
          - 'null'
          description: URI to redirect user back to after user is done adding brokerage connections. Returns null if no redirect URI has been configured (always the case for personal access clients).
          example: https://example.com/oauth/snaptrade
        pin_required:
          deprecated: true
          type: boolean
          description: Shows if pin is required by users to access connection page. This field has been deprecated.
          example: false
    BrokerageInstrumentsResponse:
      type: object
      properties:
        instruments:
          type: array
          items:
            $ref: '#/components/schemas/BrokerageInstrument'
    Brokerage:
      description: Describes a brokerage that SnapTrade supports.
      type: object
      properties:
        id:
          description: Unique identifier for the brokerage firm. This is the UUID used to reference the brokerage in SnapTrade.
          type: string
          format: uuid
          example: ebf91a5b-0920-4266-9e36-f6cfe8c40946
        slug:
          description: A short, unique identifier for the brokerage. It is usually the name of the brokerage in capital letters and will never change.
          type: string
          example: ROBINHOOD
        name:
          description: Full name of the brokerage.
          type: string
          example: Robinhood
        display_name:
          description: A display-friendly name of the brokerage.
          type: string
          example: Robinhood
        description:
          description: A brief description of the brokerage.
          type: string
          example: Robinhood is an American multinational financial services corporation based in Menlo Park, California.
        aws_s3_logo_url:
          description: URL to the brokerage's logo.
          type: string
          format: url
          example: https://passiv-brokerage-logos.s3.ca-central-1.amazonaws.com/robinhood-logo.png
        aws_s3_square_logo_url:
          description: URL to the brokerage's logo in square format.
          type:
          - string
          - 'null'
          format: url
          example: https://passiv-brokerage-logos.s3.ca-central-1.amazonaws.com/robinhood-logo-square.png
        url:
          description: URL to the brokerage's website. Returns null if the brokerage has no website on record.
          type:
          - string
          - 'null'
          format: url
          example: https://robinhood.com
        enabled:
          description: Whether the brokerage is enabled in SnapTrade. A disabled brokerage will not be available for new connections.
          type: boolean
          example: true
        maintenance_mode:
          description: Whether the brokerage is currently in maintenance mode. A brokerage in maintenance mode will not be available for new connections.
          type: boolean
          example: true
        is_degraded:
          description: Whether the brokerage is currently degraded. A degraded brokerage may have reduced functionality or be experiencing technical issues.
          type: boolean
          example: true
        allows_trading:
          description: Whether the brokerage allows trading through SnapTrade.
          type:
          - boolean
          - 'null'
          example: true
        allows_fractional_units:
          deprecated: true
          description: This field is deprecated. Please contact us if you have a valid use case for it.
          type:
          - boolean
          - 'null'
          example: true
        has_reporting:
          deprecated: true
          description: This field is deprecated. Please contact us if you have a valid use case for it.
          type:
          - boolean
          - 'null'
          example: true
        is_real_time_connection:
          deprecated: true
          description: This field is deprecated. Please contact us if you have a valid use case for it.
          type: boolean
          example: true
        brokerage_type:
          $ref: '#/components/schemas/BrokerageType'
        exchanges:
          deprecated: true
          description: This field is deprecated. Please contact us if you have a valid use case for it.
          type: array
          items: {}
          example:
          - 2bcd7cc3-e922-4976-bce1-9858296801c3
          - 4bcd8cc3-c122-4974-dc21-1858296801f4
        open_url:
          deprecated: true
          description: This field is deprecated.
          type:
          - string
          - 'null'
          format: url
    FigiInstrument:
      description: Financial Instrument Global Identifier (FIGI) information for the security. See [OpenFIGI](https://www.openfigi.com/) for more information.
      type: object
      properties:
        figi_code:
          description: This identifier is unique per security per trading venue. See section 1.4.1 of the [FIGI Standard](https://www.openfigi.com/assets/local/figi-allocation-rules.pdf) for more information.
          type:
          - string
          - 'null'
          example: BBG000B9Y5X2
        figi_share_class:
          description: This enables users to link multiple FIGIs for the same security in order to obtain an aggregated view across all countries and all exchanges. For example, `AAPL` has a different FIGI for each exchange/trading venue it is traded on. The `figi_share_class` is the same for all of these FIGIs. See section 1.4.3 of the [FIGI Standard](https://www.openfigi.com/assets/local/figi-allocation-rules.pdf) for more information.
          type:
          - string
          - 'null'
          example: BBG001S5N8V8
    SecurityType:
      type: object
      description: The type of security. For example, "Common Stock" or "ETF".
      properties:
        id:
          $ref: '#/components/schemas/SecurityTypeID'
        code:
          description: "A short code representing the security type. For example, \"cs\" for Common Stock. Here are some common values:\n  - `ad` - ADR\n  - `bnd` - Bond\n  - `cs` - Common Stock\n  - `cef` - Closed End Fund\n  - `crypto` - Cryptocurrency\n  - `et` - ETF\n  - `oef` - Open Ended Fund\n  - `pm` - Precious Metals\n  - `ps` - Preferred Stock\n  - `rt` - Right\n  - `struct` - Structured Product\n  - `ut` - Unit\n  - `wi` - When Issued\n  - `wt` - Warrant\n"
          type: string
          example: cs
        description:
          description: A human-readable description of the security type. For example, "Common Stock" or "ETF".
          type: string
          example: Common Stock
        is_supported:
          deprecated: true
          description: This field is deprecated and should not be used. Please reach out to SnapTrade support if you have a valid use case for this.
          type: boolean
          example: true
    SymbolQuery:
      type: object
      properties:
        substring:
          description: The search query for symbols.
          type: string
          example: AAPL
    CurrencyID:
      type: string
      format: uuid
      description: Unique identifier for the currency. This is the UUID used to reference the currency in SnapTrade.
      example: 87b24961-b51e-4db8-9226-f198f6518a89
    401FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: Unable to verify signature sent
        default_code:
          example: 1076
    ExchangeID:
      description: Unique ID for the exchange in SnapTrade.
      type: string
      format: uuid
      example: 2bcd7cc3-e922-4976-bce1-9858296801c3
    SecurityTypeID:
      description: Unique identifier for the security type within SnapTrade. This is the ID used to reference the security type in SnapTrade API calls.
      type: string
      format: uuid
      example: 2bcd7cc3-e922-4976-bce1-9858296801c3
  securitySchemes:
    PartnerSignature:
      type: apiKey
      in: header
      name: Signature
    PartnerClientId:
      type: apiKey
      in: query
      name: clientId
    PartnerTimestamp:
      type: apiKey
      in: query
      name: timestamp