plugin-gauge — ElizaOS plugin for GAUGE (verifiable environmental signals via x402)

Let an ElizaOS agent pull verifiable flood-risk / river-anomaly records (and air quality / precipitation) and pay per call in USDC on Base — no API key, no signup.

Every record ships with a record_hash — the canonical sha256 of the record's core fields, recomputable offline. Pure description — official-source facts (USGS / NOAA / EPA / CAMS / ERA5) + back-testable statistics; the agent decides. Payment settles directly to the provider wallet via x402 (EIP-3009, gasless).

Backed by the GAUGE service at https://aeml-x402.zeabur.app (discovery: /.well-known/agent.json · /.well-known/x402 · /llms.txt).

Install

From GitHub (built dist/ is committed — no build step needed):

npm install github:CHANGCHINFU/plugin-gauge-

(Or, once published to npm: npm install plugin-gauge.)

Configure (agent settings / env)

| Key | Required | Description | |---|---|---| | EVM_PRIVATE_KEY | rail 1 (x402) | 0x Base-mainnet wallet key. Needs a little USDC (EIP-3009 gasless, no ETH). Pays per call automatically. | | CRYPTO_CHECKOUT_URL | rail 2 (Helio) | Optional Helio hosted-checkout link. When no x402 wallet is set (or x402 fails), the paid action returns this pay_url so a human operator can pay by card/crypto. Lets agent platforms without an x402 wallet still use GAUGE. | | GAUGE_BASE_URL | no | Default https://aeml-x402.zeabur.app. | | GAUGE_MAX_USDC | no | Atomic per-call cap. Default 120000 ($0.12) — covers the $0.10 bundles, blocks accidental over-spend. |

Two payment rails. A paid action is available if either EVM_PRIVATE_KEY (autonomous x402) or CRYPTO_CHECKOUT_URL (human-in-the-loop Helio checkout) is set. With a wallet it auto-pays via x402; otherwise it returns a pay_url for a human to pay. The free action (GAUGE_RIVER_READING_FREE) needs neither.

Use

import { gaugePlugin } from "plugin-gauge";

const runtime = new AgentRuntime({
  // ...
  plugins: [gaugePlugin],
  settings: { secrets: { EVM_PRIVATE_KEY: process.env.EVM_PRIVATE_KEY } },
});

Actions

| Action | Price | What it does | |---|---|---| | GAUGE_FLOOD_RISK | $0.05 | Verifiable flood-risk / river-anomaly record: current vs official USGS/NOAA flood thresholds (band, distance-to-action) + 5-yr seasonal anomaly (percentile/strata) + record_hash. Works for any signal. | | GAUGE_REGION | $0.10 | Three-leg bundle for a location: air quality + precipitation + nearby river + cross-line corroboration. | | GAUGE_CROP_DROUGHT | $0.10 | Agriculture triangle for a grain region: agricultural drought (soil moisture vs official USDM D0–D4) + heat/GDD + crop vegetation health (NOAA VHI) + cross-validation (has drought hit the crop canopy). For ag traders & crop insurers. Global grain belts (us-iowa, ar-pampas, ua-ukraine, …). | | GAUGE_GRID_STRESS | $0.10 | Power grid triangle for a grid region: electricity demand pressure (temperature HDD/CDD load proxy) + renewable resource (solar/wind potential) + energy inflation (US CPI Energy YoY) / natural gas price (Henry Hub) + cross-validation (high demand × low renewables = grid squeeze → energy price/inflation up). For power/energy & macro/inflation traders, utilities, renewable investors. Global grids (us-ercot, us-caiso, eu-germany, …); energy inflation/gas are US-national. Weather-driven proxy, not actual MW. | | GAUGE_ROUTE_DISRUPTION | $0.10 | Shipping triangle for a chokepoint/port: logistics-flow disruption (sea state WMO + wind vs operational thresholds) + sea-state cause (wave decomposition: local-storm vs distant-swell) + live AIS vessel throughput (waiting/anchored vs transiting + congestion) + cross-validation (has the disruption reduced actual flow, or is the port absorbing it). For shipping lines, commodity/freight traders, ports, marine insurers. Global chokepoints (malacca, suez-redsea, hormuz, channel, …). Weather-driven + AIS-sampled proxy. | | GAUGE_FILING_CHECK | $0.10 | Regulatory-filing triangle for a company: 8-K material events (item severity — bankruptcy/default/restatement/delisting = critical) + NT late-filing delinquency (distress leading indicator) + Form 4 insider net open-market buy/sell + cross-validation (do insiders confirm the disclosed distress by selling, or contradict it by buying — turnaround divergence). All official SEC EDGAR. For event-driven/activist/short funds, quant funds, credit & distressed analysts. Watchlist tickers (AMC, CVNA, GME, BA, …). | | GAUGE_RIVER_READING_FREE | free | Raw river reading (current/trend/sources/hash). No wallet needed. |

Signals: hydrology.river-level, hydrology.streamflow, airquality.aqi, airquality.pm25, precipitation.daily, precipitation.wetness30d, agriculture.drought, agriculture.heat, agriculture.crop-vhi, electricity.demand, electricity.renewable, energy.inflation, energy.gas-price, shipping.route-disruption, shipping.sea-state, shipping.throughput, filing.material-events, filing.delinquency, filing.insider. Entities: USGS site id (e.g. 07010000 = Mississippi at St. Louis) for rivers; city id (e.g. us-chicago) for air/precip/region. Free station list: /gauge/catalog.

À-la-carte add-ons (/gauge/ruler $0.01, /gauge/calibrated $0.02, /gauge/strata $0.03, /gauge/history $0.03, /gauge/air $0.02, /gauge/precip $0.02) and cross-station /gauge/census ($1) are available on the API; add actions as needed.

Verify (zero-trust)

Each record carries a record_hash — the canonical sha256 of the record's core fields, which you can recompute yourself offline. Re-check with POST /verify, GET /proof/:record_hash, or the free GET /gauge/verify?format=json&hash=….

Bitcoin / OpenTimestamps anchoring: RETIRED. It was ruled out of implementation on 2026-07-23 and was never actually stamped. Earlier versions of this README advertised it — that was wrong, and this corrects it. What you actually get: integrity from record_hash, and timeliness from the official source_ref plus observed_at. The live service says the same in GET /proof/:record_hash → proof.bitcoin_anchoring.

Build & publish (maintainers)

npm run build      # tsup → dist/
npm publish        # your npm account

Notes

• Pure description, not advice. Thresholds are official facts; statistics are back-testable. Any flood/risk decision is the agent's.
• Spending is capped by GAUGE_MAX_USDC (default $0.12/call — covers the $0.10 region/agri/grid/shipping/filing bundles; blocks pricier census calls).
• ElizaOS compatibility: built and type-checked against @elizaos/core@^1.7.0 (current 1.x action interface — ActionExample.name, Content.actions[], Handler returns ActionResult). Works on ElizaOS 1.x out of the box.

MIT · AEML-DS Vanished-Data Exchange