Quickstart

Grid402’s primary product is 5-minute generation mix and the carbon intensity computed from it. This guide makes your first paid /mix call in three steps.

(Spot price and combined-signal endpoints follow the same pattern — once /mix works, the others are free swaps.)

1. Probe the endpoint (free, no wallet)

The demo tier at grid402.climatebrain.xyz/api is unmetered. You can call it without payment:

curl https://grid402.climatebrain.xyz/api/mix/CAISO/live
# => 200 OK
# => { "iso": "CAISO", "ci_g_per_kwh": 118,
#      "pct": { "solar": 38.4, "wind": 10.5, "gas": 18.7, ... },
#      "source": "live" }

The production API (the one you pay for) returns 402 Payment Required instead, with an x402 challenge body listing the cost, recipient address, and network:

curl -i https://api.grid402.xyz/mix/CAISO/live   # production URL, paid tier
# => HTTP/1.1 402 Payment Required
# => { "x402Version": 1,
#      "accepts": [{ "scheme": "exact", "price": "$0.002",
#                    "network": "eip155:8453", "payTo": "0x..." }],
#      "error": "Payment required" }

2. Pay with the x402 fetch helper

Install the official client:

pnpm add x402-fetch viem

Then make the call. The wrapper handles the 402 challenge, signs an EIP-3009 transfer authorization (gasless), and retries with the X-PAYMENT header attached:

import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({ account, chain: base, transport: http() });

const fetch402 = wrapFetchWithPayment(fetch, client);

// The primary endpoint — generation mix + carbon intensity
const res = await fetch402("https://api.grid402.xyz/mix/CAISO/live");
const data = await res.json();

console.log(`CAISO is ${data.ci_g_per_kwh} gCO₂/kWh right now`);
console.log(`Solar share: ${data.pct.solar}%`);

3. What you get

{
  "iso": "CAISO",
  "ts": "2026-04-25T20:55:00Z",
  "generation_mw": { "solar": 8421, "wind": 2310, "gas": 4115, "nuclear": 2240 },
  "pct":           { "solar": 38.4,  "wind": 10.5, "gas": 18.7,  "nuclear": 10.2 },
  "ci_g_per_kwh":  184,
  "source_url":    "https://www.caiso.com/...",
  "source":        "live"
}

Cost per call: $0.002 USDC for /mix. Pricing for other endpoints is in Endpoints.

Want price too? Use `/combined`

If your agent is making a decision (workload schedule, battery dispatch, EV charge timing) it usually wants mix + emissions + spot in one shot. The combined endpoint costs less than three separate calls:

const res = await fetch402("https://api.grid402.xyz/combined/CAISO/TH_NP15/live");
const { mix, spot, emissions } = await res.json();
//   one HTTP request, one USDC tx, three signals.

Coinbase AgentKit (zero-code)

If you’re building with Coinbase AgentKit, the x402ActionProvider is already built in. Your agent calls Grid402 with no Grid402-specific code:

import { AgentKit, x402ActionProvider } from "@coinbase/agentkit";

const agentkit = new AgentKit({
  actionProviders: [
    x402ActionProvider({
      registeredServices: ["https://api.grid402.xyz"],
      maxPaymentUsdc: 0.10,
    }),
  ],
});

// agent prompt: "what's the current CAISO carbon intensity?"
// → agent discovers /mix/CAISO/live, pays, returns data. Day one.