Bitcoin Nostr Bot

Automated Nostr bot that publishes weekly Bitcoin metrics and historical events as NIP-23 long-form articles.

Features

• 📊 Weekly Bitcoin Metrics: Posts current price, hashrate, Bitcoin nodes, Lightning Network stats with historical comparisons (1yr, 3yr)
• 📅 Weekly Historical Events: Posts upcoming week's Bitcoin historical events and timeless reads
• 🔄 Automated Scheduling: Uses cron for reliable scheduled posting (Mondays at 7:10 AM)
• 📝 NIP-23 Long-form Content: Creates rich, Markdown-formatted articles
• 🌐 Multi-relay Support: Publishes to multiple Nostr relays simultaneously
• 📈 Auto-updating CSV: Automatically updates Bitcoin node count CSV file weekly
• ⚡ High Performance: Fetches data in parallel for minimal latency
• 🛡️ Robust Error Handling: Structured logging and graceful degradation for optional metrics

Prerequisites

• Go 1.24 or higher
• Nostr private key (hex format)
• Bitcoin Events API key

Installation

1. Clone or create the project:

cd bitcoin-nostr-bot

2. Initialize Go module (already done):

go mod init bitcoin-nostr-bot

3. Install dependencies:

go get github.com/nbd-wtf/go-nostr
go get github.com/robfig/cron/v3
go get github.com/joho/godotenv
go get golang.org/x/sync/errgroup
go get golang.org/x/text

Or simply run:

go mod download

4. Create .env file from .env.example:

cp .env.example .env

5. Edit .env with your credentials:

nano .env

Configuration

Environment Variables

Variable	Description	Example
NOSTR_PRIVATE_KEY	Your Nostr private key (hex)	abc123...
NOSTR_RELAYS	Comma-separated relay URLs	wss://relay.damus.io,wss://nos.lol
EVENTS_API_KEY	Bitcoin Events API key	your_key_here
EVENTS_API_URL	Events API base URL	http://213.176.74.147:3001/api
METRICS_SCHEDULE	Cron schedule for combined post	10 7 * * 1 (Monday 7:10 AM)
TZ	Timezone	UTC

Cron Schedule Format

* * * * *
│ │ │ │ │
│ │ │ │ └─── Day of week (0-7, Sunday = 0 or 7)
│ │ │ └───── Month (1-12)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)

Examples:

• 0 9 * * * - Every day at 9:00 AM
• 0 18 * * 0 - Every Sunday at 6:00 PM
• */30 * * * * - Every 30 minutes
• 0 */6 * * * - Every 6 hours

Building

go build -o bitcoin-nostr-bot

Running

Standard Run

./bitcoin-nostr-bot

Run with Test Posts

./bitcoin-nostr-bot -test

Docker Deployment

Note: The Dockerfile uses Go 1.24 to support the parallelization features.

Build and Run

docker-compose up -d --build

View Logs

docker-compose logs -f

Stop

docker-compose down

Restart

docker-compose restart

Note: The CSV file reachable_bitcoin_nodes.csv is mounted as a volume, so updates persist across container restarts.

Output Example

Combined Post (Metrics + Events)

Hi bitcoiner. This is your weekly snapshot looking back at Bitcoin years ago.

## 📊 Bitcoin Metrics in Historical Perspective

Take a look at fresh Bitcoin metrics and see how much the network has evolved over the years.

| Metric | Today | 1 Year Ago | 3 Years Ago |
|--------|-------|------------|-------------|
| **Price** | $96,411.00 | $91,400.00 | $16,664.00 |
| **Hashrate** | 1104.75 EH/s | 761.10 EH/s | 271.59 EH/s |
| **Bitcoin Nodes** | 23,350 | 19,499 | 15,317 |
| **LN Nodes** | 16,294 | 15,790 | 13,857 |
| **LN Capacity** | 3,747.73 BTC | 5,261.11 BTC | 5,126.18 BTC |
---

## 📅 Bitcoin History - Nov 17-23

Explore the upcoming Bitcoin history milestones and holidays:

### Monday, Nov 17
- [🛑 S2X Launch Failed](https://bitcoin-calendar.org/en/events/2017-11-17/s2x-launch-failed) (2017)

## 📚 Timeless Reads
...

---

#### Sources

- *Browse hundreds of historical Bitcoin milestones by visiting [bitcoin-calendar.org](https://bitcoin-calendar.org)*
- *Historical events sourced from [Bitcoin Calendar open database](https://github.com/Bitcoin-Calendar/calendar-api-db/tree/main/data)*
- *Price, hashrate and LN data provided by [mempool.space](https://mempool.space/)*
- *Bitcoin nodes data by [Bitnodes](https://bitnodes.io/)*

Monitoring

Check if Bot is Running

ps aux | grep bitcoin-nostr-bot

View Logs

The bot logs to stdout. Redirect to a file:

./bitcoin-nostr-bot >> bot.log 2>&1 &

Troubleshooting

Bot doesn't publish

1. Check your private key is correct (64 character hex string)
2. Verify relay URLs are correct and accessible
3. Check logs for connection errors
4. Test with --test flag

API errors

1. Verify EVENTS_API_KEY is correct
2. Check EVENTS_API_URL is accessible
3. Verify you haven't hit rate limits (100 req/min)

Wrong schedule

1. Verify cron syntax is correct
2. Check TZ environment variable
3. Remember cron uses UTC by default unless TZ is set
4. Default schedule is 10 7 * * 1 (Monday at 7:10 AM UTC)

Events not found

1. The bot looks for events in the upcoming week (Monday-Sunday from next Monday)
2. If today is Sunday and you run manually, it will fetch next week's events
3. Check the Events API has data for those dates

CSV file issues

1. Ensure reachable_bitcoin_nodes.csv exists in the project root
2. Check file permissions (should be readable/writable)
3. Verify CSV format: date,total_nodes (YYYY-MM-DD format)
4. In Docker, the CSV is mounted as a volume - check volume mount in docker-compose.yml
5. The bot automatically resolves CSV path from multiple locations (current dir, parent dir, or default path)

Development

Running Tests

go test ./...

Adding More Features

Add new formatters:

1. Create new file in formatters/
2. Implement FormattedPost return type
3. Call from scheduler in main.go

Add new data sources:

1. Create new fetcher in fetchers/
2. Add configuration to config/config.go
3. Create formatter in formatters/
4. Schedule in main.go

Customize post format:

• Edit formatters/metrics.go or formatters/events.go
• Markdown is fully supported
• Can add tables, lists, headers, links, etc.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues with:

• Nostr publishing: Check go-nostr documentation
• Bitcoin data: Check mempool.space and Bitnodes API docs
• Events API: Contact API administrator
• Bot functionality: Open an issue with logs
• CSV updates: Check file permissions and Docker volume mounts

Data Sources

• Price, Hashrate & LN: mempool.space API
• Bitcoin Nodes: Bitnodes API (current) + CSV file (historical)
• Historical Events: Bitcoin Calendar API

Credits

• Built with go-nostr
• Scheduled with cron
• Parallelization with golang.org/x/sync/errgroup
• Formatting with golang.org/x/text
• Bitcoin data from mempool.space and Bitnodes