Cardano Treasury Explorer

A live CLI dashboard for Cardano on-chain treasury and governance activity, with an automated companion bot that posts structured updates to X (Twitter).

Demo

Run the included demo script directly with tsx (no demo script is defined in package.json, so don't use npm run demo):

npx tsx src/demo.ts

Example output, based on a real cached epoch snapshot:

[DRY RUN] Would post:
📊 Epoch 635: Treasury 1.51B ADA | Reserves 6.33B ADA | 118,616 txs | Fees 43,282.92 ADA

Swap in the real templated text from posts.ts if it differs. Also worth a quick screenshot of the live CLI dashboard itself (npm run dev) — the chalk + cli-table3 formatted table is a stronger visual for this README than plain log lines, and takes the same effort to capture.

What it does

• Renders a live, color-formatted CLI dashboard of Cardano treasury and governance activity
• Polls Cardano on-chain data — treasury withdrawals, governance proposals, epoch-level activity — via the Blockfrost API
• Formats findings into four distinct post types, each constrained to X's 280-character limit
• Supports a dry-run mode for safe testing without posting live
• Built to operate within free-tier API constraints, with graceful fallbacks where paid-tier endpoints are required

Why this exists

Originally scoped as part of broader research into Cardano Hydra L2 for processing ADA microtransactions. After identifying hard blockers for that use case — node sync time, Hydra liveness constraints, X API cost, and regulatory exposure — the project was deliberately descoped to a focused on-chain monitoring and social bot. This repo is the actual shipped deliverable from that research.

Tech stack

• TypeScript / Node.js — run via tsx in dev, compiled with tsc for production
• Blockfrost API (on-chain Cardano data)
• X (Twitter) API v2
• node-cron for scheduling
• chalk + cli-table3 for the CLI dashboard rendering

Architecture

src/
├── index.ts        # application entry point
├── scheduler.ts     # polling / cron logic
├── posts.ts          # post generation for the four post types
├── twitter.ts          # X API posting logic + dry-run toggle
├── backfill.ts           # historical epoch snapshot backfill
├── diagnose.ts             # diagnostics / debug utilities
├── demo.ts                  # demo run script
├── blockfrost/                # on-chain Cardano data client
├── db/                          # database access layer (treasury.db)
├── core/                          # core treasury/governance processing logic
└── display/                         # output/console formatting

Setup

1. Clone the repo
2. npm install
3. Copy .env.example to .env and fill in:
   • BLOCKFROST_API_KEY
   • TWITTER_API_KEY, TWITTER_API_SECRET, TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_SECRET
   • DRY_RUN=true (recommended for first run)
4. npm run dev to run directly via tsx (recommended for trying it out)

For a production-style run: npm run build && npm run start (dist/ isn't tracked in the repo, so build has to run first).

What it does

Known limitations

• Free-tier Blockfrost accounts don't have access to the governance proposals endpoint. This is handled via an isolated try/catch so the rest of the bot keeps functioning without it.
• Live posting requires a funded X API credit balance on a dedicated bot account.

Roadmap

• Dedicated bot X account with funded credit balance for live posting
• Possible revisit of Hydra L2 integration for microtransaction-level treasury tracking

License

MIT