How to Use FXMacroData Through Roboquant for Macro-Event Blackouts

Roboquant is an open-source Kotlin algorithmic trading platform for backtesting, notebooks, and live-trading workflows. The FXMacroData integration in the Roboquant repository is intentionally narrow: it shows how to use the FXMacroData release calendar as a macro-event risk gate around an existing strategy.

The sample pairs FXMacroData calendar data with Roboquant's normal strategy flow. In the repository example, an EMACrossover strategy still creates the trading idea, while a MacroBlackoutStrategy decides whether macro-event timing should suppress signals for that event.

Why Roboquant Works for Calendar Guardrails

Roboquant strategies receive time-stamped events and return signals. That makes macro-event gating a clean wrapper problem: fetch a calendar before the run, convert high-impact releases into blackout dates or windows, and let the wrapper decide whether the delegated strategy should run for the current event time.

The Roboquant sample uses three simple pieces:

Workflow Shape

The integration is easiest to reason about as a pre-run guardrail. Fetch the calendar once, build a set of blocked dates or windows, then pass that set into a strategy wrapper.

Step 1: Start from the Roboquant Sample

Start with the Roboquant repository and the sample file at roboquant/test/org/roboquant/samples/FxMacroDataCalendarSample.kt. Roboquant can be used as a Maven, Gradle, or Kotlin Toolchain dependency; the repository README shows the current dependency pattern and points to the Roboquant tutorial.

implementation group: 'org.roboquant', name: 'roboquant', version: 'VERSION'

The sample is marked as an ignored test, which is appropriate for an external API example. Use it as a template for your own project rather than treating it as a unit test that should run in every build.

Step 2: Fetch the FXMacroData Release Calendar

Inspect the calendar endpoint first. Public examples send the API key in the X-API-Key header when one is required. USD release-calendar rows are available for this kind of check without exposing a secret.

curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/calendar/USD?start_date=2026-07-01&end_date=2026-07-20"

The response includes the currency, timezone, quality metadata, and event rows. The fields that matter for this Roboquant use case are announcement_datetime, announcement_datetime_utc, release, name, market_tier, top_tier_for_currency, and release_date_confirmed.

The repository sample keeps the parser compact by filtering JSON text for top-tier events. In production code, parse the response with a JSON library and keep the raw response or normalized blackout set with your backtest artifacts.

private fun topTierBlackoutDates(rows: CalendarResponse): Set<LocalDate> {
    return rows.data
        .filter { it.topTierForCurrency || it.marketTier == 1 }
        .map { it.announcementDateTime.atZone(ZoneOffset.UTC).toLocalDate() }
        .toSet()
}

Step 3: Wrap the Strategy

Once the blackout set exists, the strategy wrapper is small. If the current Roboquant event falls inside the blackout set, return no signals. Otherwise, ask the delegated strategy to create signals normally.

private class MacroBlackoutStrategy(
    private val delegate: Strategy,
    private val blackoutDates: Set<LocalDate>,
    private val zoneId: ZoneId = ZoneOffset.UTC
) : Strategy {
    override fun createSignals(event: Event): List<Signal> {
        val eventDate = event.time.atZone(zoneId).toLocalDate()
        if (eventDate in blackoutDates) return emptyList()
        return delegate.createSignals(event)
    }
}

That wrapper is deliberately conservative. It does not change the feed, mutate account state, or modify the base strategy. It only controls whether the strategy is allowed to emit signals during macro-event risk.

Backtest Guardrails

A macro blackout filter is easy to add and easy to misuse. Keep the guardrail explicit so the backtest remains explainable.

The right blackout width depends on the strategy. A daily strategy may use the sample's date-level approach. A short-horizon intraday strategy should usually use the exact release timestamp, a pre-event buffer, and a post-event cooldown.

Related Links

• Open source FXMacroData integrations
• FXMacroData release calendar
• FXMacroData API quickstart
• FXMacroData API reference

Sources and References

• Roboquant open-source repository
• Roboquant FXMacroData calendar sample
• Roboquant tutorial
• FXMacroData OpenAPI schema

With that setup, FXMacroData gives Roboquant a scheduled-event risk layer: fetch the calendar once, choose the blackout rule, wrap the strategy, and make every suppressed signal visible in the backtest record.