---
title: "Calendar Events"
description: "Integrate economic calendar events (FOMC, CPI) into trading pipelines. Time-decay sizing, event countdown, and pre-event risk reduction."
icon: "calendar"
---

<Warning>
  **Ultra Feature.** Requires an Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)
</Warning>

# Calendar Events

Major economic events (FOMC decisions, CPI releases) cause sharp moves in prediction markets. Horizon's calendar module provides a live event feed, bundled FOMC/CPI dates through 2026, and pipeline functions for time-decay sizing and pre-event risk reduction. The feed maps event data to standard FeedSnapshot fields for seamless pipeline integration.

## Overview

<CardGroup cols={2}>
  <Card title="Event Feed" icon="satellite-dish">
    `CalendarFeed` tracks the nearest event with seconds-to-event countdown.
  </Card>
  <Card title="Time Decay" icon="hourglass-half">
    `hz.time_decay()` reduces position size as events approach.
  </Card>
  <Card title="Event Countdown" icon="clock">
    `hz.event_countdown()` exposes event data for downstream use.
  </Card>
  <Card title="Pre-Event Strategy" icon="shield-halved">
    `hz.pre_event_strategy()` automatically reduces exposure before events.
  </Card>
</CardGroup>

---

## Feed

### CalendarFeed

Parses bundled or custom event data and tracks the nearest future event.

```python
import horizon as hz

# Uses bundled FOMC + CPI dates automatically
feed = hz.CalendarFeed()

# Or with a custom API
feed = hz.CalendarFeed(api_url="https://api.example.com/events")
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `events_json` | `str` | bundled dates | JSON array of event objects |
| `api_url` | `str` | `""` | Optional REST API for event data |
| `interval` | `float` | `300.0` | Poll interval in seconds |

Bundled events include FOMC meeting dates and CPI release dates from 2024 through 2026.

FeedSnapshot mapping:
- `price` = urgency score (0.0 to 1.0, higher as event approaches)
- `bid` = seconds to next event
- `ask` = event type code (FOMC=1.0, CPI=2.0, NFP=3.0, GDP=4.0, EARNINGS=5.0)
- `volume_24h` = days to next event
- `source` = `"calendar:EVENT_NAME"`

---

## Pipeline Functions

### hz.time_decay

Reduce position size as events approach.

```python
decay = hz.time_decay(
    calendar_feed="calendar",
    max_days=30.0,
    decay_type="linear",  # or "exponential", "sqrt"
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `calendar_feed` | `str` | `"calendar"` | Feed name for calendar data |
| `max_days` | `float` | `30.0` | Days at which decay factor reaches 1.0 |
| `decay_type` | `str` | `"linear"` | Decay curve: `linear`, `exponential`, or `sqrt` |

Returns each cycle:

```python
{
    "time_decay_factor": 0.67,   # multiply position size by this
    "days_to_event": 20.0,
    "event_urgency": 0.33,
    "event_type_code": 1.0,      # FOMC
}
```

### hz.event_countdown

Expose raw event countdown data for downstream pipeline use.

```python
countdown = hz.event_countdown(calendar_feed="calendar")
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `calendar_feed` | `str` | `"calendar"` | Feed name |

Returns each cycle:

```python
{
    "seconds_to_event": 172800.0,
    "event_name": "FOMC 2026-03-18",
    "event_type_code": 1.0,
    "urgency": 0.33,
    "days_to_event": 2.0,
}
```

### hz.pre_event_strategy

Automatically reduce exposure as events approach, with a linear ramp.

```python
pre_event = hz.pre_event_strategy(
    calendar_feed="calendar",
    reduce_hours=24.0,      # start reducing 24h before
    reduce_factor=0.5,      # minimum 50% of normal size
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `calendar_feed` | `str` | `"calendar"` | Feed name |
| `reduce_hours` | `float` | `24.0` | Hours before event to start reducing |
| `reduce_factor` | `float` | `0.5` | Minimum size multiplier at event time |

Returns each cycle:

```python
{
    "size_multiplier": 0.75,
    "pre_event": True,
    "seconds_to_event": 43200.0,
    "event_name": "FOMC 2026-03-18",
}
```

---

## Examples

### Event-Aware Trading

```python
import horizon as hz

def my_strategy(ctx):
    if ctx.feed is None or ctx.feed.price <= 0:
        return []
    multiplier = ctx.params.get("size_multiplier", 1.0)
    size = int(10 * multiplier)
    if size < 1:
        return []
    return hz.quotes(fair=ctx.feed.price, spread=0.04, size=size)

hz.run(
    name="event_aware",
    exchange=hz.Polymarket(),
    feeds={
        "market": hz.PolymarketBook("will-fed-cut-rates"),
        "calendar": hz.CalendarFeed(),
    },
    pipeline=[
        hz.pre_event_strategy(reduce_hours=24, reduce_factor=0.3),
        hz.time_decay(max_days=7, decay_type="sqrt"),
        my_strategy,
    ],
)
```

### Custom Event Data

```python
import json
import horizon as hz

events = [
    {"name": "Earnings AAPL", "timestamp": 1711900800, "type": "earnings"},
    {"name": "Custom Event", "timestamp": 1712000000, "type": "other"},
]

feed = hz.CalendarFeed(events_json=json.dumps(events))
```

---

## Event Type Codes

| Code | Event Type |
|------|-----------|
| 1.0 | FOMC |
| 2.0 | CPI |
| 3.0 | NFP (Non-Farm Payrolls) |
| 4.0 | GDP |
| 5.0 | Earnings |
| 6.0 | PPI |
| 7.0 | PCE |
| 99.0 | Other |
