{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/snaptrade/main/json-schema/snaptrade-universal-symbol-schema.json",
  "title": "UniversalSymbol",
  "description": "Uniquely describes a single security + exchange combination across all brokerages.",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/snaptrade-openapi.yml#/components/schemas/UniversalSymbol",
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/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"
    },
    "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"
    },
    "description": {
      "description": "A human-readable description of the security. This is usually the company name or ETF name.",
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "description": "The currency in which the security is traded.",
      "allOf": [
        {
          "$ref": "#/$defs/Currency"
        }
      ]
    },
    "exchange": {
      "description": "The exchange on which the security is listed and traded.",
      "allOf": [
        {
          "$ref": "#/$defs/Exchange"
        }
      ]
    },
    "type": {
      "$ref": "#/$defs/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"
      ]
    },
    "figi_instrument": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/Currency"
      }
    }
  },
  "required": [
    "id",
    "symbol",
    "raw_symbol",
    "currency",
    "type",
    "currencies"
  ],
  "$defs": {
    "Currency": {
      "description": "Describes a currency object.",
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/CurrencyID"
        },
        "code": {
          "type": "string",
          "description": "The ISO-4217 currency code for the currency."
        },
        "name": {
          "type": "string",
          "description": "A human-friendly name of the currency."
        }
      }
    },
    "CurrencyID": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the currency. This is the UUID used to reference the currency in SnapTrade."
    },
    "Exchange": {
      "description": "Describes a single stock or crypto exchange.",
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/ExchangeID"
        },
        "code": {
          "description": "A short name for the exchange. For standardized exchange code, please use the `mic_code` field.",
          "type": "string"
        },
        "mic_code": {
          "description": "The [Market Identifier Code](https://en.wikipedia.org/wiki/Market_Identifier_Code) (MIC) for the exchange.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "The full name of the exchange.",
          "type": "string"
        },
        "timezone": {
          "description": "The timezone for the trading hours (`start_time` and `close_time`) of the exchange.",
          "type": "string"
        },
        "start_time": {
          "description": "The time when the exchange opens for trading.",
          "type": "string"
        },
        "close_time": {
          "description": "The time when the exchange closes for trading.",
          "type": "string"
        },
        "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"
          ]
        }
      }
    },
    "ExchangeID": {
      "description": "Unique ID for the exchange in SnapTrade.",
      "type": "string",
      "format": "uuid"
    },
    "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"
          ]
        },
        "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"
          ]
        }
      }
    },
    "SecurityType": {
      "type": "object",
      "description": "The type of security. For example, \"Common Stock\" or \"ETF\".",
      "properties": {
        "id": {
          "$ref": "#/$defs/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"
        },
        "description": {
          "description": "A human-readable description of the security type. For example, \"Common Stock\" or \"ETF\".",
          "type": "string"
        },
        "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"
        }
      }
    },
    "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"
    },
    "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"
    }
  }
}