Updated on 2026-05-12 NovaDataHub Engineering
Developer docs

FX Response Fields

FX integrations become easier to trust when teams are clear about which fields belong to latest-rate lookups, which belong to direct conversions, and which belong to historical reporting. This page explains how to think about the main NovaDataHub FX response shapes so pricing, checkout, and finance workflows model the data cleanly.

Key points

  • Latest-rates, conversion, and time-series responses solve related but different workflow problems.
  • Base currency, date, amount, and target-currency context should stay attached to derived values.
  • Teams usually get cleaner downstream reporting when they separate response families instead of flattening everything into one generic object.

Common errors

  • 400 invalid_currency
  • 401 invalid_key
  • 429 rate_limited
Reference details

Parameters, response shape, and operational notes

Parameter notes

  • Use latest-rates responses when you need a reusable rate table.
  • Use conversion responses when you need a direct amount result for one currency pair.
  • Use historical time-series responses when the workflow depends on a reporting window rather than only the current day.

Response highlights

  • Latest-rates responses usually emphasize base, date, and rates.
  • Conversion responses usually emphasize from, to, amount, rate, result, and date.
  • Historical responses usually emphasize base, start, end, and date-keyed rate structures.

Operational notes

  • Preserve the request context that explains why a given FX value exists.
  • Keep pricing-display logic, conversion logic, and historical-reporting logic distinct in code and storage.
  • Avoid losing auditability by stripping away base currency, amount, or date when you normalize the data.

Implementation checklist

  • Start with one latest-rates response, one conversion response, and one short time-series response before designing shared models.
  • Decide which fields your UI needs immediately and which fields your reporting layer needs later.
  • Keep base, date, amount, target currency, and time range in downstream records.
  • Use the FX guides and tutorials to validate how each response family flows into pricing or reporting logic.
Code examples

Visible integration examples

curl

curl -s -H "x-api-key: YOUR_API_KEY" "https://novadatahub.com/api/fx/rates?base=USD&symbols=EUR,GBP"

Python

import requests
rates = requests.get('https://novadatahub.com/api/fx/rates', params={'base': 'USD', 'symbols': 'EUR,GBP'}, headers={'x-api-key': 'YOUR_API_KEY'}, timeout=60).json()
print(rates.keys())

C# HttpClient

using System.Net.Http.Json;
using System.Text.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var json = await http.GetFromJsonAsync<JsonElement>("https://novadatahub.com/api/fx/rates?base=USD&symbols=EUR,GBP");
Console.WriteLine(json.ToString());

Sample JSON response

{
  "latest": {
    "ok": true,
    "base": "USD",
    "date": "2026-05-11",
    "rates": { "EUR": 0.92, "GBP": 0.78 }
  },
  "convert": {
    "ok": true,
    "from": "USD",
    "to": "EUR",
    "amount": 100,
    "rate": 0.92,
    "result": 92.0,
    "date": "2026-05-11"
  }
}
Related resources

Move from reference docs into the next relevant workflow

Currency Exchange API docs

Open the main rates reference page that pairs with these field notes.

Open docs

FX conversion docs

Compare direct-conversion fields against latest-rate fields.

Open docs

Historical FX docs

Compare time-series structures against current-rate fields.

Open docs

Historical FX tutorial

See how FX field handling flows into reporting pipelines.

Open tutorial
Related links

Continue with connected pages