Twelve Data Currencies API

openapi: 3.2.0
info:
  description: '## Overview


    Welcome to Twelve Data developer docs — your gateway to comprehensive financial market data through a powerful and easy-to-use API.'
  title: Twelve Data Currencies API
  version: 0.0.1
servers:
- url: https://api.twelvedata.com/
security:
- authorizationHeader:
  - '[]'
- queryParameter:
  - '[]'
tags:
- name: Currencies
paths:
  /currency_conversion:
    get:
      description: The currency conversion endpoint provides real-time exchange rates and calculates the converted amount for specified currency pairs, including both forex and cryptocurrencies. This endpoint is useful for obtaining up-to-date conversion values between two currencies, facilitating tasks such as financial reporting, e-commerce transactions, and travel budgeting.
      operationId: GetCurrencyConversion
      parameters:
      - description: The currency pair you want to request can be either forex or cryptocurrency. Slash(`/`) delimiter is used. E.g. `EUR/USD` or `BTC/ETH` will be correct
        in: query
        name: symbol
        required: true
        schema:
          type: string
          x-go-name: Symbol
          x-order: '10'
        x-go-name: Symbol
        x-order: '10'
        example: EUR/USD
      - description: Amount of base currency to be converted into quote currency. Supports values in the range from `0` and above
        in: query
        name: amount
        required: true
        schema:
          format: double
          type: number
          x-go-name: Amount
          x-order: '20'
        x-go-name: Amount
        x-order: '20'
        example: '100'
      - description: If not null, will use exchange rate from a specific date or time. Format `2006-01-02` or `2006-01-02T15:04:05`. Is set in the local exchange time zone, use timezone parameter to specify a specific time zone
        in: query
        name: date
        schema:
          type: string
          x-go-name: Date
          x-order: '30'
        x-go-name: Date
        x-order: '30'
        example: '2006-01-02T15:04:05'
      - description: Value can be `JSON` or `CSV`. Default `JSON`
        in: query
        name: format
        schema:
          $ref: '#/components/schemas/FormatEnum'
        x-go-name: Format
        x-order: '40'
      - description: Specify the delimiter used when downloading the `CSV` file. Default semicolon `;`
        in: query
        name: delimiter
        schema:
          default: ;
          type: string
          x-go-name: Delimiter
          x-order: '50'
        x-go-name: Delimiter
        x-order: '50'
      - description: The number of decimal places for the data
        in: query
        name: dp
        schema:
          default: 5
          format: int64
          type: integer
          x-go-name: DecimalPlaces
          x-order: '60'
        x-go-name: DecimalPlaces
        x-order: '60'
      - description: 'Timezone at which output datetime will be displayed. Supports:

          <ul>

          <li>1. <code>Exchange</code> for local exchange time</li>

          <li>2. <code>UTC</code> for datetime at universal UTC standard</li>

          <li>3. Timezone name according to the IANA Time Zone Database. E.g. <code>America/New_York</code>, <code>Asia/Singapore</code>. Full list of timezones can be found <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones" target="blank">here</a>.</li>

          </ul>

          <i>Take note that the IANA Timezone name is case-sensitive</i>'
        in: query
        name: timezone
        schema:
          type: string
          x-go-name: Timezone
          x-order: '60'
        x-go-name: Timezone
        x-order: '60'
        example: UTC
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCurrencyConversion_200_response'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiBadRequestErrorResponseBody'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedErrorResponseBody'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenErrorResponseBody'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiNotFoundErrorResponseBody'
          description: ''
        '414':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiParameterTooLongErrorResponseBody'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsErrorResponseBody'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInternalServerErrorResponseBody'
          description: ''
      summary: Currency conversion
      tags:
      - Currencies
      x-api-credits-cost: '1'
      x-api-credits-type: symbol
      x-badge: Useful
      x-group: Currencies
      x-order: '20'
  /exchange_rate:
    get:
      description: The exchange rate endpoint provides real-time exchange rates for specified currency pairs, including both forex and cryptocurrency. It returns the current exchange rate value between two currencies, allowing users to quickly access up-to-date conversion rates for financial transactions or market analysis.
      operationId: GetExchangeRate
      parameters:
      - description: The currency pair you want to request can be either forex or cryptocurrency. Slash(`/`) delimiter is used. E.g. `EUR/USD` or `BTC/ETH` will be correct
        in: query
        name: symbol
        required: true
        schema:
          type: string
          x-go-name: Symbol
          x-order: '10'
        x-go-name: Symbol
        x-order: '10'
        example: EUR/USD
      - description: If not null, will use exchange rate from a specific date or time. Format `2006-01-02` or `2006-01-02T15:04:05`. Is set in the local exchange time zone, use timezone parameter to specify a specific time zone
        in: query
        name: date
        schema:
          type: string
          x-go-name: Date
          x-order: '20'
        x-go-name: Date
        x-order: '20'
        example: '2006-01-02T15:04:05'
      - description: Value can be `JSON` or `CSV`. Default `JSON`
        in: query
        name: format
        schema:
          $ref: '#/components/schemas/FormatEnum'
        x-go-name: Format
        x-order: '30'
      - description: Specify the delimiter used when downloading the `CSV` file. Default semicolon `;`
        in: query
        name: delimiter
        schema:
          default: ;
          type: string
          x-go-name: Delimiter
          x-order: '40'
        x-go-name: Delimiter
        x-order: '40'
      - description: The number of decimal places for the data
        in: query
        name: dp
        schema:
          default: 5
          format: int64
          type: integer
          x-go-name: DecimalPlaces
          x-order: '50'
        x-go-name: DecimalPlaces
        x-order: '50'
      - description: 'Timezone at which output datetime will be displayed. Supports:

          <ul>

          <li>1. <code>Exchange</code> for local exchange time</li>

          <li>2. <code>UTC</code> for datetime at universal UTC standard</li>

          <li>3. Timezone name according to the IANA Time Zone Database. E.g. <code>America/New_York</code>, <code>Asia/Singapore</code>. Full list of timezones can be found <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones" target="blank">here</a>.</li>

          </ul>

          <i>Take note that the IANA Timezone name is case-sensitive</i>'
        in: query
        name: timezone
        schema:
          type: string
          x-go-name: Timezone
          x-order: '60'
        x-go-name: Timezone
        x-order: '60'
        example: UTC
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExchangeRate_200_response'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiBadRequestErrorResponseBody'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedErrorResponseBody'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenErrorResponseBody'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiNotFoundErrorResponseBody'
          description: ''
        '414':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiParameterTooLongErrorResponseBody'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsErrorResponseBody'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInternalServerErrorResponseBody'
          description: ''
      summary: Exchange rate
      tags:
      - Currencies
      x-api-credits-cost: '1'
      x-api-credits-type: symbol
      x-group: Currencies
      x-order: '10'
components:
  schemas:
    GetExchangeRate_200_response:
      properties:
        symbol:
          description: Requested currency symbol
          examples:
          - USD/JPY
          type: string
          x-go-name: Symbol
          x-order: 10
        rate:
          description: Real-time exchange rate for the corresponding symbol
          examples:
          - 105.12
          format: double
          type: number
          x-go-name: Rate
          x-order: 20
        timestamp:
          description: Unix timestamp of the rate
          examples:
          - 1602714051
          format: int64
          type: integer
          x-go-name: Timestamp
          x-order: 30
      required:
      - rate
      - symbol
      - timestamp
      type: object
    GetCurrencyConversion_200_response:
      properties:
        symbol:
          description: Requested currency symbol
          examples:
          - USD/JPY
          type: string
          x-go-name: Symbol
          x-order: 10
        rate:
          description: Real-time exchange rate for the corresponding symbol
          examples:
          - 105.12
          format: double
          type: number
          x-go-name: Rate
          x-order: 20
        amount:
          description: Amount of converted currency
          examples:
          - 12824.64
          format: double
          type: number
          x-go-name: Amount
          x-order: 30
        timestamp:
          description: Unix timestamp of the rate
          examples:
          - 1602714051
          format: int64
          type: integer
          x-go-name: Timestamp
          x-order: 40
      required:
      - rate
      - symbol
      - timestamp
      type: object
    ApiForbiddenErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 403
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - API key lacks permissions for the requested resource
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
    FormatEnum:
      default: JSON
      enum:
      - JSON
      - CSV
      type: string
      x-go-name: Format
      x-order: '90'
    ApiNotFoundErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 404
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - symbol or figi parameter is missing or invalid
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
    ApiUnauthorizedErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 401
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - apikey parameter is incorrect or not specified
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
    ApiTooManyRequestsErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 429
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - You have run out of API credits for the current minute. 1000 API credits were used, with the current limit being 987. Wait for the next minute or consider upgrading your plan at https://twelvedata.com/pricing
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
    ApiInternalServerErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 500
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - Internal server error
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
    ApiBadRequestErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 400
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - Invalid request
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
    ApiParameterTooLongErrorResponseBody:
      properties:
        code:
          description: Error code
          examples:
          - 414
          format: int64
          type: integer
          x-go-name: Code
        message:
          description: Error message
          examples:
          - Input parameter array exceeds the allowed length
          type: string
          x-go-name: Message
        status:
          description: Error status
          examples:
          - error
          type: string
          x-go-name: Status
      required:
      - code
      - message
      - status
      type: object
      x-go-package: gitlab.atlasgroup.ai/twelvedata/api/route/description
  securitySchemes:
    authorizationHeader:
      description: Enter the token with the `apikey ` prefix, e.g. "apikey abcde12345".
      in: header
      name: Authorization
      type: apiKey
    queryParameter:
      in: query
      name: apikey
      type: apiKey
x-group-list:
- description: Access real-time and historical market prices—time series and exchange rates—for equities, forex, cryptocurrencies, ETFs, and more. These endpoints form the foundation for any trading or data-driven application.
  name: Market data
  order: 10
- children:
  - description: Asset Catalog endpoints are your starting point. They return the complete inventory of tradeable instruments available through Twelve Data — over 1,000,000 symbols across 50+ countries. You query a catalog first to discover which symbols exist, then pass those symbols to price, fundamental, or indicator endpoints.
    name: Asset catalogs
    order: 10
  - description: Discovery endpoints help you find instruments when you don't already know the exact identifier. The Asset Catalog is the phone book; Discovery is the search engine on top of it.
    name: Discovery
    order: 20
  - description: 'Market endpoints answer operational questions about exchanges themselves: which ones are open right now, what are their trading hours, and how far back does data go for a given instrument?'
    name: Markets
    order: 30
  - description: 'Metadata endpoints return the lookup tables and enumerations that define valid parameter values across the entire API. They answer: what instrument types exist? What intervals are supported? Which countries are covered? What technical indicators can I use?'
    name: Supporting metadata
    order: 40
  description: Lookup static metadata—symbol lists, exchange details, currency information-to filter, validate, and contextualize your core data calls. Ideal for building dropdowns, mappings, and ensuring data consistency.
  name: Reference data
  order: 20
- description: In-depth company and fund financials—income statements, balance sheets, cash flows, profiles, corporate events, and key ratios. Unlock comprehensive datasets for valuation, screening, and fundamental research.
  name: Fundamentals
  order: 30
- name: Currencies
  order: 35
- description: 'ETF-focused metadata and analytics: universe lists, family and type groupings, NAV snapshots, performance metrics, risk measures, and current fund composition. Tailored to the unique characteristics and reporting cadence of exchange-traded funds.'
  name: ETFs
  order: 40
- description: 'Mutual-fund-specific listings and snapshots: fund directories, issuer families, fund types, NAV history, dividend records, key ratios, and portfolio holdings. Ideal for long-term performance analysis and portfolio attribution.'
  name: Mutual funds
  order: 50
- description: 'Money-market-fund directories and full-data snapshots: fund listings ranked by fund size, plus screener metrics (fund size, liquidity, weighted average maturity), yields, key facts, and risk indicators. Focused on short-term, low-risk cash-management instruments for liquidity and capital-preservation analysis.'
  name: Money market funds
  order: 55
- children:
  - description: Plotted directly on the price chart to smooth or envelope price data, highlighting trend direction, support/resistance, and mean-reversion levels (e.g. moving averages, Bollinger Bands, Parabolic SAR, Ichimoku Cloud, Keltner Channels, McGinley Dynamic).
    name: Overlap studies
    order: 10
  - description: Oscillators that measure the speed or strength of price movement, helping detect overbought/oversold conditions, divergences, and shifts in trend momentum (e.g. RSI, MACD, ROC, Stochastics, ADX, CCI, Coppock Curve, TRIX).
    name: Momentum indicators
    order: 20
  - description: Use trading volume to confirm price moves or warn of exhaustion—volume and price in tandem suggest trend strength, while divergences can signal reversals (e.g. OBV, Chaikin AD, Accumulation/Distribution Oscillator).
    name: Volume indicators
    order: 30
  - description: Quantify the range or dispersion of price over time to gauge risk, size stops, or identify breakouts (e.g. ATR, NATR, True Range) and adaptive overlays like SuperTrend.
    name: Volatility indicators
    order: 40
  - description: Convert raw OHLC data into derived series or aggregated values to feed other indicators or reveal different perspectives on price (e.g. typical price, HLC3, weighted close, arithmetic transforms like SUM, AVG, LOG, SQRT).
    name: Price transform
    order: 50
  - description: Detect and follow recurring periodic patterns in price action using Hilbert Transform–based measures of cycle period and phase (e.g. HT_SINE, HT_DCPERIOD, HT_DCPHASE, HT_PHASOR, HT_TRENDMODE).
    name: Cycle indicators
    order: 60
  - description: Scan bars or bar‐groups for predefined candlestick patterns that historically signal continuation or reversal setups (e.g. Doji, Hammer, Engulfing, Three Black Crows, Morning Star, Dark Cloud Cover, etc.).
    name: Pattern recognition
    order: 70
  - description: Compute fundamental statistical metrics on price series—dispersion, regression, correlation, and forecasting components—for standalone analysis or as inputs to other models (e.g. STDDEV, VAR, LINEARREG, CORREL, TSF, BETA).
    name: Statistic functions
    order: 80
  - name: Math transform
    order: 90
  description: On-demand calculation of popular indicators (SMA, EMA, RSI, MACD, Bollinger Bands, etc.) over any supported time series. Streamline chart overlays, signal generation, and backtesting without external libraries.
  name: Technical indicators
  order: 60
- description: Forward-looking and consensus analytics—earnings and revenue estimates, EPS trends and revisions, growth projections, analyst recommendations and ratings, price targets, and other consensus metrics. Perfect for incorporating expert forecasts and sentiment into your models and dashboards.
  name: Analysis
  order: 70
- description: 'Compliance and filings data: insider transactions, SEC reports, governance documents, and more. Critical for audit trails, due-diligence workflows, and risk-management integrations.'
  name: Regulatory
  order: 80
- description: High-throughput and management endpoints for power users—submit and monitor batch jobs to pull large datasets asynchronously, track your API usage and quotas programmatically, and access other developer-focused tools for automating and scaling your data workflows.
  name: Advanced
  order: 90
x-original-swagger-version: '2.0'