diff --git a/openapi/paths/crypto.yaml b/openapi/paths/crypto.yaml new file mode 100644 index 0000000..96e4cd3 --- /dev/null +++ b/openapi/paths/crypto.yaml @@ -0,0 +1,271 @@ +# Crypto API Endpoints for Tiingo API +# Reference: https://www.tiingo.com/documentation/crypto + +crypto-prices: &crypto-prices + get: + summary: Get cryptocurrency prices + description: | + Get real-time and historical cryptocurrency prices. Returns meta information about the crypto pair + along with OHLCV price data. Without startDate, returns latest data for the current or last business day. + With startDate, returns historical intraday data. + + The response includes consolidated data from multiple exchanges, with optional raw exchange-level data + when includeRawExchangeData is enabled. + operationId: getCryptoPrices + tags: + - Crypto + parameters: + - name: tickers + in: query + required: true + schema: + type: string + pattern: '^[a-z0-9]+(,[a-z0-9]+)*$' + description: Comma-separated list of crypto tickers + example: 'btcusd,fldcbtc' + - name: startDate + in: query + required: false + schema: + type: string + format: date + pattern: '^\d{4}-\d{2}-\d{2}$' + description: Start date for historical data in YYYY-MM-DD format + example: '2019-01-02' + - name: endDate + in: query + required: false + schema: + type: string + format: date + pattern: '^\d{4}-\d{2}-\d{2}$' + description: End date for historical data in YYYY-MM-DD format + example: '2019-12-31' + - name: resampleFreq + in: query + required: false + schema: + type: string + pattern: '^[0-9]+(min|hour|day)$' + enum: + - '1min' + - '5min' + - '15min' + - '30min' + - '1hour' + - '2hour' + - '4hour' + - '1day' + description: Resampling frequency for historical data (e.g., 5min, 1hour, 1day) + example: '5min' + - name: includeRawExchangeData + in: query + required: false + schema: + type: boolean + default: false + description: Include raw exchange-level data in the response + example: true + - $ref: '../parameters/_index.yaml#/TokenParam' + responses: + '200': + description: Successful response with cryptocurrency price data + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/crypto-schemas.yaml#/CryptoPrice' + examples: + latest-price: + summary: Latest price data + description: Get current/latest price for Bitcoin + value: + - ticker: 'btcusd' + baseCurrency: 'btc' + quoteCurrency: 'usd' + priceData: + - date: '2019-01-02T00:00:00.000Z' + close: 3610.32 + high: 3701.0 + low: 3600.65 + open: 3690.01 + volume: 1234.56 + volumeNotional: 4456789.12 + tradesDone: 5000 + historical-prices: + summary: Historical price data with 5-minute resampling + description: Get historical intraday data for Bitcoin with 5-minute intervals + value: + - ticker: 'btcusd' + baseCurrency: 'btc' + quoteCurrency: 'usd' + priceData: + - date: '2019-01-02T00:00:00.000Z' + close: 3610.32 + high: 3701.0 + low: 3600.65 + open: 3690.01 + volume: 1234.56 + volumeNotional: 4456789.12 + tradesDone: 5000 + - date: '2019-01-02T00:05:00.000Z' + close: 3615.50 + high: 3620.0 + low: 3610.0 + open: 3610.32 + volume: 567.89 + volumeNotional: 2052345.67 + tradesDone: 2345 + '400': + $ref: '../responses/_index.yaml#/BadRequest' + '401': + $ref: '../responses/_index.yaml#/Unauthorized' + '404': + $ref: '../responses/_index.yaml#/NotFound' + '429': + $ref: '../responses/_index.yaml#/TooManyRequests' + '500': + $ref: '../responses/_index.yaml#/InternalServerError' + +crypto-meta: &crypto-meta + get: + summary: Get cryptocurrency metadata + description: | + Get metadata information for cryptocurrencies including ticker, base/quote currencies, name, and description. + + Without the tickers parameter, returns metadata for all available cryptocurrencies. + With the tickers parameter, returns metadata only for the specified tickers. + operationId: getCryptoMetadata + tags: + - Crypto + parameters: + - name: tickers + in: query + required: false + schema: + type: string + pattern: '^[a-z0-9]+(,[a-z0-9]+)*$' + description: Comma-separated list of crypto tickers to filter by. If omitted, returns all tickers. + example: 'btcusd,ethusd' + - $ref: '../parameters/_index.yaml#/TokenParam' + responses: + '200': + description: Successful response with cryptocurrency metadata + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/crypto-schemas.yaml#/CryptoMetadata' + examples: + bitcoin-metadata: + summary: Bitcoin metadata + description: Get metadata for Bitcoin + value: + - ticker: 'btcusd' + baseCurrency: 'btc' + quoteCurrency: 'usd' + name: 'Bitcoin' + description: 'Bitcoin is a cryptocurrency and worldwide payment system.' + multiple-metadata: + summary: Multiple cryptocurrency metadata + description: Get metadata for Bitcoin and Ethereum + value: + - ticker: 'btcusd' + baseCurrency: 'btc' + quoteCurrency: 'usd' + name: 'Bitcoin' + description: 'Bitcoin is a cryptocurrency and worldwide payment system.' + - ticker: 'ethusd' + baseCurrency: 'eth' + quoteCurrency: 'usd' + name: 'Ethereum' + description: 'Ethereum is a decentralized platform for smart contracts.' + '400': + $ref: '../responses/_index.yaml#/BadRequest' + '401': + $ref: '../responses/_index.yaml#/Unauthorized' + '404': + $ref: '../responses/_index.yaml#/NotFound' + '429': + $ref: '../responses/_index.yaml#/TooManyRequests' + '500': + $ref: '../responses/_index.yaml#/InternalServerError' + +crypto-top: &crypto-top + get: + summary: Get cryptocurrency top-of-book data (DEPRECATED) + description: | + **DEPRECATED**: This endpoint has been deprecated and may be removed in a future version. + + Tiingo has deprecated the top-of-book endpoint due to reliability issues with cryptocurrency exchange feeds. + The feeds have been found unreliable for constructing consistent best bid/ask data across 60+ exchanges. + Issues include inconsistent timestamps, improperly ordered messages, and varying exchange-specific quirks. + + For last price information, use the `/tiingo/crypto/prices` endpoint instead. + + This endpoint returns top-of-book data including bid/ask prices, last trade information, and optional + raw exchange-level data. While the endpoint remains available, it should not be used for production systems. + operationId: getCryptoTopOfBook + deprecated: true + tags: + - Crypto + parameters: + - name: tickers + in: query + required: true + schema: + type: string + pattern: '^[a-z0-9]+(,[a-z0-9]+)*$' + description: Comma-separated list of crypto tickers + example: 'btcusd,ethusd' + - name: includeRawExchangeData + in: query + required: false + schema: + type: boolean + default: false + description: Include raw exchange-level top-of-book data in the response + example: true + - $ref: '../parameters/_index.yaml#/TokenParam' + responses: + '200': + description: Successful response with top-of-book data (DEPRECATED) + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/crypto-schemas.yaml#/CryptoTopOfBook' + examples: + bitcoin-top-of-book: + summary: Bitcoin top-of-book data + description: Get top-of-book data for Bitcoin + value: + - ticker: 'btcusd' + baseCurrency: 'btc' + quoteCurrency: 'usd' + topOfBookData: + quoteTimestamp: '2019-01-02T12:34:56.789Z' + lastSaleTimestamp: '2019-01-02T12:34:56.789Z' + lastPrice: 3610.32 + lastSize: 0.5 + lastSizeNotional: 1805.16 + lastExchange: 'Coinbase' + bidSize: 1.2 + bidPrice: 3609.50 + bidExchange: 'Binance' + askSize: 0.8 + askPrice: 3611.00 + askExchange: 'Kraken' + '400': + $ref: '../responses/_index.yaml#/BadRequest' + '401': + $ref: '../responses/_index.yaml#/Unauthorized' + '404': + $ref: '../responses/_index.yaml#/NotFound' + '429': + $ref: '../responses/_index.yaml#/TooManyRequests' + '500': + $ref: '../responses/_index.yaml#/InternalServerError' diff --git a/openapi/paths/forex.yaml b/openapi/paths/forex.yaml new file mode 100644 index 0000000..58453ad --- /dev/null +++ b/openapi/paths/forex.yaml @@ -0,0 +1,200 @@ +# Tiingo Forex API Paths +# Reference these using: $ref: './forex.yaml#/forex-single' + +forex-single: &forex-single + get: + tags: + - Forex + summary: Get top-of-book data for a specific forex pair + description: | + Returns real-time top-of-book data including bid/ask prices and sizes for a specific forex pair. + This endpoint provides institutional-grade quality forex quotes from tier-1 banks and FX dark pools. + Market hours are Sunday 8pm EST through Friday 5pm EST. + operationId: getForexTopOfBook + parameters: + - name: ticker + in: path + required: true + schema: + type: string + pattern: '^[a-z]{6}$' + description: Forex ticker pair (e.g., eurusd, gbpusd, audusd) + example: eurusd + - $ref: '../parameters/_index.yaml#/TokenParam' + responses: + '200': + description: Successful response with forex top-of-book data + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/forex-schemas.yaml#/ForexTopOfBook' + example: + - ticker: eurusd + quoteTimestamp: '2019-07-01T21:00:01.289000+00:00' + bidPrice: 1.1186 + bidSize: 1000000.0 + askPrice: 1.1187 + askSize: 1000000.0 + midPrice: 1.11865 + '400': + $ref: '../responses/_index.yaml#/BadRequest' + '401': + $ref: '../responses/_index.yaml#/Unauthorized' + '404': + $ref: '../responses/_index.yaml#/NotFound' + '429': + $ref: '../responses/_index.yaml#/TooManyRequests' + '500': + $ref: '../responses/_index.yaml#/InternalServerError' + +forex-top: &forex-top + get: + tags: + - Forex + summary: Get top-of-book data for multiple forex pairs + description: | + Returns real-time top-of-book data including bid/ask prices and sizes for multiple forex pairs. + This endpoint allows you to query multiple forex tickers in a single request. + Supports 140+ forex ticker pairs with quotes updated to the latest microsecond during market hours. + operationId: getForexTopOfBookMultiple + parameters: + - name: tickers + in: query + required: true + schema: + type: string + description: Comma-separated list of forex ticker pairs (e.g., eurusd,gbpusd,audusd) + example: eurusd,gbpusd + - $ref: '../parameters/_index.yaml#/TokenParam' + responses: + '200': + description: Successful response with forex top-of-book data for multiple tickers + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/forex-schemas.yaml#/ForexTopOfBook' + example: + - ticker: audusd + quoteTimestamp: '2019-07-01T21:00:01.289000+00:00' + bidPrice: 0.6963 + bidSize: 100000.0 + askPrice: 0.6965 + askSize: 100000.0 + midPrice: 0.6964 + - ticker: eurusd + quoteTimestamp: '2019-07-01T21:00:01.289000+00:00' + bidPrice: 1.1186 + bidSize: 1000000.0 + askPrice: 1.1187 + askSize: 1000000.0 + midPrice: 1.11865 + '400': + $ref: '../responses/_index.yaml#/BadRequest' + '401': + $ref: '../responses/_index.yaml#/Unauthorized' + '404': + $ref: '../responses/_index.yaml#/NotFound' + '429': + $ref: '../responses/_index.yaml#/TooManyRequests' + '500': + $ref: '../responses/_index.yaml#/InternalServerError' + +forex-prices: &forex-prices + get: + tags: + - Forex + summary: Get historical intraday OHLC prices for a forex pair + description: | + Returns historical intraday OHLC (Open, High, Low, Close) prices for a forex pair. + Supports multiple resample frequencies from 1-minute to daily bars. + Default date range is current date minus 1 year to current date. + operationId: getForexPrices + parameters: + - name: ticker + in: path + required: true + schema: + type: string + pattern: '^[a-z]{6}$' + description: Forex ticker pair (e.g., eurusd, gbpusd, audusd) + example: eurusd + - name: startDate + in: query + required: false + schema: + type: string + format: date + description: Start date for historical data in YYYY-MM-DD format (default is current date minus 1 year) + example: '2019-06-30' + - name: endDate + in: query + required: false + schema: + type: string + format: date + description: End date for historical data in YYYY-MM-DD format (default is current date) + example: '2019-07-01' + - name: resampleFreq + in: query + required: false + schema: + type: string + enum: + - 1min + - 5min + - 15min + - 30min + - 1hour + - 1day + default: 1day + description: Frequency to resample data to + example: 5min + - $ref: '../parameters/_index.yaml#/TokenParam' + responses: + '200': + description: Successful response with historical forex price data + content: + application/json: + schema: + type: object + properties: + ticker: + type: string + description: Forex ticker pair + example: eurusd + priceData: + type: array + items: + $ref: '../schemas/forex-schemas.yaml#/ForexPrice' + example: + ticker: eurusd + priceData: + - date: '2019-06-28T20:00:00.000Z' + open: 1.1232 + high: 1.1254 + low: 1.1220 + close: 1.1245 + - date: '2019-06-28T20:05:00.000Z' + open: 1.1245 + high: 1.1268 + low: 1.1242 + close: 1.1260 + - date: '2019-06-28T20:10:00.000Z' + open: 1.1260 + high: 1.1275 + low: 1.1258 + close: 1.1268 + '400': + $ref: '../responses/_index.yaml#/BadRequest' + '401': + $ref: '../responses/_index.yaml#/Unauthorized' + '404': + $ref: '../responses/_index.yaml#/NotFound' + '429': + $ref: '../responses/_index.yaml#/TooManyRequests' + '500': + $ref: '../responses/_index.yaml#/InternalServerError' diff --git a/openapi/schemas/crypto-schemas.yaml b/openapi/schemas/crypto-schemas.yaml new file mode 100644 index 0000000..6ba3d60 --- /dev/null +++ b/openapi/schemas/crypto-schemas.yaml @@ -0,0 +1,303 @@ +# Crypto Schema Definitions for Tiingo API +# Reference these using: $ref: '../schemas/crypto-schemas.yaml#/SchemaName' + +CryptoCurrency: &CryptoCurrency + type: string + pattern: '^[a-z0-9]+$' + description: Cryptocurrency code (lowercase) + example: 'btc' + +CryptoTicker: &CryptoTicker + type: string + pattern: '^[a-z0-9]+$' + description: Cryptocurrency ticker (e.g., btcusd, ethusd) + example: 'btcusd' + +ResampleFreq: &ResampleFreq + type: string + pattern: '^[0-9]+(min|hour|day)$' + description: Resampling frequency for historical data + enum: + - '1min' + - '5min' + - '15min' + - '30min' + - '1hour' + - '2hour' + - '4hour' + - '1day' + example: '5min' + +# Price Data Schemas + +PriceDataItem: &PriceDataItem + type: object + description: OHLCV price data for a specific time period + properties: + date: + type: string + format: date-time + description: The datetime this data pertains to, dependent on resampleFreq parameter + example: '2019-01-02T00:00:00.000Z' + open: + type: number + format: float + description: The opening price for the asset + example: 3690.01 + high: + type: number + format: float + description: The high price for the asset + example: 3701.0 + low: + type: number + format: float + description: The low price for the asset + example: 3600.65 + close: + type: number + format: float + description: The closing price for the asset + example: 3610.32 + volume: + type: number + format: float + description: The volume in the base currency + example: 1234.56 + volumeNotional: + type: number + format: float + description: The volume in the quote currency (volumeNotional = close * volume) + example: 4456789.12 + tradesDone: + type: integer + format: int32 + description: The number of trades executed + example: 5000 + required: + - date + - open + - high + - low + - close + - volume + - volumeNotional + - tradesDone + +ExchangeDataItem: &ExchangeDataItem + type: object + description: Raw exchange-level price data + additionalProperties: + type: object + description: Exchange-specific data keyed by exchange name + properties: + date: + type: string + format: date-time + open: + type: number + format: float + high: + type: number + format: float + low: + type: number + format: float + close: + type: number + format: float + volume: + type: number + format: float + volumeNotional: + type: number + format: float + tradesDone: + type: integer + +CryptoPrice: &CryptoPrice + type: object + description: Cryptocurrency price response with metadata and price data + properties: + ticker: + type: string + description: Ticker related to the asset + example: 'btcusd' + baseCurrency: + type: string + description: The base pair of the cryptocurrency (e.g., "btc" for "btcusd") + example: 'btc' + quoteCurrency: + type: string + description: The quote pair of the cryptocurrency (e.g., "usd" for "btcusd") + example: 'usd' + priceData: + type: array + description: Array of price data points + items: + $ref: '#/PriceDataItem' + exchangeData: + $ref: '#/ExchangeDataItem' + description: Underlying data for each exchange (only included if includeRawExchangeData=true) + required: + - ticker + - baseCurrency + - quoteCurrency + - priceData + +# Metadata Schemas + +CryptoMetadata: &CryptoMetadata + type: object + description: Cryptocurrency metadata information + properties: + ticker: + type: string + description: Ticker related to the asset + example: 'btcusd' + baseCurrency: + type: string + description: The base pair of the cryptocurrency + example: 'btc' + quoteCurrency: + type: string + description: The quote pair of the cryptocurrency + example: 'usd' + name: + type: string + description: Full-length name of the asset + example: 'Bitcoin' + description: + type: string + description: Long-form description of the asset + example: 'Bitcoin is a cryptocurrency and worldwide payment system.' + required: + - ticker + - baseCurrency + - quoteCurrency + - name + +# Top-of-Book Schemas + +TopOfBookData: &TopOfBookData + type: object + description: Top-of-book data with bid/ask and last trade information + properties: + quoteTimestamp: + type: string + format: date-time + description: Timestamp when quote (bid/ask) data was last received + example: '2019-01-02T12:34:56.789Z' + lastSaleTimestamp: + type: string + format: date-time + description: Timestamp when last trade data was received + example: '2019-01-02T12:34:56.789Z' + lastPrice: + type: number + format: float + description: Last executed price on any exchange + example: 3610.32 + lastSize: + type: number + format: float + description: Volume of the last trade in base currency + example: 0.5 + lastSizeNotional: + type: number + format: float + description: Notional value of last trade (lastSizeNotional = lastPrice * lastSize) + example: 1805.16 + lastExchange: + type: string + description: Full name of the exchange where last trade occurred + example: 'Coinbase' + bidSize: + type: number + format: float + description: Amount at the bid price + example: 1.2 + bidPrice: + type: number + format: float + description: Current bid price + example: 3609.50 + bidExchange: + type: string + description: Full name of the exchange with the best bid + example: 'Binance' + askSize: + type: number + format: float + description: Amount at the ask price + example: 0.8 + askPrice: + type: number + format: float + description: Current ask price + example: 3611.00 + askExchange: + type: string + description: Full name of the exchange with the best ask + example: 'Kraken' + +TopOfBookExchangeData: &TopOfBookExchangeData + type: object + description: Exchange-level top-of-book data + additionalProperties: + type: object + description: Exchange-specific top-of-book data keyed by exchange name + properties: + quoteTimestamp: + type: string + format: date-time + lastSaleTimestamp: + type: string + format: date-time + lastPrice: + type: number + format: float + lastSize: + type: number + format: float + bidSize: + type: number + format: float + bidPrice: + type: number + format: float + askSize: + type: number + format: float + askPrice: + type: number + format: float + +CryptoTopOfBook: &CryptoTopOfBook + type: object + description: Cryptocurrency top-of-book response with metadata and book data (DEPRECATED) + deprecated: true + properties: + ticker: + type: string + description: Ticker related to the asset + example: 'btcusd' + baseCurrency: + type: string + description: The base pair of the cryptocurrency + example: 'btc' + quoteCurrency: + type: string + description: The quote pair of the cryptocurrency + example: 'usd' + topOfBookData: + $ref: '#/TopOfBookData' + description: Top-of-book data + exchangeData: + $ref: '#/TopOfBookExchangeData' + description: Underlying data for each exchange (only included if includeRawExchangeData=true) + required: + - ticker + - baseCurrency + - quoteCurrency + - topOfBookData diff --git a/openapi/schemas/forex-schemas.yaml b/openapi/schemas/forex-schemas.yaml new file mode 100644 index 0000000..47496e3 --- /dev/null +++ b/openapi/schemas/forex-schemas.yaml @@ -0,0 +1,106 @@ +# Tiingo Forex API Schema Definitions +# Reference these using: $ref: './forex-schemas.yaml#/ForexTopOfBook' + +ForexTopOfBook: &ForexTopOfBook + type: object + description: Real-time top-of-book data for a forex pair including bid/ask prices and sizes + properties: + ticker: + type: string + description: Forex ticker pair + pattern: '^[a-z]{6}$' + example: eurusd + quoteTimestamp: + type: string + format: date-time + description: The timestamp when the data was last refreshed (ISO 8601 format with timezone) + example: '2019-07-01T21:00:01.289000+00:00' + midPrice: + type: number + format: float + nullable: true + description: The mid price calculated as (bidPrice + askPrice) / 2.0 when both bid and ask prices are not null + example: 1.11865 + bidSize: + type: number + format: float + description: The amount of units available at the bid price + example: 1000000.0 + bidPrice: + type: number + format: float + nullable: true + description: The current bid price + example: 1.1186 + askSize: + type: number + format: float + description: The amount of units available at the ask price + example: 1000000.0 + askPrice: + type: number + format: float + nullable: true + description: The current ask price + example: 1.1187 + required: + - ticker + - quoteTimestamp + - bidSize + - askSize + example: + ticker: eurusd + quoteTimestamp: '2019-07-01T21:00:01.289000+00:00' + bidPrice: 1.1186 + bidSize: 1000000.0 + askPrice: 1.1187 + askSize: 1000000.0 + midPrice: 1.11865 + +ForexPrice: &ForexPrice + type: object + description: Historical OHLC (Open, High, Low, Close) price data for a forex pair + properties: + date: + type: string + format: date-time + description: The date/time this data pertains to (ISO 8601 format). Format depends on resampleFreq parameter + example: '2019-06-28T20:00:00.000Z' + open: + type: number + format: float + description: The opening price for the asset in the given period + example: 1.1232 + high: + type: number + format: float + description: The high price for the asset in the given period + example: 1.1254 + low: + type: number + format: float + description: The low price for the asset in the given period + example: 1.1220 + close: + type: number + format: float + description: The closing price for the asset in the given period + example: 1.1245 + volume: + type: number + format: float + nullable: true + description: Trading volume for the period (when available) + example: null + required: + - date + - open + - high + - low + - close + example: + date: '2019-06-28T20:00:00.000Z' + open: 1.1232 + high: 1.1254 + low: 1.1220 + close: 1.1245