Gridpulse MCP Server

⚡ GridPulse

Pay-per-call U.S. energy market data for AI agents. Agents pay per call in USDC on Algorand or Base using the x402 protocol. No signup and no API keys for buyers.

Live on Algorand MainNet: https://noahs-mac-mini.tail571e99.ts.net

Free: / (landing page), /llms.txt (docs for agents), /health. Data source: U.S. Energy Information Administration (public domain).

Entry for the Algorand Global x402 Challenge (Composite: three endpoints, one payout address).

Use it from your agent

Any x402 client works: call the endpoint, get 402 Payment Required, pay, retry. The @x402/fetch wrapper does all of this automatically.

• OpenAPI spec: https://noahs-mac-mini.tail571e99.ts.net/openapi.json
• Agent docs: https://noahs-mac-mini.tail571e99.ts.net/llms.txt

Pay with USDC on Base (npm i @x402/fetch @x402/evm viem):

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const signer = toClientEvmSigner(account, createPublicClient({ chain: base, transport: http() }));
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
const fetchWithPay = wrapFetchWithPayment(fetch, client);

const res = await fetchWithPay("https://noahs-mac-mini.tail571e99.ts.net/v1/grid-mix?region=CISO");
console.log(await res.json());

Pay with USDC on Algorand: see src/pay.ts (uses @x402/avm).

MCP server (Claude Desktop, Claude Code, Cursor, …)

One-click (Claude Desktop): download gridpulse-mcp.mcpb, open it, and optionally enter a small spending wallet. Also listed in the official MCP Registry as io.github.noah-silver/gridpulse.

Or configure it manually:

Add GridPulse as tools (grid_mix, retail_electricity_price, henry_hub_gas_price). Each tool call pays from your own wallet via x402. Use a small, dedicated spending wallet, never your main one.

{
  "mcpServers": {
    "gridpulse": {
      "command": "npx",
      "args": ["-y", "github:noah-silver/gridpulse"],
      "env": { "EVM_PRIVATE_KEY": "0x… (Base wallet holding a little USDC)" }
    }
  }
}

Use ALGORAND_MNEMONIC instead of (or as well as) EVM_PRIVATE_KEY to pay with USDC on Algorand.

---

Setup guide (Mac mini)

Run each command in Terminal on the Mac mini, one at a time.

1. Install Node.js

brew install node

If brew isn't found, install Homebrew first from https://brew.sh.

2. Get the code and install

Copy this gridpulse folder onto the Mac mini (AirDrop works), then:

cd ~/gridpulse
npm install
cp .env.template .env
open -e .env

3. Fill in .env

• PAY_TO_ADDRESS: create a new account in Pera for receiving payments. Fund it with about 1 ALGO and opt it in to USDC (in Pera: Add Asset, then search USDC, asset ID 31566704). Paste its address here.
• EIA_API_KEY: free, instant, at https://www.eia.gov/opendata/register.php
• Leave NETWORK=testnet for now.

4. Run it

npm start

Open http://localhost:4021 to see the landing page. http://localhost:4021/v1/henry-hub should return 402 Payment Required, which means the paywall is working. Press Ctrl+C to stop.

5. Give it a public HTTPS address

Pick one:

Option A: Tailscale Funnel (free, easiest). You get a permanent URL like https://mac-mini.tail1234.ts.net.

brew install tailscale

Sign in, then run:

tailscale funnel --bg 4021

Option B: Cloudflare Tunnel with your own domain (about $10/yr, looks more professional). Buy a domain such as gridpulse.xyz in Cloudflare, then:

brew install cloudflared
cloudflared tunnel login
cloudflared tunnel create gridpulse
cloudflared tunnel route dns gridpulse api.YOURDOMAIN.com
cloudflared tunnel run --url http://localhost:4021 gridpulse

Put the resulting URL in .env as PUBLIC_URL.

6. Switch to MainNet and keep it running 24/7

In .env, set NETWORK=mainnet. Then:

npm install -g pm2
pm2 start npm --name gridpulse -- start
pm2 save
pm2 startup

(pm2 startup prints one more command to copy and run.) In System Settings → Energy, turn on "Prevent automatic sleeping" and "Start up automatically after a power failure."

7. Make the first real payment (required by the contest)

Create another new Pera account as the "buyer." Put about $1 of USDC and 0.3 ALGO in it. Add its 25-word phrase to .env as BUYER_MNEMONIC. Never use the phrase of your main wallet.

npm run pay -- "/v1/grid-mix?region=ISNE"
npm run pay -- "/v1/retail-price?state=CT"
npm run pay -- /v1/henry-hub

Each settled payment lists that endpoint in the Bazaar and on the leaderboard.

8. Submit (by September 30)

1. Push this folder to a public GitHub repo. .env is git-ignored, so your secrets stay local.
2. Add the repo to Electric Capital open-dev-data.
3. Fill in the submission form.

---

Technical notes

• @x402/* packages are pinned to 2.17.0, and network IDs are hardcoded in the legacy format that the hosted GoPlausible facilitator currently expects (x402-foundation/x402#3528). Don't upgrade until the facilitator is updated.
• The facilitator pays Algorand network fees. Buyers need only USDC.
• EIA responses are cached for 10 minutes.
• Invalid inputs return 400 and upstream failures return 502. Neither response is settled, so buyers aren't charged.