openbb-aurastream 0.1.0__tar.gz

openbb_aurastream-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+# Publishes to PyPI when a GitHub release is published, using PyPI trusted publishing (no token stored here).
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

openbb_aurastream-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,18 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install openbb -e ".[test]"
+      - run: python -c "import openbb; openbb.build()"
+      - run: python -m pytest -q

openbb_aurastream-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+dist/
+*.egg-info/
+.pytest_cache/

openbb_aurastream-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unbiased Alpha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openbb_aurastream-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: openbb-aurastream
+Version: 0.1.0
+Summary: AuraStream data for the OpenBB Platform: EU net short positions, USDA WASDE, FRED vintages, SEC fails-to-deliver and Binance funding rates.
+Project-URL: Homepage, https://aurastream.unbiased-alpha.com
+Project-URL: Documentation, https://aurastream.unbiased-alpha.com/docs/
+Project-URL: Source, https://github.com/UnbiasedAlpha/openbb-aurastream
+Author: Unbiased Alpha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aurastream,fred,market data,openbb,quant,short selling,wasde
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: openbb-core<3,>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# openbb-aurastream
+
+[AuraStream](https://aurastream.unbiased-alpha.com) data for the [OpenBB Platform](https://github.com/OpenBB-finance/OpenBB). The extension adds five commands under `obb.aurastream`. Each covers a dataset that the other OpenBB providers don't offer:
+
+| Command | Data |
+|---|---|
+| `net_short` | EU net short positions of 0.5% or more, with the holder's name, from the French (AMF), Dutch (AFM) and Spanish (CNMV) registers, back to 2010–2012 |
+| `wasde` | USDA WASDE projections since July 2010: US balance sheets and world tables by country, one row per monthly report |
+| `fred_vintages` | FRED series with every revision, stamped at the date each value was published |
+| `fails_to_deliver` | SEC fails-to-deliver for any US stock or ETF |
+| `funding_rates` | Binance USD-M perpetual funding rates |
+
+## Install
+
+```
+pip install openbb openbb-aurastream
+```
+
+OpenBB rebuilds its Python interface the first time you import it after installing.
+
+## Credentials
+
+You need an AuraStream API key. The free plan includes 500 calls a month, with no credit card required: [sign up here](https://aurastream.unbiased-alpha.com/sign-up).
+
+```python
+from openbb import obb
+
+obb.user.credentials.aurastream_api_key = "..."
+# Only for fred_vintages: your own free FRED key (https://fred.stlouisfed.org/docs/api/api_key.html)
+obb.user.credentials.aurastream_fred_api_key = "..."
+# Only for fails_to_deliver: the SEC asks automated requests to name the sender
+obb.user.credentials.aurastream_sec_user_agent = "Jane Doe jane@example.com"
+```
+
+You can also keep them in `~/.openbb_platform/user_settings.json`.
+
+## Examples
+
+```python
+from openbb import obb
+
+# Who is short Ubisoft, and by how much
+shorts = obb.aurastream.net_short("ubisoft", start_date="2024-01-01", country="FR").to_df()
+shorts.pivot_table(index=shorts.index.date, columns="holder", values="net_short_pct").ffill()
+
+# Every position one fund has disclosed
+obb.aurastream.net_short("all", holder="citadel", start_date="2026-01-01").to_df()
+
+# How the USDA's projection of US corn ending stocks changed, report by report
+corn = obb.aurastream.wasde("corn:ending_stocks", start_date="2024-01-01").to_df()
+corn["revision"] = corn["value"] - corn["previous"]
+
+# Brazil's soybean crop from the world tables
+obb.aurastream.wasde("soybeans:production:Brazil").to_df()
+
+# CPI as first published vs. after revisions
+cpi = obb.aurastream.fred_vintages("CPIAUCSL", start_date="2020-01-01").to_df()
+first_print = cpi.groupby("reference_date")["value"].first()
+latest = cpi.groupby("reference_date")["value"].last()
+
+# Fails-to-deliver in GameStop
+obb.aurastream.fails_to_deliver("GME", start_date="2024-01-01", end_date="2025-01-01").to_df()
+
+# Funding rates of the Bitcoin and Ether perpetuals
+obb.aurastream.funding_rates("BTCUSDT,ETHUSDT", start_date="2025-06-01").to_df()
+```
+
+Without `start_date`, each command returns the last year.
+
+## Timing
+
+All five datasets are historical, not real-time, and each row is stamped when the data became public:
+
+- EU net short positions are published by the next trading day, so lag them by one day in a backtest.
+- WASDE rows are stamped at the report's release, 12:00 New York time.
+- For `fred_vintages`, `start_date` and `end_date` filter on the publication date.
+- The SEC publishes fails-to-deliver twice a month, about two weeks after each half-month ends.
+
+See the [AuraStream docs](https://aurastream.unbiased-alpha.com/docs/) for the field definitions and coverage of each source.
+
+## Data terms
+
+- France: source Autorité des marchés financiers (AMF), data.gouv.fr, Licence Ouverte 2.0.
+- Netherlands: source AFM.
+- Spain: this information can be obtained free of charge from the CNMV website (www.cnmv.es).
+- Holder names can belong to individuals, so treat them as personal data under the GDPR.
+
+## License
+
+MIT. This package is by Unbiased Alpha and is not affiliated with OpenBB.

openbb_aurastream-0.1.0/README.md

@@ -0,0 +1,90 @@
+# openbb-aurastream
+
+[AuraStream](https://aurastream.unbiased-alpha.com) data for the [OpenBB Platform](https://github.com/OpenBB-finance/OpenBB). The extension adds five commands under `obb.aurastream`. Each covers a dataset that the other OpenBB providers don't offer:
+
+| Command | Data |
+|---|---|
+| `net_short` | EU net short positions of 0.5% or more, with the holder's name, from the French (AMF), Dutch (AFM) and Spanish (CNMV) registers, back to 2010–2012 |
+| `wasde` | USDA WASDE projections since July 2010: US balance sheets and world tables by country, one row per monthly report |
+| `fred_vintages` | FRED series with every revision, stamped at the date each value was published |
+| `fails_to_deliver` | SEC fails-to-deliver for any US stock or ETF |
+| `funding_rates` | Binance USD-M perpetual funding rates |
+
+## Install
+
+```
+pip install openbb openbb-aurastream
+```
+
+OpenBB rebuilds its Python interface the first time you import it after installing.
+
+## Credentials
+
+You need an AuraStream API key. The free plan includes 500 calls a month, with no credit card required: [sign up here](https://aurastream.unbiased-alpha.com/sign-up).
+
+```python
+from openbb import obb
+
+obb.user.credentials.aurastream_api_key = "..."
+# Only for fred_vintages: your own free FRED key (https://fred.stlouisfed.org/docs/api/api_key.html)
+obb.user.credentials.aurastream_fred_api_key = "..."
+# Only for fails_to_deliver: the SEC asks automated requests to name the sender
+obb.user.credentials.aurastream_sec_user_agent = "Jane Doe jane@example.com"
+```
+
+You can also keep them in `~/.openbb_platform/user_settings.json`.
+
+## Examples
+
+```python
+from openbb import obb
+
+# Who is short Ubisoft, and by how much
+shorts = obb.aurastream.net_short("ubisoft", start_date="2024-01-01", country="FR").to_df()
+shorts.pivot_table(index=shorts.index.date, columns="holder", values="net_short_pct").ffill()
+
+# Every position one fund has disclosed
+obb.aurastream.net_short("all", holder="citadel", start_date="2026-01-01").to_df()
+
+# How the USDA's projection of US corn ending stocks changed, report by report
+corn = obb.aurastream.wasde("corn:ending_stocks", start_date="2024-01-01").to_df()
+corn["revision"] = corn["value"] - corn["previous"]
+
+# Brazil's soybean crop from the world tables
+obb.aurastream.wasde("soybeans:production:Brazil").to_df()
+
+# CPI as first published vs. after revisions
+cpi = obb.aurastream.fred_vintages("CPIAUCSL", start_date="2020-01-01").to_df()
+first_print = cpi.groupby("reference_date")["value"].first()
+latest = cpi.groupby("reference_date")["value"].last()
+
+# Fails-to-deliver in GameStop
+obb.aurastream.fails_to_deliver("GME", start_date="2024-01-01", end_date="2025-01-01").to_df()
+
+# Funding rates of the Bitcoin and Ether perpetuals
+obb.aurastream.funding_rates("BTCUSDT,ETHUSDT", start_date="2025-06-01").to_df()
+```
+
+Without `start_date`, each command returns the last year.
+
+## Timing
+
+All five datasets are historical, not real-time, and each row is stamped when the data became public:
+
+- EU net short positions are published by the next trading day, so lag them by one day in a backtest.
+- WASDE rows are stamped at the report's release, 12:00 New York time.
+- For `fred_vintages`, `start_date` and `end_date` filter on the publication date.
+- The SEC publishes fails-to-deliver twice a month, about two weeks after each half-month ends.
+
+See the [AuraStream docs](https://aurastream.unbiased-alpha.com/docs/) for the field definitions and coverage of each source.
+
+## Data terms
+
+- France: source Autorité des marchés financiers (AMF), data.gouv.fr, Licence Ouverte 2.0.
+- Netherlands: source AFM.
+- Spain: this information can be obtained free of charge from the CNMV website (www.cnmv.es).
+- Holder names can belong to individuals, so treat them as personal data under the GDPR.
+
+## License
+
+MIT. This package is by Unbiased Alpha and is not affiliated with OpenBB.

openbb_aurastream-0.1.0/live_check.py

@@ -0,0 +1,32 @@
+"""Run each command once against the live AuraStream API (uses 5 calls).
+
+Reads the key from the AURASTREAM_API_KEY environment variable; FRED and
+fails-to-deliver run only when FRED_API_KEY / SEC_USER_AGENT are set too.
+"""
+
+import os
+
+from openbb import obb
+
+obb.user.credentials.aurastream_api_key = os.environ["AURASTREAM_API_KEY"]
+if os.environ.get("FRED_API_KEY"):
+    obb.user.credentials.aurastream_fred_api_key = os.environ["FRED_API_KEY"]
+if os.environ.get("SEC_USER_AGENT"):
+    obb.user.credentials.aurastream_sec_user_agent = os.environ["SEC_USER_AGENT"]
+
+checks = {
+    "net_short": lambda: obb.aurastream.net_short("ubisoft", start_date="2025-01-01", country="FR"),
+    "wasde": lambda: obb.aurastream.wasde("corn:ending_stocks", start_date="2025-06-01"),
+    "funding_rates": lambda: obb.aurastream.funding_rates("BTCUSDT", start_date="2025-06-01", end_date="2025-06-03"),
+}
+if os.environ.get("FRED_API_KEY"):
+    checks["fred_vintages"] = lambda: obb.aurastream.fred_vintages("CPIAUCSL", start_date="2025-01-01", end_date="2025-04-01")
+if os.environ.get("SEC_USER_AGENT"):
+    checks["fails_to_deliver"] = lambda: obb.aurastream.fails_to_deliver("GME", start_date="2024-05-01", end_date="2024-06-01")
+
+for name, call in checks.items():
+    try:
+        df = call().to_df()
+        print(f"OK   {name}: {len(df)} rows, columns {list(df.columns)[:6]}")
+    except Exception as exc:  # noqa: BLE001
+        print(f"FAIL {name}: {type(exc).__name__}: {str(exc)[:300]}")

openbb_aurastream-0.1.0/openbb_aurastream/__init__.py

@@ -0,0 +1,31 @@
+"""OpenBB AuraStream Provider Module."""
+
+from openbb_core.provider.abstract.provider import Provider
+
+from openbb_aurastream.models.fails_to_deliver import AuraStreamFailsToDeliverFetcher
+from openbb_aurastream.models.fred_vintages import AuraStreamFredVintagesFetcher
+from openbb_aurastream.models.funding_rates import AuraStreamFundingRatesFetcher
+from openbb_aurastream.models.net_short import AuraStreamNetShortFetcher
+from openbb_aurastream.models.wasde import AuraStreamWasdeFetcher
+
+aurastream_provider = Provider(
+    name="aurastream",
+    website="https://aurastream.unbiased-alpha.com",
+    description="AuraStream, a unified market data API for quants by Unbiased Alpha:"
+    " EU net short positions, USDA WASDE projections, FRED with every revision,"
+    " SEC fails-to-deliver and Binance funding rates.",
+    credentials=["api_key", "fred_api_key", "sec_user_agent"],
+    fetcher_dict={
+        "AuraStreamNetShort": AuraStreamNetShortFetcher,
+        "AuraStreamWasde": AuraStreamWasdeFetcher,
+        "AuraStreamFredVintages": AuraStreamFredVintagesFetcher,
+        "AuraStreamFailsToDeliver": AuraStreamFailsToDeliverFetcher,
+        "AuraStreamFundingRates": AuraStreamFundingRatesFetcher,
+    },
+    repr_name="AuraStream",
+    instructions="Get a free API key (500 calls a month, no credit card) at"
+    " https://aurastream.unbiased-alpha.com/sign-up and set it as aurastream_api_key."
+    " fred_vintages also needs your own free FRED key (aurastream_fred_api_key), and"
+    " fails_to_deliver a contact string for the SEC (aurastream_sec_user_agent),"
+    " e.g. 'Jane Doe jane@example.com'.",
+)

openbb_aurastream-0.1.0/openbb_aurastream/aurastream_router.py

@@ -0,0 +1,117 @@
+"""AuraStream Router."""
+
+from openbb_core.app.model.command_context import CommandContext
+from openbb_core.app.model.example import APIEx
+from openbb_core.app.model.obbject import OBBject
+from openbb_core.app.provider_interface import (
+    ExtraParams,
+    ProviderChoices,
+    StandardParams,
+)
+from openbb_core.app.query import Query
+from openbb_core.app.router import Router
+
+router = Router(prefix="", description="AuraStream market data.")
+
+
+@router.command(
+    model="AuraStreamNetShort",
+    examples=[
+        APIEx(
+            description="Disclosed short positions in Ubisoft on the French register.",
+            parameters={"symbol": "ubisoft", "country": "FR", "provider": "aurastream"},
+        ),
+        APIEx(
+            description="Every position one fund has disclosed in the period.",
+            parameters={"symbol": "all", "holder": "citadel", "provider": "aurastream"},
+        ),
+    ],
+)
+async def net_short(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get disclosed net short positions of 0.5% or more in European shares (AMF, AFM, CNMV)."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamWasde",
+    examples=[
+        APIEx(
+            description="How the USDA's projection of US corn ending stocks changed, report by report.",
+            parameters={"symbol": "corn:ending_stocks", "provider": "aurastream"},
+        ),
+        APIEx(
+            description="Brazil's soybean crop from the world tables.",
+            parameters={"symbol": "soybeans:production:Brazil", "provider": "aurastream"},
+        ),
+    ],
+)
+async def wasde(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get USDA WASDE projections since July 2010, one row per monthly report."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamFredVintages",
+    examples=[
+        APIEx(
+            description="Every published version of US CPI, by publication date.",
+            parameters={"symbol": "CPIAUCSL", "provider": "aurastream"},
+        ),
+    ],
+)
+async def fred_vintages(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get FRED series with every revision, stamped at the date each value was published."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamFailsToDeliver",
+    examples=[
+        APIEx(
+            description="Fails-to-deliver in GameStop.",
+            parameters={"symbol": "GME", "provider": "aurastream"},
+        ),
+    ],
+)
+async def fails_to_deliver(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get SEC fails-to-deliver for a US stock or ETF, one row per settlement date."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamFundingRates",
+    examples=[
+        APIEx(
+            description="Funding rates of the Bitcoin and Ether perpetuals.",
+            parameters={"symbol": "BTCUSDT,ETHUSDT", "provider": "aurastream"},
+        ),
+    ],
+)
+async def funding_rates(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get Binance USD-M perpetual funding rates at each funding time."""
+    return await OBBject.from_query(Query(**locals()))

openbb_aurastream-0.1.0/openbb_aurastream/models/__init__.py

@@ -0,0 +1 @@
+"""AuraStream models."""

openbb_aurastream-0.1.0/openbb_aurastream/models/fails_to_deliver.py

@@ -0,0 +1,99 @@
+"""AuraStream Fails-to-Deliver Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from pydantic import Field
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    require_key,
+    split_symbols,
+    to_rows,
+)
+
+
+class AuraStreamFailsToDeliverQueryParams(SeriesQueryParams):
+    """AuraStream Fails-to-Deliver Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/edgar/
+    """
+
+    __json_schema_extra__ = {"symbol": {"multiple_items_allowed": True}}
+
+    symbol: str = Field(
+        description="US stock or ETF symbol (e.g. 'GME') or 9-character CUSIP."
+    )
+    start_date: dateType | None = Field(
+        default=None, description="Start date. Default: one year ago."
+    )
+    end_date: dateType | None = Field(
+        default=None, description="End date. Default: today."
+    )
+
+
+class AuraStreamFailsToDeliverData(Data):
+    """AuraStream Fails-to-Deliver Data. One row per settlement date with fails outstanding."""
+
+    date: datetime = Field(description="Settlement date.")
+    symbol: str = Field(description="Security symbol.")
+    fails: int | None = Field(
+        default=None, description="Total fails-to-deliver balance, in shares."
+    )
+    price: float | None = Field(
+        default=None, description="Previous day's closing price."
+    )
+    cusip: str | None = Field(default=None, description="CUSIP of the security.")
+    description: str | None = Field(default=None, description="Security description.")
+
+
+class AuraStreamFailsToDeliverFetcher(
+    Fetcher[AuraStreamFailsToDeliverQueryParams, list[AuraStreamFailsToDeliverData]]
+):
+    """Fetch SEC fails-to-deliver from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamFailsToDeliverQueryParams:
+        """Transform the query."""
+        return AuraStreamFailsToDeliverQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamFailsToDeliverQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return the raw rows."""
+        key = api_key(credentials)
+        user_agent = require_key(
+            credentials,
+            "aurastream_sec_user_agent",
+            "The SEC asks every automated request to name the sender: your name or company"
+            " and a contact email, e.g. 'Jane Doe jane@example.com'.",
+        )
+        symbols = [s.upper() for s in split_symbols(query.symbol)]
+        body = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1d",
+            "source": "edgar",
+            "dataset": "ftd",
+            "credentials": {"user_agent": user_agent},
+        }
+        data = await fetch(body, key)
+        return to_rows(data, symbols)
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamFailsToDeliverQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamFailsToDeliverData]:
+        """Transform the data."""
+        return [AuraStreamFailsToDeliverData.model_validate(d) for d in data]

openbb_aurastream-0.1.0/openbb_aurastream/models/fred_vintages.py

@@ -0,0 +1,112 @@
+"""AuraStream FRED Vintages Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from openbb_core.provider.utils.errors import EmptyDataError
+from pydantic import Field
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    parse_timestamp,
+    require_key,
+    split_symbols,
+)
+
+
+class AuraStreamFredVintagesQueryParams(SeriesQueryParams):
+    """AuraStream FRED Vintages Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/fred/
+    """
+
+    __json_schema_extra__ = {"symbol": {"multiple_items_allowed": True}}
+
+    symbol: str = Field(
+        description="FRED series ID, e.g. 'CPIAUCSL', 'UNRATE', 'GDPC1'."
+    )
+    start_date: dateType | None = Field(
+        default=None,
+        description="First publication date. Default: one year ago.",
+    )
+    end_date: dateType | None = Field(
+        default=None, description="Last publication date. Default: today."
+    )
+
+
+class AuraStreamFredVintagesData(Data):
+    """AuraStream FRED Vintages Data. One row per published value."""
+
+    date: datetime = Field(description="Publication date of the value.")
+    symbol: str = Field(description="FRED series ID.")
+    reference_date: datetime = Field(description="The period the value describes.")
+    value: float | None = Field(default=None, description="The value as published.")
+
+
+class AuraStreamFredVintagesFetcher(
+    Fetcher[AuraStreamFredVintagesQueryParams, list[AuraStreamFredVintagesData]]
+):
+    """Fetch every published version of FRED series from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamFredVintagesQueryParams:
+        """Transform the query."""
+        return AuraStreamFredVintagesQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamFredVintagesQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return one row per (publication date, period)."""
+        key = api_key(credentials)
+        fred_key = require_key(
+            credentials,
+            "aurastream_fred_api_key",
+            "FRED needs a free key of your own: https://fred.stlouisfed.org/docs/api/api_key.html.",
+        )
+        symbols = [s.upper() for s in split_symbols(query.symbol)]
+        body = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1d",  # ignored: each series comes at its own frequency
+            "source": "fred",
+            "credentials": {"key": fred_key},
+        }
+        data = await fetch(body, key)
+
+        rows: list[dict] = []
+        for symbol in symbols:
+            series = data.get(symbol)
+            if not isinstance(series, dict):
+                continue
+            for published, row in series.items():
+                for update in (row or {}).get("updates") or []:
+                    rows.append(
+                        {
+                            "date": parse_timestamp(published),
+                            "symbol": symbol,
+                            "reference_date": parse_timestamp(update["reference_date"]),
+                            "value": update.get("value"),
+                        }
+                    )
+        if not rows:
+            raise EmptyDataError(f"AuraStream returned no data for {', '.join(symbols)}.")
+        rows.sort(key=lambda r: (r["date"], r["symbol"], r["reference_date"]))
+        return rows
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamFredVintagesQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamFredVintagesData]:
+        """Transform the data."""
+        return [AuraStreamFredVintagesData.model_validate(d) for d in data]