> For the complete documentation index, see [llms.txt](https://bluegamma.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluegamma.io/documentation/integrations/api/how-to-guides/fetching-central-bank-probabilities.md).

# Fetching Central Bank Probabilities

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](/documentation/methodology/central-bank-probabilities.md).

***

## Example: Next Decision

```python
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())
```

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

**Response:**

```json
{
  "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.

***

## Example: Probability Matrix

```bash
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):**

```json
{
  "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 timestamp can trail by up to a day 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.

{% hint style="info" %}
The probabilities are market-implied, risk-neutral reads of traded rates, not forecasts. See the [methodology page](/documentation/methodology/central-bank-probabilities.md) for the construction, assumptions and limitations.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bluegamma.io/documentation/integrations/api/how-to-guides/fetching-central-bank-probabilities.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.