# How to Use FXMacroData Endpoints and Authentication

Canonical: https://fxmacrodata.com/articles/how-to-use-fxmacrodata-endpoints-and-authentication
Author: FXMacroData
Published: 2026-03-30T00:32:11Z

A practical end-to-end guide to authenticating with FXMacroData, choosing the right endpoint families, and building a production-ready macro data workflow.

By the end of this guide you will be able to authenticate correctly, choose the right endpoint family for each task, and make production-ready requests across the FXMacroData API without guessing route structure or indicator coverage.

### Prerequisites

- A FXMacroData account and API key for non-[USD](/united-states) requests

- A terminal with`curl`or a runtime like Python/Node.js

- Basic familiarity with JSON responses and URL query parameters

- Access to the live docs at[/documentation/](/documentation/)

## Step 1 - Start with the production base URL

All public examples should start from the production API base:

```
https://api.fxmacrodata.com/v1
```

The endpoint families you will use most are:

- `/announcements/{currency}/{indicator}`for historical released values with precise`announcement_datetime`

- `/calendar/{currency}`for upcoming release timestamps

- `/catalogue/{currency}`for discoverability of supported indicators

- `/cot/{currency}`for commitment-of-traders positioning

- `/commodities/{indicator}`for commodity and energy series

- `/forex/{pair}`and`/market-sessions`for market context

## Step 2 - Authenticate correctly with query parameters

FXMacroData uses query-parameter authentication in public usage examples:

```
?api_key=YOUR_API_KEY
```

USD endpoint access is available without a key, while non-USD routes require a valid key.

```
# USD endpoint (no key required)
curl "https://api.fxmacrodata.com/v1/announcements/usd/inflation"

# Non-USD endpoint (key required)
curl "https://api.fxmacrodata.com/v1/announcements/aud/policy_rate?api_key=YOUR_API_KEY"
```

## Step 3 - Discover what is available before coding

Call the catalogue route first when you are unsure which indicators exist for a currency. This avoids hard-coding assumptions.

```
curl "https://api.fxmacrodata.com/v1/catalogue/eur?api_key=YOUR_API_KEY"
```

Then use the indicator page index in[the documentation indicator index](/documentation/#indicator-index) to confirm route paths and expected fields.

## Step 4 - Pull released data from announcements endpoints

Announcement endpoints return a top-level object plus a`data`array of historical releases. Each row includes a period-end`date`, a`val`, and an`announcement_datetime`timestamp.

```
curl "https://api.fxmacrodata.com/v1/announcements/gbp/unemployment?api_key=YOUR_API_KEY"
```

```
{
  "currency": "GBP",
  "indicator": "unemployment",
  "has_official_forecast": false,
  "start_date": "2025-01-31",
  "end_date": "2026-03-31",
  "data": [
    {
      "date": "2026-01-31",
      "val": 4.39,
      "announcement_datetime": 1770521400
    }
  ]
}
```

For exact indicator semantics and units, check the endpoint pages such as[USD policy rate](/api-data-docs/usd/policy_rate) and[EUR inflation](/api-data-docs/eur/inflation) .

## Step 5 - Use the release calendar for event-driven workflows

The release calendar helps you schedule fetches around publication time instead of polling continuously.

```
curl "https://api.fxmacrodata.com/v1/calendar/usd?indicator=non_farm_payrolls&api_key=YOUR_API_KEY"
```

A robust pattern is: query calendar -> read next`announcement_datetime`-> fetch the matching announcements route at release time.

## Step 6 - Add supplementary endpoint families

Once your core announcements flow is stable, extend coverage with domain-specific routes:

- **COT:**`/api/v1/cot/{currency}`for futures positioning context

- **Metals:**`/api/v1/commodities/{indicator}`for gold, silver, platinum, and related safe-haven inputs

- **Forex:**`/api/v1/forex/{pair}`for spot alignment with macro releases

- **Market sessions:**`/api/v1/market-sessions`for session-state-aware automation

```
curl "https://api.fxmacrodata.com/v1/cot/usd"
curl "https://api.fxmacrodata.com/v1/commodities/gold"
curl "https://api.fxmacrodata.com/v1/forex/eur/usd?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/market-sessions"
```

## Step 7 - End-to-end Python example

The snippet below checks availability, fetches one indicator series, and returns the latest print.

```
import requests

BASE = "https://api.fxmacrodata.com/v1"
API_KEY = "YOUR_API_KEY"

def fetch_latest(currency: str, indicator: str, api_key: str | None = None) -> dict | None:
    params = {}
    if api_key:
        params["api_key"] = api_key

    catalogue = requests.get(f"{BASE}/catalogue/{currency}", params=params, timeout=10)
    catalogue.raise_for_status()

    endpoint = requests.get(
        f"{BASE}/announcements/{currency}/{indicator}",
        params=params,
        timeout=10,
    )
    endpoint.raise_for_status()

    rows = endpoint.json().get("data", [])
    return rows[-1] if rows else None

latest = fetch_latest("aud", "policy_rate", API_KEY)
print(latest)

```

## What you can build next

You now have the full path to authenticate, discover coverage, request historical release series, and expand into calendar-driven automation. A natural next step is pairing this workflow with the release scheduler in[How to Use the Release Calendar API](/articles/how-to-schedule-with-release-calendar) so your system reacts exactly when new macro data is published.

Source: FXMacroData