BTC Energy API

GraphQL service for estimating Bitcoin network energy usage from public blockchain data.

Overview

The service exposes a single GraphQL endpoint and provides:

• energy consumption per transaction for a specific block;
• total daily energy consumption for the last N days;
• total energy consumption for transactions linked to a wallet address.

The API is designed for frontend dashboards and reporting workloads where low latency and predictable API behavior are required.

Stack

• Runtime: Node.js 20
• Language: TypeScript
• API: GraphQL (graphql, graphql-compose, graphql-helix)
• HTTP/Lambda adapter: lambda-api
• Deployment model: AWS Lambda + API Gateway (serverless)
• Build: serverless-esbuild, esbuild
• Local development: serverless-offline
• Testing: jest

Domain Model

• Bitcoin network consists of blocks.
• Blocks include transactions.
• Transaction size is measured in bytes (tx.size).
• Energy coefficient is fixed: 4.56 kWh per byte.

API

Endpoint:

http://localhost:4000/graphql

Queries

1. energyPerTransactionByBlock(blockHash: String, blockHeight: Int)

• Calculates per-transaction energy for one block.
• Requires exactly one selector: blockHash or blockHeight.

2. dailyEnergyConsumptionLastDays(days: Int!)

• Returns daily energy totals for the last N days.
• Uses cumulative blockchain size chart deltas plus per-day block count lookup.
• Optimized to reduce upstream request volume and avoid rate-limit bursts.

3. walletEnergyConsumption(address: String!)

• Returns energy total for transactions associated with a wallet address.

Data Sources

Public Blockchain APIs:

• https://blockchain.info/rawblock/{hash}
• https://blockchain.info/block-height/{height}?format=json
• https://blockchain.info/blocks/{unix_ms}?format=json
• https://blockchain.info/rawaddr/{address}
• https://api.blockchain.info/charts/blocks-size?timespan={N}days&format=json

Running Locally

Requirements:

• Node.js 20.x
• Yarn

Install dependencies:

yarn

Run the API:

yarn start

Type check:

yarn compile

Notes

• Upstream blockchain endpoints may enforce strict rate limits.
• The service applies in-memory caching and request throttling.
• Daily aggregation uses chart deltas to keep external call volume low.