> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar Events

> Integrate economic calendar events (FOMC, CPI) into trading pipelines. Time-decay sizing, event countdown, and pre-event risk reduction.

<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 theme={null}
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 theme={null}
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 theme={null}
{
    "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 theme={null}
countdown = hz.event_countdown(calendar_feed="calendar")
```

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

Returns each cycle:

```python theme={null}
{
    "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 theme={null}
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 theme={null}
{
    "size_multiplier": 0.75,
    "pre_event": True,
    "seconds_to_event": 43200.0,
    "event_name": "FOMC 2026-03-18",
}
```

***

## Examples

### Event-Aware Trading

```python theme={null}
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 theme={null}
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                   |