Forex Heatmap

Nov 8

█  OVERVIEW


This indicator creates a dynamic grid display of currency pair cross rates (exchange rates) and percentage changes, emulating the Cross Rates and Heat Map widgets available on our Forex page. It provides a view of realtime exchange rates for all possible pairs derived from a user-specified list of currencies, allowing users to monitor the relative performance of several currencies directly on a TradingView chart.



█  CONCEPTS


Foreign exchange

The Foreign Exchange (Forex/FX) market is the largest, most liquid financial market globally, with an average daily trading volume of over 5 trillion USD. Open 24 hours a day, five days a week, it operates through a decentralized network of financial hubs in various major cities worldwide. In this market, participants trade currencies in pairs, where the listed price of a currency pair represents the exchange rate from a given base currency to a specific quote currency. For example, the "EURUSD" pair's price represents the amount of USD (quote currency) that equals one unit of EUR (base currency). Globally, the most traded currencies include the U.S. dollar (USD), Euro (EUR), Japanese yen (JPY), British pound (GBP), and Australian dollar (AUD), with USD involved in over 87% of all trades.

Understanding the Forex market is essential for traders and investors, even those who do not trade currency pairs directly, because exchange rates profoundly affect global markets. For instance, fluctuations in the value of USD can impact the demand for U.S. exports or the earnings of companies that handle multinational transactions, either of which can affect the prices of stocks, indices, and commodities. Additionally, since many factors influence exchange rates, including economic policies and interest rate changes, analyzing the exchange rates across currencies can provide insight into global economic health.



█  FEATURES


Requesting a list of currencies

This indicator requests data for every valid currency pair combination from the list of currencies defined by the "Currency list" input in the "Settings/Inputs" tab. The list can contain up to six unique currency codes separated by commas, resulting in a maximum of 30 requested currency pairs.

For example, if the specified "Currency list" input is "CAD, USD, EUR", the indicator requests and displays relevant data for six currency pair combinations: "CADUSD", "USDCAD", "CADEUR", "EURCAD", "USDEUR", "EURUSD". See the "Grid display" section below to understand how the script organizes the requested information.

Each item in the comma-separated list must represent a valid currency code. If the "Currency list" input contains an invalid currency code, the corresponding cells for that currency in the "Cross rates" or "Heat map" grid show "NaN" values. If the list contains empty items, e.g., "CAD, ,EUR, ", the indicator ignores them in its data requests and calculations.

NOTE: Some uncommon currency pair combinations might not have data feeds available. If no available symbols provide the exchange rates between two specified currencies, the corresponding table cells show "NaN" results.


Realtime data

The indicator retrieves realtime market prices, daily price changes, and minimum tick sizes for all the currency pairs derived from the "Currency list" input. It updates the retrieved information shown in its grid display after new ticks become available to reflect the latest known values.

NOTE: Pine scripts execute on realtime bars only when new ticks are available in the chart's data feed. If no new updates are available from the chart's realtime feed, it may cause a delay in the data the indicator receives.


Grid display

This indicator displays the requested data for each currency pair in a table with cells organized as a grid. Each row name corresponds to a pair's base currency, and each column name corresponds to a quote currency. The cell at the intersection of a specific row and column shows the value requested from the corresponding currency pair.

For example, the cell at the intersection of a "EUR" row and "USD" column shows the data retrieved for the "EURUSD" currency pair, and the cell at the "USD" row and "EUR" column shows data for the inverse pair ("USDEUR").

Note that the main diagonal cells in the table, where rows and columns with the same names intersect, are blank. The exchange rate from one currency to itself is always 1, and no Forex symbols such as "EUREUR" exist.

The dropdown input at the top of the "Settings/Inputs" tab determines the type of information displayed in the table. Two options are available: "Cross rates" and "Heat map". Both modes color their cells for light and dark themes separately based on the inputs in the "Colors" section.


Cross rates

When a user selects the "Cross rates" display mode, the table's cells show the latest available exchange rate for each currency pair, emulating the behavior of the Cross Rates widget. Each cell's value represents the amount of the quote currency (column name) that equals one unit of the base currency (row name). This display allows users to compare cross rates across currency pairs, and their inverses.

The background color of each cell changes based on the most recent update to the exchange rate, allowing users to monitor the direction of short-term fluctuations as they occur. By default, the background turns green (positive cell color) when the cross rate increases from the last recorded update and red (negative cell color) when the rate decreases. The cell's color reverts to the chart's background color after no new updates are available for 200 milliseconds.


Heat map

When a user selects the "Heat map" display mode, the table's cells show the latest daily percentage change of each currency pair, emulating the behavior of the Heat Map widget.

In this mode, the background color of each cell depends on the corresponding currency pair's daily performance. Heat maps typically use colors that vary in intensity based on the calculated values. This indicator uses the following color coding by default:

 • Green (Positive cell color): Percentage change > +0.1%
 • No color: Percentage change between 0.0% and +0.1%
 • Bright red (Negative cell color): Percentage change < -0.1%
 • Lighter/darker red (Minor negative cell color): Percentage change between 0.0% and -0.1%



█  FOR Pine Script™ CODERS


• This script utilizes dynamic requests to iteratively fetch information from multiple contexts using a single request.security() instance in the code. Previously, `request.*()` functions were not allowed within the local scopes of loops or conditional structures, and most `request.*()` function parameters, excluding `expression`, required arguments of a simple or weaker qualified type. The new `dynamic_requests` parameter in script declaration statements enables more flexibility in how scripts can use `request.*()` calls. When its value is `true`, all `request.*()` functions can accept series arguments for the parameters that define their requested contexts, and `request.*()` functions can execute within local scopes. See the Dynamic requests section of the Pine Script™ User Manual to learn more.

• Scripts can execute up to 40 unique `request.*()` function calls. A `request.*()` call is unique only if the script does not already call the same function with the same arguments. See this section of the User Manual's Limitations page for more information.

• Typically, when requesting higher-timeframe data with request.security() using barmerge.lookahead_on as the `lookahead` argument, the `expression` argument should use the history-referencing operator to offset the series, preventing lookahead bias on historical bars. However, the request.security() call in this script uses barmerge.lookahead_on without offsetting the `expression` because the script only displays results for the latest historical bar and all realtime bars, where there is no future information to leak into the past. Instead, using this call on those bars ensures each request fetches the most recent data available from each context.

• The request.security() instance in this script includes a `calc_bars_count` argument to specify that each request retrieves only a minimal number of bars from the end of each symbol's historical data feed. The script does not need to request all the historical data for each symbol because it only shows results on the last chart bar that do not depend on the entire time series. In this case, reducing the retrieved bars in each request helps minimize resource usage without impacting the calculated results.



Look first. Then leap.