How Should You Read Data Returned by an FX API? Understanding Prices, Timestamps, and Trading Symbols

After integrating an FX API, developers typically receive JSON data containing trading symbols, prices, and time information. Some interfaces also return bid and ask order book data with corresponding quantity fields. Without understanding what each field represents, developers may mistake a Bid for an Ask, treat a millisecond timestamp as a second-based timestamp, or display prices from different currency pairs on the wrong market data page.

Understanding FX market data requires more than looking at price values. Trading symbols, quote timestamps, and order book quantities must also be considered. This article uses AllTick FX depth data as an example to explain how to read and process these fields correctly.

How to Read Prices and Volume Returned by an FX API

FX quotes are usually represented as currency pairs, such as EURUSD, GBPUSD, and USDJPY. Taking EURUSD as an example, EUR is the base currency and USD is the quote currency. The pair indicates how many US dollars are equivalent to one euro.

In AllTick order book data, bids and asks represent the buy and sell sides respectively. Each price level contains two fields: price and volume.

The following is sample EURUSD data. The values are illustrative and are provided only to explain the field structure. They are not records returned by a live API request.

{
  "ret": 200,
  "msg": "ok",
  "trace": "demo-trace",
  "data": {
    "tick_list": [
      {
        "code": "EURUSD",
        "seq": "123456",
        "tick_time": "1793260800000",
        "bids": [
          {
            "price": "1.08518",
            "volume": "120000"
          }
        ],
        "asks": [
          {
            "price": "1.08522",
            "volume": "95000"
          }
        ]
      }
    ]
  }
}

The main fields can be understood as follows:

Bid represents the price at which the base currency can be bought, while Ask represents the price at which the base currency can be sold. From the trader's perspective, selling the base currency usually means referring to the Bid, while buying it means referring to the Ask.

For example, in the EURUSD data above, the Bid is 1.08518 and the Ask is 1.08522. The difference between these two prices is the spread.

Spread = Ask − Bid

The result is 0.00004. For EURUSD, one standard pip is typically 0.0001, so this spread is equivalent to 0.4 pips.

volume represents the quantity associated with a particular order book price level. It is not the cumulative trading volume of the currency pair, nor is it the same as the volume of a candlestick. The unit of quantity should be checked against the data definition of the relevant product. Do not assume that every asset uses the same unit.

According to AllTick's current data specifications, volume is provided for FX, precious metals, energy, stocks, and cryptocurrency data. However, this field is not provided for some CFD indices. Therefore, when processing data across multiple markets, developers should allow for differences in field structures between instruments rather than assuming that volume is mandatory for every product.

How to Convert Timestamps to Display the Correct Quote Time

Prices indicate the level of a quote, while timestamps help developers determine when that quote was recorded. They are also useful for checking whether market data is being updated at the expected time.

AllTick uses different time fields depending on the interface. For example, the tick_time field in HTTP depth data uses a millisecond timestamp, while the timestamp field in candlestick data uses a second-based timestamp.

Passing a millisecond timestamp directly to a function that expects seconds will produce an incorrect date and time.

The timestamp in order book data can be converted using Python as follows:

from datetime import datetime, timezone

tick_time = "1793260800000"

quote_time = datetime.fromtimestamp(
    int(tick_time) / 1000,
    tz=timezone.utc
)

print(quote_time.isoformat())

First, the string is converted into an integer and divided by 1000 to obtain seconds. The UTC time zone is then specified.

When processing candlestick data, the timestamp should be converted as a second-based value:

timestamp = "1793260800"

kline_time = datetime.fromtimestamp(
    int(timestamp),
    tz=timezone.utc
)

print(kline_time.isoformat())

In actual development, do not determine the time unit of every API solely from the number of digits. Always check the field definition of the specific interface first.

When measuring market data delays, it is also important to record the local data receipt time and account for clock synchronization between servers. Otherwise, differences in local clock settings may be mistaken for network latency.

How to Match Trading Symbols with the Correct Market Data

The trading symbol field identifies which market instrument each quote belongs to. AllTick FX symbols use a six-character currency code format, such as EURUSD, GBPUSD, and USDJPY.

Taking USDJPY as an example, USD is the base currency and JPY is the quote currency. The pair indicates how many Japanese yen are equivalent to one US dollar.

During development, it is recommended to retain the original code returned by the API and handle the display format separately. For example, the API may use EURUSD, while the frontend displays it as EUR/USD. However, the display format should not be directly substituted for the API request parameter.

When a system subscribes to multiple currency pairs at the same time, it is recommended to store code, price, volume, and timestamp in the same market data record. This helps prevent prices from being associated with the wrong trading symbols during asynchronous updates.

How to Parse FX Order Book Data with Python

Once the fields are understood, the parsing logic can be centralized in the backend. The following example uses AllTick HTTP Interface API's /depth-tick order book endpoint to retrieve the Bid, Ask, quantities, and timestamp for EURUSD.

import json
import requests
from decimal import Decimal
from datetime import datetime, timezone

TOKEN = "YOUR_TOKEN_HERE"

query = {
    "trace": "fx_depth_demo",
    "data": {
        "symbol_list": [{"code": "EURUSD"}]
    }
}

response = requests.get(
    "https://quote.alltick.co/quote-b-api/depth-tick",
    params={
        "token": TOKEN,
        "query": json.dumps(query, separators=(",", ":"))
    },
    timeout=10
)

response.raise_for_status()
result = response.json()

if result.get("ret") != 200:
    raise RuntimeError(f"API error: {result}")

tick_list = result.get("data", {}).get("tick_list", [])

for item in tick_list:
    bids = item.get("bids") or []
    asks = item.get("asks") or []

    if not bids or not asks:
        continue

    bid = bids[0]
    ask = asks[0]

    bid_price = Decimal(bid["price"])
    ask_price = Decimal(ask["price"])

    bid_volume = bid.get("volume")
    ask_volume = ask.get("volume")

    quote_time = datetime.fromtimestamp(
        int(item["tick_time"]) / 1000,
        tz=timezone.utc
    )

    print({
        "symbol": item["code"],
        "bid": str(bid_price),
        "bid_volume": bid_volume,
        "ask": str(ask_price),
        "ask_volume": ask_volume,
        "spread": str(ask_price - bid_price),
        "time": quote_time.isoformat()
    })

This code handles the API request, response status check, Bid and Ask parsing, order book quantity retrieval, and timestamp conversion. It uses Decimal for price calculations to reduce precision issues associated with ordinary floating-point arithmetic.

The example is designed for EURUSD, which supports order book data. For instruments such as some CFD indices that do not provide volume, this field should be treated as optional. Similarly, if order book data is unavailable for a particular instrument, developers should not immediately classify the price as invalid. They should first check whether the instrument supports order book functionality and whether there are any issues with the current market data status.

How to Choose the Right Interface for Different FX Data Requirements

If an application only needs to retrieve current Bid and Ask quotes, the HTTP depth query interface can be used. If it needs to receive continuous order book updates, WebSocket subscriptions can be used instead. For trade-by-trade data or historical candlesticks, the corresponding data interfaces should be selected.

It is also important to distinguish the meaning of volume across different types of market data:

• Order book volume: The quantity associated with a particular Bid or Ask price level.
• Tick trade volume: The quantity associated with an individual trade record.
• Candlestick volume: The trading volume for the corresponding candlestick period.

Although these fields share the same name, their business meanings are different. They should not be mixed in calculations.

AllTick provides FX market data APIs supporting currency pairs such as EURUSD, GBPUSD, and USDJPY. Different types of market data can be accessed through REST and WebSocket interfaces. Developers can select the appropriate interface according to their needs, whether for market displays, real-time subscriptions, or historical analysis.

Before production integration, verify the trading symbol codes, price fields, timestamp units, and whether volume is available for the relevant data type. You can visit the AllTick official website to explore product information and developer resources.

For an FX market data system, correctly reading prices is only the starting point. Only when prices, timestamps, trading symbols, and order book quantities are properly understood can subsequent caching, market display, and strategy calculations be built on a reliable data structure.