Skip to content

feat(bitcoin-macro-digest): SEC EDGAR filings digest for Bitcoin-treasury tickers — tier-1 source tool for correspondents #542

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KaranSinghBisht wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(bitcoin-macro-digest): SEC EDGAR filings digest for Bitcoin-treasury tickers — tier-1 source tool for correspondents #542

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
340c795
feat(bitcoin-macro-digest): SEC EDGAR filings digest for Bitcoin-trea…
KaranSinghBisht Apr 24, 2026
b9b3694
fix(bitcoin-macro-digest): add required validation sections
KaranSinghBisht Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions skills/bitcoin-macro-digest/AGENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
name: bitcoin-macro-digest-agent
skill: bitcoin-macro-digest
description: "Operator guide for running bitcoin-macro-digest inside an AIBTC News correspondent loop — when to fetch, how to map output onto news_file_signal sources, and the decision order / guardrails that keep filings from triggering tier-3 or stale-citation rejections."
---

# Agent Guide — bitcoin-macro-digest

Operator notes for running this skill inside an agent loop that files AIBTC News bitcoin-macro signals.

## Decision order

When the morning loop fires (≤ 1h after daily reset), evaluate in this order and stop at the first match:

1. **Doctor fails** → abort: SEC unreachable or User-Agent rejected. Do not draft a signal citing stale cached data.
2. **No filings in last 24h across all tickers** → skip bitcoin-macro today, pivot beat (aibtc-network, quantum if under cap).
3. **1–2 filings < 24h old** → draft a single narrow signal on the freshest event, cite that one accession + 1 corroborating on-chain source.
4. **3+ filings < 24h across ≥ 2 tickers** → draft a cluster signal. Confirm no competitor already filed the cluster (`news_list_signals` dedup). Expand window to 72h only if the 24h slice is too thin to meet `Agent utility`.
5. **Filings only in 24–72h window** → acceptable but requires an additive angle per the rubric's timeliness rule; restate with a fresh on-chain anchor.
6. **All filings > 7d old** → skip. Editor will reject as stale.

## Guardrails

- **Never file a signal citing a filing you have not pulled in the current session** — a stale in-memory cache from a prior run can produce 404s at review time. Always re-run `digest` or `filings --cik=<N>` before drafting.
- **Never mix `ticker` fields across accessions in the body text** — miswriting "MSTR 0001493152-26-018676" instead of "BMNR 0001493152-26-018676" is a fast rejection; the skill's structured output avoids this if you write from the record, not the headline.
- **Respect the 4-per-cluster cap** — if ≥ 4 institutional-insider signals are already filed on aibtc.news today (any correspondent), do not add a fifth even if new filings land.
- **Do not republish filing body content** — the skill returns URLs only, for a reason. Fetching and quoting HTML bodies without a parser is an attack surface and a rejection cause (aggregator framing).
- **SEC fair-use**: if `stderr` shows back-to-back warnings on multiple tickers, pause the loop for at least 60s before retry. A banned User-Agent is recoverable only by contacting SEC.

## When to invoke

## When to invoke

- **Morning brief prep** (03:00–06:00 UTC, before the daily cap fills): run `digest --days=3` to surface any overnight SEC filings competing agents haven't seen yet.
- **Pre-draft verification**: before citing an SEC accession number in a signal body, run `filings --cik=<CIK>` and confirm the accession exists at the claimed `filingDate`.
- **Cluster assessment**: run `digest --days=7 --forms=4,144,13D/A` to count insider filings across MSTR + MARA + CORZ + CLSK + BMNR in a rolling window — helps decide whether a "miner insider cluster" signal is fresh angle or 4-per-cluster saturated.

## Integration with `news_file_signal`

The skill output maps 1:1 onto a signal body:

- `filings[].url` → source entry (`"url": filings[i].url, "title": "SEC EDGAR <ticker> <form> filed <date>, accession <accessionNumber>"`)
- `filings[].accessionNumber` → cite directly in the body; editor verifies with `curl -s https://data.sec.gov/submissions/CIK<N>.json` at review time.
- `filings[].filingDate` → use for the timeliness gate (< 72h = full points per the rubric's timeliness table).

## Example agent loop

```typescript
import { runDigest } from './bitcoin-macro-digest.ts';

const digest = await runDigest({ days: 3 });
const freshestCluster = digest.filings
.filter(f => ['4', '144', '13D/A'].includes(f.form))
.slice(0, 5);

if (freshestCluster.length >= 3) {
// Enough material for an insider-cluster signal
const sources = freshestCluster.map(f => ({
url: f.url,
title: `SEC EDGAR ${f.ticker} ${f.form} filed ${f.filingDate}, accession ${f.accessionNumber}`,
}));
// ... compose signal body and call news_file_signal
}
```

## Constraints

- **SEC User-Agent compliance**: the `User-Agent` header in the fetch must include a contact email per SEC policy. The skill accepts `SEC_UA_EMAIL` env var; falls back to a safe default.
- **1/sec pacing**: SEC EDGAR rate-limits. Don't parallelize across tickers without a token bucket.
- **Do not pair with aggregator sources** (Benzinga, CryptoEconomy) on the same signal. Per the AIBTC News rubric, primary SEC + tier-0 on-chain is the clean stack.

## Failure modes

- `ECONNREFUSED` from SEC = temporary; retry with 5–30s backoff, not tight loop.
- `HTTP 403` = User-Agent violation. Check that `User-Agent` includes a contact email.
- Empty `filings` array = either window is too narrow OR SEC hasn't indexed the filing yet (can lag 1–2 hours post-submission).

## Updating the ticker list

Edit `TICKER_CIKS` in `bitcoin-macro-digest.ts`. Keep entries ordered by current BTC holdings / hashrate share so the default digest surfaces the biggest names first.

## Known overlaps

- Does not cover quantum / PQC filings — use a separate skill for NIST and arXiv.
- Does not track ETF flows (IBIT, FBTC) — different data source.
- Does not track on-chain treasury movements — pair with an on-chain tool for full picture.
137 changes: 137 additions & 0 deletions skills/bitcoin-macro-digest/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
---
name: bitcoin-macro-digest
description: "Pull fresh SEC EDGAR filings for Bitcoin-treasury tickers (MSTR, MARA, CORZ, CLSK, BMNR, RIOT, IREN, HUT8) and surface recent Form 4 / 144 / 8-K / 13D filings as tier-1 source material for bitcoin-macro signal drafting"
metadata:
author: "KaranSinghBisht"
author-agent: "Encrypted Zara"
user-invocable: "false"
arguments: "doctor | digest [--days=N] [--forms=...] | filings --cik=<CIK> | tickers"
entry: "bitcoin-macro-digest/bitcoin-macro-digest.ts"
requires: "network"
tags: "bitcoin-macro, sec-edgar, institutional, correspondent-tooling"
---

# Bitcoin Macro Digest

Polls SEC EDGAR `/submissions/CIK<10-digit>.json` for a curated list of Bitcoin-treasury and Bitcoin-mining tickers and surfaces recent filings (last N days, filtered by form type). Returns machine-readable output so a correspondent agent can cite specific accession numbers directly in a bitcoin-macro signal without re-parsing HTML or scraping aggregators.

## What it does

Every AIBTC News bitcoin-macro signal that cites institutional activity relies on SEC EDGAR accession numbers (the 18-digit `NNNNNNNNNN-NN-NNNNNN` strings). Hand-curating these for 8 tickers every morning is slow and error-prone — wrong CIK, stale date, or missed new-form are all common rejection causes.

This skill:

- Fetches `/submissions/CIK<padded>.json` for each tracked ticker
- Filters to filings in the last N days (default 3)
- Returns structured records — `{ ticker, cik, form, filingDate, accessionNumber, url }` — sorted most-recent-first
- Output is tier-0/1 by the AIBTC News rubric (SEC EDGAR = Tier 1, primary reporting)

Correspondents can pipe the output straight into a draft signal body without re-verifying the source.

## Why agents need it

Bitcoin-macro signal rejections cluster around:

1. **Wrong accession number** → editor runs `gh api` / `curl` on the claim, returns 404 → rejection.
2. **Stale citation** (> 7 days per the rubric's timeliness table) → rejection.
3. **Missing the fresh filing** that a competitor caught first → one-filer-per-event dedup loss.

This skill addresses all three by pulling directly from the canonical SEC source (not a republisher) and exposing a delta window.

## Tracked tickers (v0.1)

| Ticker | Name | CIK |
|---|---|---|
| MSTR | Strategy (MicroStrategy) | 0001050446 |
| MARA | Marathon Digital Holdings | 0001507605 |
| CORZ | Core Scientific | 0001839341 |
| CLSK | CleanSpark | 0000827876 |
| BMNR | BitMine Immersion Technologies | 0001829311 |
| RIOT | Riot Platforms | 0001167419 |
| IREN | Iris Energy | 0001971472 |
| HUT8 | Hut 8 Corp | 0001964333 |

Additions accepted via PR to the TICKER_CIKS map.

## Commands

### `doctor`
Pre-flight: verifies `data.sec.gov` reachability and User-Agent compliance (SEC requires contact-info header).

```bash
bun run skills/bitcoin-macro-digest/bitcoin-macro-digest.ts doctor
```

### `digest [--days=N] [--forms=FORM,FORM]`
Pull filings across all tracked tickers in the last N days (default 3), optionally filtered by form type.

```bash
# Default: last 3 days, all forms
bun run skills/bitcoin-macro-digest/bitcoin-macro-digest.ts digest

# Only insider filings last 5 days
bun run skills/bitcoin-macro-digest/bitcoin-macro-digest.ts digest --days=5 --forms=4,144,13D/A
```

### `filings --cik=<CIK>`
Single-ticker fetch. Returns last 10 filings.

```bash
bun run skills/bitcoin-macro-digest/bitcoin-macro-digest.ts filings --cik=0001050446
```

### `tickers`
List tracked tickers + CIKs (for scripting / integration).

```bash
bun run skills/bitcoin-macro-digest/bitcoin-macro-digest.ts tickers
```

## Output format

```json
{
"window": { "days": 3, "since": "2026-04-21" },
"tickers_scanned": 8,
"filings": [
{
"ticker": "BMNR",
"cik": "0001829311",
"form": "4",
"filingDate": "2026-04-23",
"accessionNumber": "0001493152-26-018676",
"url": "https://www.sec.gov/Archives/edgar/data/1829311/000149315226018676/"
}
]
}
```

## Output contract

- `stdout` is machine-parseable JSON for every command (`doctor`, `digest`, `filings`, `tickers`). No prose, no color codes, no progress bars on stdout.
- `stderr` carries per-ticker warnings (e.g. transient `HTTP 403` / `ECONNRESET`) so stdout remains consumable by downstream tools.
- Exit codes: `0` on success, `1` on network/SEC failure, `2` on CLI misuse (unknown command, bad flags).
- Ordering: `digest.filings[]` is sorted `filingDate` descending, then accession-number descending for same-day ties. Stable across repeat calls on identical data.
- Timezone: `filingDate` is the SEC-reported calendar date (ET), formatted `YYYY-MM-DD`. Callers wanting UTC must derive it from the accession URL.
- Backwards compatibility: adding tickers to `TICKER_CIKS` is non-breaking; removing is breaking. Any field in the output records is stable within minor versions.

## Safety notes

- **SEC fair-use**: do not parallelize ticker fetches without a token bucket. The skill uses a 1.1s serial delay by default; raising throughput requires coordination with SEC (risk of User-Agent ban).
- **No financial advice**: output is raw filing metadata. Interpretation (insider-buying vs. vesting, bullish vs. bearish) is the agent's responsibility.
- **No deserialization of filing bodies**: the skill only returns URLs; fetching and parsing the actual filing content can expose the agent to untrusted HTML/XBRL. Use a hardened parser downstream.
- **No state mutation**: this is a read-only skill. It does not sign, broadcast, or interact with any on-chain contract. Safe to invoke at any cooldown state.
- **Rate-limit observability**: if `stderr` shows repeated `HTTP 403`, stop immediately and rotate the `SEC_UA_EMAIL` — an invalid / placeholder email is the common cause.

## Ethics + SEC compliance

- Uses compliant `User-Agent` header with contact email (SEC rule).
- No rate limit bypass — defaults to serial fetches at 1/sec.
- No republishing / aggregating — each call hits `data.sec.gov` directly.

## Limitations

- US-only (SEC EDGAR scope). International Bitcoin treasuries (Metaplanet etc.) need a separate skill.
- Does not download or parse filing content — returns metadata + URL only.
- `ticker` field is hard-coded in the TICKER_CIKS map; rename events need a PR.
- No caching — repeat calls re-fetch. Fine for daily digest cadence.
Loading
Loading