@agentgate-builder/perpradar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentgate-builder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# PerpRadar: perp funding rates, open interest and positioning for trading agents (x402 API + MCP)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Perpetual futures funding radar across the onchain perp venues **Hyperliquid, dYdX v4, Paradex and Aevo**. One call returns
+funding normalized to **8h % and APR**, open interest, mark/index premium, the cross-venue median, spread, the cheapest venue to
+be long or short and a positioning read (crowded long / long bias / neutral / short bias / crowded short). The full tier adds
+7-day funding history with z-score and percentile, the funding regime and carry; the scan finds funding extremes and the widest
+cross-venue spreads across the whole market.
+
+> **Not financial advice. Past performance does not guarantee future results.** Read-only market analytics from public venue
+> data. PerpRadar never trades, never holds funds and never asks for keys.
+
+- API: https://api.youraitools.co/perpradar (fallback https://perpradar.agentgate.workers.dev)
+- Remote MCP: `https://api.youraitools.co/perpradar/mcp` (tool `perp_positioning`, free preview)
+- stdio MCP: `npx -y @agentgate-builder/perpradar` (tools `perp_funding`, `perp_funding_scan`)
+- OpenAPI: `/openapi.json` · x402 manifest: `/.well-known/x402`
+
+## Routes and prices
+
+| Route | Price | Returns |
+|---|---|---|
+| `GET /v1/lite?symbol=BTC` | $0.005 | per-venue funding (8h %, APR) and OI, median and OI-weighted funding, spread, cheapest venue for longs/shorts, positioning |
+| `GET /v1/full?symbol=ETH` | $0.03 | lite + mark/index premium, 24h volume, Hyperliquid 7-day and dYdX 100-hour funding history (mean, min, max, z-score, percentile), regime, carry |
+| `GET /v1/scan?universe=all` or `?symbols=BTC,ETH,SOL` | $0.02 | highest / lowest funding, widest cross-venue spreads, market-wide OI-weighted funding |
+| `GET /v1/preview?symbol=BTC` | free (10/min/IP) | positioning label, venues, confidence (no rates) |
+
+All paid routes accept POST with the same fields as JSON. Payment: x402 v2 (`PAYMENT-SIGNATURE`; USDC on Base, Polygon,
+Arbitrum One or Solana) or v1 (`X-PAYMENT`, Base), or a prepaid YourAITools credits key (`Authorization: Bearer yatc_...`).
+Bad input (400), unknown symbols (404) and upstream failures (503) are never charged.
+
+## Fail-closed
+
+A venue that errors or times out is listed in `sources_failed` and left out: never estimated. The cross-venue read needs at
+least 2 venues (otherwise `positioning: "unknown"`, confidence low). No venue at all = HTTP 503 `upstream_unavailable`, not charged.
+
+## stdio MCP paid mode
+
+Set `PERPRADAR_X402_PRIVATE_KEY` (a Base wallet with a little USDC) and install the optional peers:
+`npx -y -p @agentgate-builder/perpradar -p @x402/fetch -p @x402/evm -p viem perpradar`. Spend guard: Base USDC only,
+max $0.03 per payment, only to the PerpRadar payTo.
+
+## Develop
+
+`npm test` (offline mocks) · `npm start` (Node server) · `wrangler deploy` (Cloudflare Worker).
+
+MIT. Data: public market-data APIs of Hyperliquid, dYdX v4 indexer, Paradex and Aevo.

package/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="AgentReady"><rect width="64" height="64" rx="14" fill="#0f172a"/><rect x="14" y="16" width="36" height="28" rx="6" fill="none" stroke="#38bdf8" stroke-width="3.2"/><circle cx="25" cy="29" r="3.2" fill="#38bdf8"/><circle cx="39" cy="29" r="3.2" fill="#38bdf8"/><path d="M32 8v8M22 50h20" stroke="#38bdf8" stroke-width="3.2" stroke-linecap="round"/><path d="M40 44l5 5 9-10" fill="none" stroke="#22c55e" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@agentgate-builder/perpradar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "mcpName": "co.youraitools/perpradar",
+  "description": "Perp funding rates, open interest and positioning for trading agents: MCP server + client for PerpRadar. Funding normalized to 8h and APR, OI, mark/index premium, cross-venue median and spread, 7-day funding history and z-score, carry and a universe scan for funding extremes across Hyperliquid, dYdX v4, Paradex and Aevo. Free MCP preview; full data via x402 pay-per-call API. Read-only analytics. Not financial advice.",
+  "type": "module",
+  "main": "src/lite.js",
+  "bin": {
+    "perpradar": "src/mcp-stdio.js",
+    "perpradar-mcp": "src/mcp-stdio.js"
+  },
+  "exports": {
+    ".": "./src/lite.js",
+    "./lite": "./src/lite.js",
+    "./mcp": "./src/mcp-stdio.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/mcp-stdio.js",
+    "src/lite.js",
+    "src/paid.js",
+    "src/deadline.js",
+    "src/version.js",
+    "README.md",
+    "LICENSE",
+    "logo.svg"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "start": "node src/node.js",
+    "deploy": "wrangler deploy",
+    "mcp": "node src/mcp-stdio.js",
+    "gen:examples": "node tools/gen-examples.mjs"
+  },
+  "keywords": [
+    "funding-rate",
+    "funding-rates",
+    "perpetual-futures",
+    "perps",
+    "open-interest",
+    "hyperliquid",
+    "dydx",
+    "paradex",
+    "aevo",
+    "crypto-trading",
+    "trading-bot",
+    "market-data",
+    "mcp",
+    "mcp-server",
+    "x402",
+    "usdc",
+    "ai-agents"
+  ],
+  "author": "agentgate-builder",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://agentgate-source.pages.dev/x402-perpradar/"
+  },
+  "homepage": "https://api.youraitools.co/perpradar",
+  "bugs": {
+    "url": "https://agentgate-source.pages.dev/x402-perpradar/",
+    "email": "hello@youraitools.co"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@coinbase/x402": "2.1.0",
+    "@hono/node-server": "^1.19.9",
+    "@x402/core": "2.28.0",
+    "@x402/evm": "2.28.0",
+    "@x402/extensions": "2.28.0",
+    "@x402/fetch": "2.28.0",
+    "@x402/hono": "2.28.0",
+    "hono": "^4.13.13",
+    "viem": "^2.0.0",
+    "wrangler": "^4.86.0",
+    "x402": "1.2.0",
+    "x402-fetch": "1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@x402/fetch": ">=2.28.0 <3",
+    "@x402/evm": ">=2.28.0 <3",
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@x402/fetch": {
+      "optional": true
+    },
+    "@x402/evm": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  }
+}

package/src/deadline.js

@@ -0,0 +1,24 @@
+// Hard deadlines so no request can hang: every awaited network step races a timer, and the Worker entry has a
+// last-resort watchdog. Budgets (paid route, worst case): verify 8 s + work <= 20 s + settle 15 s < 45 s watchdog.
+export const BUDGET = { supportedMs: 3000, verifyMs: 8000, settleMs: 15000, workMs: 20000, watchdogMs: 45000 };
+
+export class DeadlineError extends Error {
+  constructor(what, ms) { super(`${what} timed out after ${ms} ms`); this.name = 'DeadlineError'; this.code = 'timeout'; }
+}
+
+/** Resolve/reject with `p`, or reject with DeadlineError after `ms`. The timer is always cleared. */
+export function withDeadline(p, ms, what = 'operation') {
+  let t;
+  const timer = new Promise((_, rej) => { t = setTimeout(() => rej(new DeadlineError(what, ms)), ms); });
+  return Promise.race([Promise.resolve(p), timer]).finally(() => clearTimeout(t));
+}
+
+/** Wrap a Worker fetch handler: answer 503 (never charged, settlement only follows a 2xx) instead of hanging. */
+export function watchdog(handler, ms = BUDGET.watchdogMs) {
+  return (request, env, ctx) => withDeadline(Promise.resolve().then(() => handler(request, env, ctx)), ms, 'request').catch((e) => {
+    console.error(`watchdog: ${request.method} ${new URL(request.url).pathname}: ${e && e.message}`);
+    return new Response(JSON.stringify({ error: e instanceof DeadlineError ? 'timeout' : 'internal_error', message: 'The request took too long or failed; it was not charged. Please retry.' }), {
+      status: 503, headers: { 'content-type': 'application/json', 'retry-after': '5', 'access-control-allow-origin': '*' },
+    });
+  });
+}

package/src/lite.js

@@ -0,0 +1,29 @@
+// PerpRadar client used by the npm package (library + stdio MCP server). Free tier: the hosted preview
+// (positioning label, venues, confidence; 10/min per IP). Rates, OI, history and scans: paid API over x402 (see paid.js).
+import { withDeadline } from './deadline.js';
+
+export const API_BASE = 'https://api.youraitools.co/perpradar';
+export const FALLBACK_API_BASE = 'https://perpradar.agentgate.workers.dev';
+export const PAID_URL = `${API_BASE}/v1/full`;
+export const PRICES = { lite: '$0.005', full: '$0.03', scan: '$0.02' };
+export const DISCLAIMER = 'Not financial advice. Past performance does not guarantee future results. Read-only market analytics; PerpRadar never trades, holds funds or keys.';
+export const FULL_DETAILS = `Per-venue funding (8h %, APR), open interest, premium, 7-day funding history and carry: paid API ${API_BASE}/v1/lite|full?symbol=<ticker> (${PRICES.lite} / ${PRICES.full} USDC over x402, or a prepaid credits key); universe scan ${API_BASE}/v1/scan?universe=all (${PRICES.scan}).`;
+
+/** Validate the symbol argument locally (no network). Returns { symbol } or { error }. */
+export function toSymbol(args = {}) {
+  const v = args.symbol ?? args.coin ?? args.asset ?? args.ticker;
+  if (typeof v !== 'string' || !v.trim()) return { error: '"symbol" is required: an asset ticker, e.g. BTC' };
+  let s = v.trim().toUpperCase().replace(/[\s_/]+/g, '-').replace(/-?(PERP|PERPETUAL|SWAP)$/, '').replace(/-?(USDT|USDC|USD)$/, '').replace(/-+$/, '');
+  if (!/^[A-Z0-9]{1,15}$/.test(s)) return { error: '"symbol" must be a ticker like BTC, ETH or SOL' };
+  return { symbol: s };
+}
+
+/** Free hosted preview. Returns the preview JSON or { error, message }. */
+export async function preview(symbol, { fetchImpl = globalThis.fetch, apiBase = API_BASE, ms = 30000 } = {}) {
+  try {
+    const res = await withDeadline(fetchImpl(`${apiBase.replace(/\/+$/, '')}/v1/preview?symbol=${encodeURIComponent(symbol)}`, { headers: { accept: 'application/json', 'user-agent': 'perpradar-npm' } }), ms, 'PerpRadar preview');
+    const j = await res.json().catch(() => null);
+    if (!res.ok) return { error: j?.error || `http_${res.status}`, message: j?.message || `PerpRadar preview answered HTTP ${res.status}` };
+    return j;
+  } catch (e) { return { error: 'network', message: String(e?.message || e).slice(0, 200) }; }
+}

package/src/mcp-stdio.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// PerpRadar MCP server over stdio (newline-delimited JSON-RPC 2.0).
+// Free by default: the hosted free preview (positioning label, venues, confidence; 10/min per IP).
+// Full data: set PERPRADAR_X402_PRIVATE_KEY (or X402_PRIVATE_KEY) to a Base wallet key holding a little USDC, and this
+// server pays the hosted API per call over x402 (full $0.03, scan $0.02): https://api.youraitools.co/perpradar
+//   npx -y @agentgate-builder/perpradar   (bin: perpradar)
+import { createInterface } from 'node:readline';
+import { toSymbol, preview, DISCLAIMER, FULL_DETAILS, API_BASE, PRICES } from './lite.js';
+import { createPaidClient } from './paid.js';
+import { VERSION_STR as VERSION } from './version.js';
+
+export { VERSION };
+const SYM = { type: 'string', description: 'Asset ticker, e.g. BTC, ETH, SOL, HYPE' };
+const RO = { readOnlyHint: true, openWorldHint: true, idempotentHint: false };
+export const TOOLS = [
+  { name: 'perp_funding', title: 'Perp funding, OI and positioning for an asset', description: `Perpetual futures funding read for one asset across Hyperliquid, dYdX v4, Paradex and Aevo. Free by default: cross-venue positioning label (crowded long ... crowded short), venues and confidence. With PERPRADAR_X402_PRIVATE_KEY set, returns the paid full tier (${PRICES.full} USDC on Base per call over x402): per-venue funding (8h %, APR), open interest, premium, 7-day funding history with z-score, regime and carry. Read-only; not financial advice.`, inputSchema: { type: 'object', properties: { symbol: SYM }, required: ['symbol'] }, annotations: RO },
+  { name: 'perp_funding_scan', title: 'Scan perp funding extremes and spreads', description: `Paid only (needs PERPRADAR_X402_PRIVATE_KEY, ${PRICES.scan} USDC on Base per call): highest and lowest funding, widest cross-venue spreads and market-wide OI-weighted funding across Hyperliquid, dYdX and Paradex; pass symbols (comma list) for a watchlist or leave empty for the whole universe. Read-only; not financial advice.`, inputSchema: { type: 'object', properties: { symbols: { type: 'string', description: 'Optional comma-separated tickers (max 25); empty = whole universe' }, limit: { type: 'integer', description: '1-25, default 10' } } }, annotations: RO },
+];
+const PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const summarizePreview = (r, note) => `${note ? note + '\n' : ''}PerpRadar ${r.symbol}: ${String(r.positioning).replace(/_/g, ' ')}. ${r.positioning_note || ''} Venues: ${(r.venues_listed || []).join(', ')}; confidence ${r.confidence}.\n${FULL_DETAILS} Set PERPRADAR_X402_PRIVATE_KEY to get them here.\n${DISCLAIMER}`;
+const summarizeFull = (r) => `PerpRadar ${r.symbol}: ${String(r.positioning).replace(/_/g, ' ')}; median funding ${r.funding?.median_apr_pct}% APR (spread ${r.funding?.cross_venue_spread_apr_pct}%), OI $${r.open_interest_usd_total}. Regime: ${r.regime?.vs_recent}.\n${(r.venues || []).map((v) => `- ${v.venue}: ${v.funding_8h_pct}%/8h (${v.funding_apr_pct}% APR), OI $${v.open_interest_usd}, premium ${v.premium_pct}%`).join('\n')}\n${DISCLAIMER}`;
+const summarizeScan = (r) => `PerpRadar scan (${r.mode}, ${r.assets} assets): market OI-weighted funding ${r.market?.oi_weighted_funding_apr_pct}% APR (${r.market?.read}).\nHighest: ${(r.highest_funding || []).map((x) => `${x.symbol} ${x.median_apr_pct}%`).join(', ')}\nLowest: ${(r.lowest_funding || []).map((x) => `${x.symbol} ${x.median_apr_pct}%`).join(', ')}\nWidest spreads: ${(r.widest_spreads || []).map((x) => `${x.symbol} ${x.spread_apr_pct}%`).join(', ')}\n${DISCLAIMER}`;
+
+let paidClient;
+const paid = async (opts) => { if (paidClient === undefined) paidClient = await createPaidClient(opts); return paidClient; };
+
+export async function handle(m, opts = {}) {
+  if (!m || m.jsonrpc !== '2.0' || typeof m.method !== 'string') return { jsonrpc: '2.0', id: m?.id ?? null, error: { code: -32600, message: 'Invalid Request' } };
+  const note = m.id === undefined || m.id === null;
+  const ok = (result) => (note ? null : { jsonrpc: '2.0', id: m.id, result });
+  const err = (text) => ok({ isError: true, content: [{ type: 'text', text }] });
+  switch (m.method) {
+    case 'initialize': {
+      const client = await paid(opts);
+      const mode = client && !client.error ? `Paid mode: full data from ${client.apiBase} over x402.` : `Free preview mode; rates and scans at ${API_BASE} (x402).`;
+      return ok({ protocolVersion: PROTOCOLS.includes(m.params?.protocolVersion) ? m.params.protocolVersion : '2025-06-18', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'perpradar', title: 'PerpRadar', version: VERSION }, instructions: `Call perp_funding with an asset ticker for the cross-venue perp funding read. ${mode} Not financial advice.` });
+    }
+    case 'ping': return ok({});
+    case 'tools/list': return ok({ tools: TOOLS });
+    case 'tools/call': {
+      const name = m.params?.name;
+      if (!TOOLS.some((t) => t.name === name)) return note ? null : { jsonrpc: '2.0', id: m.id, error: { code: -32602, message: `Unknown tool: ${name}` } };
+      const args = m.params?.arguments || {};
+      const client = await paid(opts);
+      if (name === 'perp_funding_scan') {
+        if (!client || client.error) return err(`perp_funding_scan is paid only: set PERPRADAR_X402_PRIVATE_KEY (Base USDC) or call ${API_BASE}/v1/scan?universe=all with any x402 client (${PRICES.scan}).${client?.error ? ` (${client.error})` : ''}`);
+        const lim = args.limit === undefined ? 10 : Number(args.limit);
+        const input = args.symbols ? { symbols: String(args.symbols), limit: lim } : { universe: 'all', limit: lim };
+        try {
+          const r = await client.call('scan', input);
+          if (r.result && !r.error) return ok({ content: [{ type: 'text', text: summarizeScan(r.result) }], structuredContent: { ...r.result, payer: client.payer }, isError: false });
+          return err(`${r.error}${r.detail ? `: ${r.detail}` : ''}`);
+        } catch (e) { return err(`paid call failed: ${String(e?.message || e).slice(0, 200)}`); }
+      }
+      const t = toSymbol(args);
+      if (t.error) return err(`bad_request: ${t.error}`);
+      let fallbackNote = '';
+      if (client?.error) fallbackNote = client.error;
+      else if (client) {
+        try {
+          const r = await client.call('full', { symbol: t.symbol });
+          if (r.result && !r.error) return ok({ content: [{ type: 'text', text: summarizeFull(r.result) }], structuredContent: { ...r.result, payer: client.payer, ...(r.paymentResponse ? { payment_response: r.paymentResponse } : {}) }, isError: false });
+          fallbackNote = `Paid call failed (${r.error}${r.detail ? `: ${r.detail}` : ''}); showing the free preview.`;
+        } catch (e) { fallbackNote = `Paid call failed (${String(e?.message || e).slice(0, 200)}); showing the free preview.`; }
+      }
+      const r = await preview(t.symbol, { fetchImpl: opts.fetchImpl, apiBase: opts.apiBase || process.env.PERPRADAR_API_URL || API_BASE });
+      if (r.error) return err(`${r.error}: ${r.message}${fallbackNote ? ` (${fallbackNote})` : ''}`);
+      delete r.full;
+      return ok({ content: [{ type: 'text', text: summarizePreview(r, fallbackNote) }], structuredContent: fallbackNote ? { ...r, paid_error: fallbackNote } : r, isError: false });
+    }
+    default:
+      return m.method.startsWith('notifications/') || note ? null : { jsonrpc: '2.0', id: m.id, error: { code: -32601, message: `Method not found: ${m.method}` } };
+  }
+}
+
+export function serve({ input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  const write = (o) => output.write(JSON.stringify(o) + '\n');
+  rl.on('line', async (l) => {
+    if (!l.trim()) return;
+    let msg; try { msg = JSON.parse(l); } catch { return write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); }
+    const batch = Array.isArray(msg);
+    const replies = (await Promise.all((batch ? msg : [msg]).map((x) => handle(x)))).filter(Boolean);
+    if (replies.length) write(batch ? replies : replies[0]);
+  });
+  return rl;
+}
+
+const self = process.argv[1] || '';
+if (import.meta.url === `file://${self}` || /perpradar(-mcp)?$/.test(self)) serve();

package/src/paid.js

@@ -0,0 +1,46 @@
+// Optional paid tier for the stdio MCP server: the PerpRadar full tier from the hosted API, paid per call over x402
+// with the user's own wallet. Only active when PERPRADAR_X402_PRIVATE_KEY (or X402_PRIVATE_KEY) is set.
+// Needs the optional peer dependencies @x402/fetch, @x402/evm and viem (loaded lazily; the free path never imports them).
+// Spend guard: Base USDC only, at most $0.03 per payment, and only to the PerpRadar pay-to address.
+import { API_BASE } from './lite.js';
+
+export const PAY_TO = '0x3c1A1E01e790Cd326495631B3b38Bd7068F08d6F';
+export const NETWORK = 'eip155:8453';
+export const MAX_PER_PAYMENT = '$0.03';
+export const KEY_ENVS = ['PERPRADAR_X402_PRIVATE_KEY', 'X402_PRIVATE_KEY'];
+export const INSTALL_HINT = 'Paid mode needs @x402/fetch, @x402/evm and viem next to this package, e.g. command "npx" with args ["-y", "-p", "@agentgate-builder/perpradar", "-p", "@x402/fetch", "-p", "@x402/evm", "-p", "viem", "perpradar"].';
+
+export function keyFromEnv(env = process.env) {
+  for (const k of KEY_ENVS) { const v = (env[k] || '').trim(); if (v) return { name: k, value: v }; }
+  return null;
+}
+
+/** Returns a paying client, null (no key) or { error } (never throws, never echoes the key). */
+export async function createPaidClient({ env = process.env, fetchImpl = globalThis.fetch, apiBase = (env.PERPRADAR_API_URL || API_BASE).replace(/\/+$/, ''), payTo = PAY_TO } = {}) {
+  const key = keyFromEnv(env);
+  if (!key) return null;
+  const hex = key.value.startsWith('0x') ? key.value : `0x${key.value}`;
+  if (!/^0x[0-9a-fA-F]{64}$/.test(hex)) return { error: `${key.name} is set but is not a 32-byte hex private key; using the free preview.` };
+  let wrap, ExactEvmScheme, privateKeyToAccount;
+  try {
+    ({ wrapFetchWithPaymentFromConfig: wrap } = await import('@x402/fetch'));
+    ({ ExactEvmScheme } = await import('@x402/evm'));
+    ({ privateKeyToAccount } = await import('viem/accounts'));
+  } catch {
+    return { error: `${key.name} is set, but ${INSTALL_HINT} Using the free preview.` };
+  }
+  let account;
+  try { account = privateKeyToAccount(hex); } catch { return { error: `${key.name} could not be loaded as an EVM private key; using the free preview.` }; }
+  const onlyUs = (_v, reqs) => reqs.filter((r) => r.network === NETWORK && String(r.payTo).toLowerCase() === payTo.toLowerCase());
+  const pay = wrap(fetchImpl, { schemes: [{ network: NETWORK, client: new ExactEvmScheme(account) }], policies: [onlyUs], spendControls: { maxAmountPerPayment: MAX_PER_PAYMENT } });
+  return {
+    payer: account.address, apiBase,
+    call: async (tier, input) => {
+      const res = await pay(`${apiBase}/v1/${tier}`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(input) });
+      const text = await res.text();
+      let json = null; try { json = JSON.parse(text); } catch { /* not JSON */ }
+      if (!res.ok) return { error: `paid API answered HTTP ${res.status}`, detail: json?.message || json?.error || text.slice(0, 300) };
+      return { result: json, paymentResponse: res.headers.get('payment-response') || res.headers.get('x-payment-response') || null };
+    },
+  };
+}

package/src/version.js

@@ -0,0 +1 @@
+export const VERSION_STR = '0.1.0';