Fetching Central Bank Probabilities

Retrieve market-implied hike, hold and cut probabilities for scheduled central bank decisions, and the full probability matrix over rate levels.

Two endpoints cover central bank decision pricing: /central_bank_probabilities returns the headline view for the next scheduled decision, and /central_bank_probability_matrix returns the full distribution over rate levels for every scheduled meeting in the horizon. Both cover the Fed (USD), ECB (EUR), BoE (GBP), BoJ (JPY), BoC (CAD), RBA (AUD), SNB (CHF) and RBNZ (NZD).

The construction behind the numbers is documented in Central Bank Decision Probabilities.

---

Example: Next Decision

import requests

url = "https://api.bluegamma.io/v1/central_bank_probabilities"
headers = {"x-api-key": "your_api_key"}

params = {
    "currency": "GBP"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

curl -X GET "https://api.bluegamma.io/v1/central_bank_probabilities?currency=GBP" \
  -H "x-api-key: your_api_key_here"

Response:

{
  "currency": "GBP",
  "meeting_date": "2026-09-17",
  "provisional_meeting_date": false,
  "current_policy_rate": 3.75,
  "target_range": null,
  "hike_probability": 18.87,
  "hold_probability": 81.13,
  "cut_probability": 0.0,
  "base_case": "Hold",
  "observation_basis": "intraday",
  "valuation_time": "2026-08-06T15:15:57",
  "timestamp": "2026-08-06T14:15:15"
}

Omit currency to get all eight banks in one call. Probabilities are percentages and sum to 100. For the Fed, current_policy_rate is the target-range midpoint with the bounds in target_range; single-rate banks return the policy rate itself and target_range null. Between a decision's announcement and its effective date (mainly ECB weeks), pending_rate and pending_rate_effective_date carry the announced rate that expected rates are anchored to while current_policy_rate still shows the rate in force; both are null at all other times.

---

Example: Probability Matrix

curl -X GET "https://api.bluegamma.io/v1/central_bank_probability_matrix?currency=USD&horizon_months=18" \
  -H "x-api-key: your_api_key_here"

Response (excerpt):

{
  "currency": "USD",
  "current_policy_rate": 3.625,
  "target_range": { "low": 3.5, "high": 3.75 },
  "step_bp": 25,
  "matrix": [
    {
      "rate_level": 3.875,
      "probabilities": [
        { "meeting_date": "2026-09-16", "probability": 60.4 },
        { "meeting_date": "2026-10-28", "probability": 55.49 },
        { "meeting_date": "2027-12-08", "probability": null }
      ]
    }
  ],
  "meetings": [
    {
      "meeting_date": "2026-09-16",
      "days_until": 41,
      "provisional": false,
      "implied_change_bp": 15.1,
      "expected_rate": 3.776,
      "cut_probability": 0.0,
      "hold_probability": 39.6,
      "hike_probability": 60.4,
      "base_case": "Hike"
    }
  ],
  "observation_basis": "intraday",
  "valuation_time": "2026-08-06T15:15:44",
  "timestamp": "2026-08-06T14:15:15"
}

matrix rows are rate levels (descending); each cell carries its own meeting_date, in the same chronological order as meetings. horizon_months defaults to 18 and accepts 1 to 36.

---

Reading the Response Correctly

Four conventions matter for a correct integration:

1. Matrix width is variable. Rows are the levels that carry probability over the horizon, and the distribution widens by one level per priced meeting, so row counts differ by currency (the SNB's quarterly calendar gives around five rows; the ECB's deep calendar can give twelve) and change over time. Treat row count as fully dynamic.

2. Null and zero mean different things. The final decision a bank has published cannot be priced until the bank schedules the meeting after it (its pricing window has no close). That decision appears as a real column with its date and provisional flag populated and every derived value null. A null therefore means "published but not yet priceable" and resolves automatically when the next meeting is scheduled. A zero inside a priced column is a genuine market statement that a level is unreachable, never missing data.

3. Per-meeting cut/hold/hike are cumulative versus today's rate. hike_probability for a meeting is the total probability of being above the current level at that meeting, not the chance of a hike at that specific meeting. The three always sum to 100, and the next-decision endpoint always equals the first matrix column aggregated, so the two endpoints cannot disagree.

4. Two timestamps, one label. valuation_time is the as-of your request was answered for; timestamp is when the underlying market data is from; staleness is the difference. observation_basis labels each currency's data cadence: "intraday" for seven currencies, "eod" for NZD, whose curve is a once-daily close added on the following business day, so its timestamp can trail by more than a day (longer over weekends and holidays) as declared cadence rather than a fault.

---

Historical Snapshots

Both endpoints accept valuation_time (ISO 8601, interpreted as UTC) like the other rate endpoints. Requests for valuation dates the meeting calendar cannot support are rejected with a 422 rather than answered approximately.

The probabilities are market-implied, risk-neutral reads of traded rates, not forecasts. See the methodology page for the construction, assumptions and limitations.