Server-side Bitcoin report generation with LOD (Level of Detail) support.
npm install @pioneer-platform/integration-reportServer-side Bitcoin report generation with LOD (Level of Detail) support.
``bash`
cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/services/pioneer-server
make start
`bash
cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/e2e/reports/intergration-report
Reports Output
Reports are saved to
./reports/ directory:-
bitcoin_report_lod0_YYYY-MM-DD.json
- bitcoin_report_lod1_YYYY-MM-DD.json
- etc.LOD Levels
| LOD | Description | Size | Time | Use Case |
|-----|-------------|------|------|----------|
| 0 | Portfolio overview | ~200B | 500ms | Dashboard widget |
| 1 | XPUB summary | ~1KB | 1s | Multi-account view |
| 2 | Account details | ~2KB | 1.5s | Account analysis |
| 3 | Address level | ~50KB | 3s | Address auditing |
| 4 | Transaction IDs | ~500KB | 10s | Tax reporting |
| 5 | Full details + LLM | ~2MB | 30s | User-facing history |
Configuration
$3
Edit
/projects/pioneer/services/pioneer-server/.env:`bash
Use mock LLM (default, no API calls)
ENABLE_LLM=true
LLM_PROVIDER=mockOr use OpenAI (requires API key)
ENABLE_LLM=true
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
`Architecture
`
Client (integration-report)
↓
1. Get XPUBs from KeepKey (Pioneer SDK)
↓
2. POST to http://localhost:9001/api/v1/reports/bitcoin
↓
Pioneer Server
↓
3. Bitcoin Report Service (LOD processors)
↓
4. UTXO Network Module (Blockbook API)
↓
5. LLM Service (optional, LOD 5 only)
↓
6. Return structured JSON
↓
Client
↓
7. Save JSON to ./reports/
↓
8. (Optional) Generate PDF from JSON
`Example Output
$3
`json
{
"lod": 0,
"totalBalanceBTC": 0.12345678,
"totalBalanceUSD": 8024.69,
"totalXpubs": 9,
"lastUpdated": "2025-01-17T10:30:00.000Z"
}
`$3
`json
{
"lod": 2,
"totalBalanceBTC": 0.12345678,
"totalBalanceUSD": 8024.69,
"totalXpubs": 9,
"lastUpdated": "2025-01-17T10:30:00.000Z",
"xpubs": [
{
"xpub": "zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtym...",
"type": "p2wpkh",
"path": "m/84'/0'/0'",
"label": "Native SegWit Account 0",
"balance": 0.05000000,
"addressCount": 15,
"txCount": 42,
"receiveIndex": 14,
"changeIndex": 8,
"totalReceived": 0.15000000,
"totalSent": 0.10000000
}
]
}
`Development
$3
`bash
node dist/server-side-report-example.js 2 # LOD 2
`$3
`bash
node dist/server-side-report-example.js 2 5 # LOD 2, 5 accounts
`This will generate 3 XPUBs per account (Legacy, SegWit, Native SegWit) × 5 accounts = 15 XPUBs total.
Troubleshooting
$3
- Ensure KeepKey is connected and unlocked
- Check Pioneer SDK initialization$3
- Check pioneer-server logs: tail -f /projects/pioneer/services/pioneer-server/logs/server.log
- Verify server is running: curl http://localhost:9001/api/v1/health$3
- Start pioneer-server: cd /projects/pioneer/services/pioneer-server && make start`- Bitcoin Reports API Documentation
- Pioneer Server README
MIT