---
title: "Get pair rate differentials"
method: GET
path: "/v1/rate_differentials/{base}/{quote}"
tags: ["fx_markets"]
---

# Get pair rate differentials

`GET /v1/rate_differentials/{base}/{quote}`

## Request

- Base URL: `https://api.fxmacrodata.com`
- URL: `https://api.fxmacrodata.com/v1/rate_differentials/{base}/{quote}`
- Auth: one of:
  - none
  - API key in header `X-API-Key`
  - HTTP bearer

Returns a historical differential between the base and quote currency using a shared rate measure. The endpoint aligns the two legs by date intersection and reports the spread in both percentage points and basis points.

**Measures:**
- Supported values: `auto`, `risk_free_rate`, `gov_bond_2y`, `gov_bond_10y`, `policy_rate`.
- `auto` prefers `risk_free_rate`, then `gov_bond_2y`, then `policy_rate`.

**Rate Types:**
- Supported values: `spot`, `forward`.
- `spot` compares the selected shared rate measure.
- `forward` derives each leg from government bond curve nodes, then aligns dates.

**Authentication:**
- Requires an Individual or Business API key via `?api_key=<key>` or `X-API-Key`.

## Path parameters

- `base` 'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CNH' | 'CNY' | 'DKK' | 'EUR' | 'GBP' | 'HUF' | 'ILS' | 'JPY' | 'KRW' | 'MYR' | 'NGN' | 'NOK' | 'NZD' | 'PEN' | 'SEK' | 'THB' | 'TWD' | 'USD', required: Base currency code
- `quote` 'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CNH' | 'CNY' | 'DKK' | 'EUR' | 'GBP' | 'HUF' | 'ILS' | 'JPY' | 'KRW' | 'MYR' | 'NGN' | 'NOK' | 'NZD' | 'PEN' | 'SEK' | 'THB' | 'TWD' | 'USD', required: Quote currency code

## Query parameters

- `measure` 'auto' | 'risk_free_rate' | 'gov_bond_2y' | 'gov_bond_10y' | 'policy_rate': Shared rate measure to compare across the pair.
- `rate_type` 'spot' | 'forward': Differential type: spot for shared rate measures, forward for derived curve segments.
- `curve_family` 'government_nominal': Curve family used when rate_type=forward.
- `start_tenor_years` number: Start tenor in years when rate_type=forward.
- `end_tenor_years` number: End tenor in years when rate_type=forward.
- `start_date` string: Inclusive start date YYYY-MM-DD. Defaults to 365 days ago.
- `end_date` string: Inclusive end date YYYY-MM-DD. Defaults to today.
- `limit` integer: Maximum rows to return. Defaults to 20. Maximum 100.
- `offset` integer: Number of rows to skip after most-recent-first ordering.
- `as_of` string, nullable: Explicit UTC information cutoff for verified vintage replay; date means start of day.
- `availability` string: Source-public or captured-value availability clock.
- `api_key` string: Your Individual or Business API key

## Response `200`

Successful Response

- RateDifferentialResponse
  - `research` object, nullable
  - `base` string, required
  - `quote` string, required
  - `rate_type` string
  - `measure_requested` string, required
  - `measure_used` string, required
  - `base_indicator` string, nullable
  - `quote_indicator` string, nullable
  - `curve_family` string, nullable
  - `start_tenor` string, nullable
  - `end_tenor` string, nullable
  - `forward_label` string, nullable
  - `start_date` string, required
  - `end_date` string, required
  - `matched_points` integer, required
  - `unit` string, required
  - `latest_spread` number, nullable
  - `latest_spread_bps` number, nullable
  - `latest_differential` number, nullable
  - `latest_differential_bps` number, nullable
  - `base_latest` number, nullable
  - `quote_latest` number, nullable
  - `sources` RateDifferentialSources, required: Publisher of each leg's rate. The spot path reports a single publisher name per leg; the curve and forward paths report the list of curve sources each leg was built from, so both shapes are declared.
    - `base` union
      - string
      - string[]
    - `quote` union
      - string
      - string[]
  - `official_forward_source_support` object: How the official publisher makes forward rates available, if at all.
    - `source_type` string, nullable
    - `source_note` string, nullable
  - `data_quality` DataQuality, required
    - `source_freshness` string, nullable
    - `source_monitoring_complete` boolean, nullable
    - `known_source_gap` boolean, nullable
    - `source_checked_at` integer, nullable
    - `source_check_expires_at` integer, nullable
    - `latest_published_period` string, nullable
    - `source_permission_status` string, nullable
    - `commodity_coverage` CommodityCoverage
      - `scope` string, required
      - `requested_start` string, nullable
      - `requested_end` string, nullable
      - `available_start` string, nullable
      - `available_end` string, nullable
      - `input_row_count` integer, required
      - `row_count` integer, required
      - `distinct_date_count` integer, required
      - `duplicate_date_row_count` integer, required
      - `excluded_weekend_row_count` integer, required
      - `invalid_date_row_count` integer, required
      - `expected_weekday_label_count` integer, required
      - `missing_weekday_label_count` integer, required
      - `largest_missing_weekday_run` integer, required
      - `largest_calendar_gap_days` integer, required
      - `missing_weekday_ranges` CommodityMissingWeekdayRange[], required
        - `start_date` string, required
        - `end_date` string, required
        - `weekday_count` integer, required
      - `longest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `latest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `sparse_history` boolean, required
      - `coverage_basis` string, required
      - `continuous_coverage_verified` boolean
      - `reference_only` boolean
      - `executable_quotes` boolean
      - `provenance_version` integer, required
      - `repaired_excluded_weekend_row_count` integer
      - `repaired_invalid_date_row_count` integer
    - `stored_history_coverage` CommodityCoverage
      - `scope` string, required
      - `requested_start` string, nullable
      - `requested_end` string, nullable
      - `available_start` string, nullable
      - `available_end` string, nullable
      - `input_row_count` integer, required
      - `row_count` integer, required
      - `distinct_date_count` integer, required
      - `duplicate_date_row_count` integer, required
      - `excluded_weekend_row_count` integer, required
      - `invalid_date_row_count` integer, required
      - `expected_weekday_label_count` integer, required
      - `missing_weekday_label_count` integer, required
      - `largest_missing_weekday_run` integer, required
      - `largest_calendar_gap_days` integer, required
      - `missing_weekday_ranges` CommodityMissingWeekdayRange[], required
        - `start_date` string, required
        - `end_date` string, required
        - `weekday_count` integer, required
      - `longest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `latest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `sparse_history` boolean, required
      - `coverage_basis` string, required
      - `continuous_coverage_verified` boolean
      - `reference_only` boolean
      - `executable_quotes` boolean
      - `provenance_version` integer, required
      - `repaired_excluded_weekend_row_count` integer
      - `repaired_invalid_date_row_count` integer
    - `point_in_time_basis` string, nullable
    - `is_official` boolean, required
    - `is_proxy` boolean, required
    - `is_fallback` boolean, required
    - `is_stale` boolean, required
    - `has_announcement_datetime` boolean, required
    - `point_in_time_safe` boolean, required: Whether the returned values have verified availability and vintage evidence; estimated release times do not qualify.
    - `unverified_vintage_count` integer
    - `unknown_publication_time_count` integer
    - `latest_available_date` string, nullable
    - `last_updated` string, nullable
    - `data_lag_days` integer, nullable
    - `source_name` string, nullable
    - `source_type` 'official' | 'public' | 'fallback' | 'derived', required
    - `is_derived` boolean
    - `row_count` integer
    - `announcement_datetime_count` integer
    - `missing_announcement_datetime_count` integer
    - `has_assumed_release_times` boolean: True when at least one row in the quality scope carries a publication timestamp derived from the publication lag measured on that series' own confirmed releases, because no official release calendar reaches the period.
    - `assumed_release_time_count` integer: Number of rows in the quality scope whose publication timestamp was derived rather than captured. Compare against row_count to size the derived portion of the requested window.
    - `bounded_release_time_count` integer: Legacy rows carrying an upper-bound estimate flag; this does not certify replay safety.
    - `unbounded_release_time_count` integer: Assumed timestamps without proven availability bounds.
    - `quality_scope` string
    - `stale_after_days` integer, nullable
    - `requested_window_has_data` boolean, nullable
    - `requested_window_latest_date` string, nullable
    - `requested_window_includes_latest_available` boolean, nullable
    - `page_includes_latest_available` boolean, nullable
    - `returned_latest_available_before_window` boolean, nullable
    - `staleness_days` integer, nullable
    - `reason` string, nullable
    - `datetime_field` string, nullable
    - `datetime_precision` string, nullable
    - `datetime_semantics` string, nullable
    - `source_legs` object[], nullable
    - `historical_point_in_time` PointInTimeCompleteness: Coverage of source-confirmed publication timestamps for a dataset.
      - `row_count` integer, required
      - `announcement_datetime_count` integer, required
      - `missing_announcement_datetime_count` integer, required
      - `assumed_release_time_count` integer
      - `bounded_release_time_count` integer
      - `unbounded_release_time_count` integer
      - `unverified_vintage_count` integer
      - `unknown_publication_time_count` integer
      - `point_in_time_safe` boolean, required
  - `pagination` object, required: Offset pagination state for one page of results.
    - `limit` integer, nullable
    - `offset` integer, nullable
    - `returned_count` integer, nullable
    - `total_count` integer, nullable
    - `has_more` boolean, nullable
    - `next_offset` integer, nullable
    - `page_includes_latest_available` boolean, nullable
  - `data` RateDifferentialPoint[], required
    - `date` string, required
    - `base_val` number, nullable
    - `quote_val` number, nullable
    - `spread` number, nullable
    - `spread_bps` number, nullable
    - `differential` number, nullable
    - `differential_bps` number, nullable
    - `base_forward_val` number, nullable
    - `quote_forward_val` number, nullable
    - `base_start_val` number, nullable
    - `base_end_val` number, nullable
    - `quote_start_val` number, nullable
    - `quote_end_val` number, nullable
    - `base_announcement_datetime` integer, nullable
    - `quote_announcement_datetime` integer, nullable
    - `base_start_announcement_datetime` integer, nullable
    - `base_end_announcement_datetime` integer, nullable
    - `quote_start_announcement_datetime` integer, nullable
    - `quote_end_announcement_datetime` integer, nullable
    - `base_selected_vintage_known_at_ns` string, nullable
    - `quote_selected_vintage_known_at_ns` string, nullable
    - `base_start_selected_vintage_known_at_ns` string, nullable
    - `base_end_selected_vintage_known_at_ns` string, nullable
    - `quote_start_selected_vintage_known_at_ns` string, nullable
    - `quote_end_selected_vintage_known_at_ns` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api.md) · [All operations](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api/revisions/fadaa543b154?raw)