GridPulse: U.S. Energy Data

⚡ GridPulse

为 AI Agent 提供按次付费的美国能源市场数据。Agent 使用 x402 协议，以 Algorand 或 Base 上的 USDC 按次付款。买家无需注册，也无需 API 密钥。

端点	价格	返回内容
GET /v1/grid-mix?region=ERCO	$0.02	电网区域最新的每小时发电结构（按燃料类型划分的 MWh、可再生能源和无碳能源占比）
GET /v1/retail-price?state=CT&sector=RES	$0.01	按州和行业划分的零售电价、同比变化、12 个月历史数据
GET /v1/henry-hub	$0.01	Henry Hub 天然气现货价格、30 天统计数据和历史记录
GET /v1/seller-check?url=…	$0.01	**x402 卖家检查：**为任何 x402 卖家评定 0–100 的可靠性分数（运行时间探测、结算历史、运营时长、买家多样性）
GET /v1/sellers/search?q=weather&maxPrice=0.05	$0.02	为某项任务查找可靠的 x402 卖家，并按卖家检查分数排序
GET /v1/algorand/network-health	$0.008	Algorand 出块时间、TPS、在线质押占比、健康状态（仅限 Algorand USDC）
GET /v1/algorand/account?address=…	$0.01	可用 ALGO、是否可支付手续费、是否可接收 USDC、质押和密钥轮换状态（仅限 Algorand USDC）
GET /v1/algorand/asset?id=31566704	$0.015	ASA 供应量、Pera 验证等级、冻结／撤回风险标记（仅限 Algorand USDC）
GET /v1/algorand/tx?id=…	$0.01	以通俗易懂的文字说明交易，并解码备注（仅限 Algorand USDC）
GET /v1/crypto/market-pulse	$0.015	在 Coinbase 和 Kraken 交叉核验的 ALGO/BTC/ETH/SOL/USDC 价格（仅限 Algorand USDC）

已在 Algorand MainNet 上线： https://noahs-mac-mini.tail571e99.ts.net

免费：/（着陆页）、/llms.txt（Agent 文档）、/health。 数据来源：美国能源信息署（公有领域）。

在你的 Agent 中使用

任何 x402 客户端都能使用：调用端点，收到 402 Payment Required，付款后重试。@x402/fetch 封装程序会自动完成所有这些步骤。

• OpenAPI 规范：https://noahs-mac-mini.tail571e99.ts.net/openapi.json
• Agent 文档：https://noahs-mac-mini.tail571e99.ts.net/llms.txt

使用 Base 上的 USDC 付款（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());

**使用 Algorand 上的 USDC 付款：**参见 src/pay.ts（使用 @x402/avm）。

MCP 服务（Claude Desktop、Claude Code、Cursor 等）

**一键安装（Claude Desktop）：**下载 gridpulse-mcp.mcpb，打开它，并可选择输入一个小额支出钱包。它也已列入官方 MCP Registry，名称为 io.github.noah-silver/gridpulse。

或者手动配置：

将 GridPulse 添加为工具（grid_mix、retail_electricity_price、henry_hub_gas_price）。每次工具调用都会通过 x402 从你自己的钱包付款。请使用专用的小额支出钱包，切勿使用主钱包。

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

使用 ALGORAND_MNEMONIC 代替 EVM_PRIVATE_KEY，也可以同时使用两者，以便使用 Algorand 上的 USDC 付款。

---

设置指南（Mac mini）

在 Mac mini 上的终端中逐条运行每个命令。

1. 安装 Node.js

brew install node

如果找不到 brew，请先从 https://brew.sh 安装 Homebrew。

2. 获取代码并安装

将此 gridpulse 文件夹复制到 Mac mini 上（可使用 AirDrop），然后：

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

3. 填写 .env

• PAY_TO_ADDRESS：在 Pera 中创建一个用于接收付款的新账户。向其中转入约 1 ALGO，并为其启用 USDC（在 Pera 中：添加资产，然后搜索 USDC，资产 ID 为 31566704）。将该账户地址粘贴到此处。
• EIA_API_KEY：免费，可立即获取：https://www.eia.gov/opendata/register.php
• 暂时将 NETWORK=testnet 保持不变。

4. 运行

npm start

打开 http://localhost:4021 查看着陆页。http://localhost:4021/v1/henry-hub 应返回 402 Payment Required，这表示付费墙正在正常工作。按 Ctrl+C 停止。

5. 为它提供一个公开的 HTTPS 地址

任选一种：

选项 A：Tailscale Funnel（免费，最简单）。 你会获得一个永久 URL，例如 https://mac-mini.tail1234.ts.net。

brew install tailscale

登录后，运行：

tailscale funnel --bg 4021

选项 B：使用自有域名的 Cloudflare Tunnel（每年约 $10，看起来更专业）。 在 Cloudflare 购买一个域名，例如 gridpulse.xyz，然后：

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

将生成的 URL 填入 .env 中的 PUBLIC_URL。

6. 切换到 MainNet 并让它全天候运行

在 .env 中设置 NETWORK=mainnet。然后：

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

（pm2 startup 会打印另一条需要复制并运行的命令。）在系统设置 → 能源中，开启“防止自动睡眠”和“电源故障后自动启动”。

7. 完成第一笔真实付款（比赛要求）

新建另一个 Pera 账户作为“买家”。在账户中存入约 $1 的 USDC 和 0.3 ALGO。将它的 25 个单词的助记词添加到 .env 中的 BUYER_MNEMONIC。 切勿使用主钱包的助记词。

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

每笔结算完成的付款都会在 Bazaar 和排行榜上列出该端点。

8. 提交（截止 9 月 30 日）

1. 将此文件夹推送到公开的 GitHub 仓库。.env 已被 git 忽略，因此机密信息会保留在本地。
2. 将仓库添加到 Electric Capital open-dev-data。
3. 填写提交表单。

---

技术说明

• @x402/* 软件包固定为 2.17.0，网络 ID 使用硬编码的旧格式，这是托管的 GoPlausible facilitator 当前所要求的格式（x402-foundation/x402#3528）。在 facilitator 更新前请勿升级。
• facilitator 会支付 Algorand 网络费用。买家只需持有 USDC。
• EIA 响应会缓存 10 分钟。
• 无效输入会返回 400，上游故障会返回 502。这两种响应均不会结算，因此不会向买家收费。