@agentutility/mcp-edge-market 0.1.8

package/README.md

@@ -0,0 +1,110 @@
+# @agentutility/mcp-edge-market
+
+> Onchain decisions agents can charge for.
+
+Token risk, DEX depth, wallet PnL, gas, bridges, NFTs, DAO proposals, Safe multisig — every onchain question an agent asks before transacting.
+
+**Pricing:** pay-per-call in USDC on Base. No subscriptions, no API keys. See per-tool prices below.
+
+## Install — Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agentutility-edge-market": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-edge-market"],
+      "env": { "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HEX" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. 37 tools appear in the tool palette.
+
+## Install — Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentutility-edge-market": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-edge-market"],
+      "env": { "X402_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+## Funding
+
+Send any amount of **USDC on Base mainnet** to the address derived from your `X402_PRIVATE_KEY`. The MCP server uses it to pay for tool calls automatically.
+
+USDC on Base contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+
+## Tools (37)
+
+| Tool | Description |
+|---|---|
+| `agent-card-resolve` | (0.005 USDC/call) Agent card resolver / ERC-8004 Identity Registry lookup / Trustless Agents / agentId → owner + agentURI / A2A identity / agent.json fetch / on-chain agent metadata. Pass an ERC-8004 agentId (uint256 on Base) — returns the on-chain owner address, the agentURI from the Identity Registry, and the resolved agent card JSON (set fetch_card=false to skip the HTTP follow-up). Reads from Base mainnet Identity Registry 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 via a static eth_call (no gas, no wallet). Useful for agents discovering peers in the A2A ecosystem. |
+| `arbitrage-spread` | (0.005 USDC/call) Cross-exchange arbitrage spread / max-min price / CEX price dispersion / spread % calculator. For any CoinGecko-listed coin, pulls every tracked exchange ticker, computes the lowest and highest USD-converted prices, the spread %, and identifies which exchanges sit at each extreme plus the highest-volume venue. Filters out stale or anomalous tickers. |
+| `basename-resolve` | (0.005 USDC/call) Basename resolver / Coinbase Basenames / .base.eth lookup / Base name service / on-chain name resolution. Forward: pass a basename like 'alice.base.eth' (bare names are auto-suffixed with .base.eth) → returns the registered Ethereum address. Reverse: pass a 0x address → returns the primary basename, if any. Also returns avatar / url / com.twitter / com.github / email / com.discord text records on forward lookups (override with `text_records`). Reads from Base mainnet L2 Resolver 0xC6d566A56A1aFf6508b41f6c90ff131615583BCD via a static eth_call (no gas, no wallet, no API key). Useful for agent-payment flows that need to translate human names to Base addresses. |
+| `bridge-rates` | (0.03 USDC/call) Cross-chain bridge rate aggregator. LiFi public quote API aggregates Across, Stargate, Hop, deBridge, Synapse, CCTP. Free, commercial-OK with attribution. |
+| `contract-source` | (0.01 USDC/call) Verified contract source code / Etherscan source / contract ABI fetcher / Solidity source lookup. For any deployed contract on Ethereum, Base, Optimism, Arbitrum, or Polygon: returns is_verified, contract name, compiler version, parsed ABI, full source, license, optimizer settings, constructor args, and proxy implementation address. |
+| `contract-source-verified` | (0.01 USDC/call) Verified contract source code / Etherscan source / Basescan ABI / Solidity source lookup / contract verification check / ABI fetcher / Etherscan-getsourcecode wrapper. For a deployed contract on Ethereum, Optimism, Polygon, Base, or Arbitrum, returns whether the source is verified, the contract name, compiler version, parsed ABI (as a JSON array, not a string), full Solidity source code (multi-file sources reassembled with '// File: ...' separators), license type, optimizer settings, constructor arguments, and — for proxy contracts — the implementation address. Wraps Etherscan v2's multichain getsourcecode endpoint. |
+| `crypto-tx-explainer` | (0.04 USDC/call) Ethereum/Base/Arbitrum/Optimism/Polygon transaction explainer. Returns receipt + ERC20/ERC721 transfers + contracts + fees + plain-English explanation (Venice). |
+| `dao-proposal-monitor` | (0.03 USDC/call) Snapshot.org DAO proposal monitor. Recent proposals + vote tallies + voter counts for any Snapshot space. Optional Venice TLDR. |
+| `defi-llama-protocol` | (0.02 USDC/call) DefiLlama protocol lookup — TVL, chain breakdown, current TVL, 24h/7d/30d changes, audits, parent protocol, categories. Free public API with attribution. |
+| `defi-yield-pools` | (0.005 USDC/call) DeFi yield pools / APY aggregator / yield-farming opportunities / DeFiLlama yields / cross-protocol APY ranking / stablecoin yields / LP pool returns. Filter and rank thousands of DeFi yield-bearing pools across every chain DeFiLlama tracks. Filters: chain, project, asset symbol, stablecoin-only, single-vs-LP exposure, TVL minimum, APY range, impermanent-loss risk. Returns pool ID, chain, project, symbol, current APY (base + reward), 30-day mean APY, day/week/month APY change, TVL, exposure, IL risk, and predicted-class. Differentiates from defi-llama-protocol (single-protocol TVL) — this is the yield-discovery surface. |
+| `dex-liquidity-depth` | (0.01 USDC/call) DEX liquidity depth / pool TVL aggregator / total liquidity per token / on-chain liquidity audit. Sums TVL across every DefiLlama-tracked yield pool that holds a given ERC-20 on Ethereum, Base, Polygon, Arbitrum, or Optimism. Returns per-pool TVL + APY plus total liquidity in USD and the deepest pool. Free public DefiLlama backend, no auth. |
+| `ens-resolve` | (0.03 USDC/call) ENS resolver / Ethereum Name Service lookup. Forward (vitalik.eth → 0x...address) and reverse (0x... → primary ENS name) with text records (avatar, url, description, com.twitter, com.github, email, org.telegram). |
+| `erc20-balance` | (0.002 USDC/call) ERC-20 balance reader / balanceOf / on-chain token balance / wallet balance lookup / multi-chain ERC20 balance / read Base / read Ethereum / read Arbitrum / read Optimism / read Polygon. Reads balanceOf(wallet) on a token contract across any supported EVM chain via public RPC (no API key needed). Co-fetches decimals to return both raw bigint and decimal-formatted balance. Supports historical block parameter. Useful for agent wallet introspection, payment reconciliation, treasury monitoring. |
+| `erc20-metadata` | (0.002 USDC/call) ERC-20 metadata reader / token info / token symbol lookup / token decimals / total supply / multi-chain ERC20 reader / Base / Ethereum / Arbitrum / Optimism / Polygon / BSC / Avalanche. Reads name(), symbol(), decimals(), totalSupply() in parallel via public RPC. Robust to non-standard tokens that return bytes32 instead of string (MakerDAO MKR pattern is decoded). Returns formatted total supply when decimals are present, plus a chain-appropriate block explorer URL. |
+| `eth-logs` | (0.01 USDC/call) eth_getLogs / on-chain event logs / EVM event reader / Transfer event scan / ERC20 Transfer logs / NFT mint logs / DEX swap events / multi-chain log scanner / log indexer / smart contract event reader. Generic eth_getLogs across Base / Ethereum / Arbitrum / Optimism / Polygon / BSC via public no-auth RPC. Supports address + up to 4 topics (with OR arrays), from/to block range, and a 'last_n_blocks' convenience param. Hard-capped at 5,000 logs and 10,000-block range per call. |
+| `funding-rates` | (0.002 USDC/call) Perp funding rates / Binance USD-M futures funding / next-funding-time / 24h history / perp basis. Current funding %, mark + index price, next funding timestamp, and last 24 funding intervals (default 24 × 1h-since-event) for any Binance USD-M futures symbol (BTCUSDT, ETHUSDT, SOLUSDT…). Free public Binance API — no auth. |
+| `gas-now-base` | (0.02 USDC/call) Gas oracle / EIP-1559 fee estimator. Real-time base fee + priority fee for Base / Ethereum / Optimism / Arbitrum / Polygon. USD-cost estimates for native transfer, USDC transfer, ERC-20 approve, Uniswap V2/V3 swap, NFT mint, contract deploy. |
+| `gas-price` | (0.02 USDC/call) Gas price API / EIP-1559 fee estimator / Base + Ethereum + Optimism + Arbitrum gas tracker / pre-tx cost estimator. Reads the chain's latest block, derives base fee, suggests priority fees for safe-low/standard/fast tiers, computes total maxFeePerGas, and converts cost to USD for common tx types. |
+| `honeypot-check` | (0.05 USDC/call) Honeypot.is buy/sell simulation for any Base or Ethereum ERC-20. Returns is_honeypot verdict, buy/sell/transfer tax %, simulation success flag, and a reason string when a honeypot is detected. Use before every swap to detect sell-blocking risk. |
+| `ipfs-fetch` | (0.005 USDC/call) IPFS fetch / IPFS gateway / Web3 storage retrieval / NFT metadata fetcher / Filecoin gateway / decentralized content / pinned-content reader. Resolves a CID (CIDv0 Qm... or CIDv1 bafy...) and optional sub-path through a fallback chain of public gateways (cloudflare-ipfs.com → ipfs.io → dweb.link) and returns the content as base64 / text / parsed JSON. Hard cap 5 MB. HEAD pre-flight + streaming size cap so oversized files are rejected before they're fully downloaded. No API key required. |
+| `lp-lock-check` | (0.01 USDC/call) LP lock check / liquidity-lock auditor / Unicrypt + Team Finance + burn-address detection. For any LP token (Uniswap V2-shaped) on Ethereum or Base, reports the % of supply held by the canonical LP-locker contracts (Unicrypt v2, Team Finance) plus burn addresses (0x0, 0xdead). Returns a verdict of locked (≥95%), partial (1-95%), or none. Useful for detecting rug-pull risk before swapping into a new pair. |
+| `nft-floor` | (0.01 USDC/call) NFT collection floor + recent sales via Reservoir. Ethereum / Base / Arbitrum / Optimism / Polygon. Floor, top bid, 24h/7d/30d volume + change, ranks, recent sales. |
+| `price-impact` | (0.005 USDC/call) Price-impact / slippage estimator / DEX swap size impact / size-keyed quote / depth simulation. For a (from_token, to_token, chain), pulls aggregator quotes (LlamaSwap meta-aggregator, free public) at multiple USD sizes and reports per-size effective price + slippage versus the smallest size. Use to size a fill before submitting it on-chain. |
+| `safe-multisig-status` | (0.005 USDC/call) Safe multisig status / Gnosis Safe info / Safe owners / Safe threshold / Safe pending queue / DAO treasury wallet / Safe wallet lookup. Reads a Safe (Gnosis Safe) multisig's on-chain state — owners[], threshold, nonce, version, master copy, fallback handler, guard — via batched eth_call on Base / Ethereum / Arbitrum / Optimism / Polygon (no key, no gas). Also fetches pending (unexecuted) transactions from the Safe Transaction Service. DAO/treasury agents need this constantly to verify multisig config + watch the execution queue. |
+| `safe-tx-decode` | (0.003 USDC/call) Gnosis Safe execTransaction decoder. Decodes a Safe multisig tx hash or raw calldata into target/value/data/operation/gas/signers. Auto-decodes inner MultiSend batches. |
+| `stablecoin-monitor` | (0.005 USDC/call) Stablecoin monitor. Live prices and basis-point deviation from $1 for USDT, USDC, DAI, FRAX, PYUSD, FDUSD, USDE, RLUSD. Configurable depeg-alert threshold. Wraps the same backend as stablecoin-peg under a clearer slug. |
+| `stablecoin-peg` | (0.005 USDC/call) Stablecoin peg monitor / depeg detector. Real-time prices for USDT, USDC, DAI, FRAX, PYUSD, FDUSD, USDE, RLUSD. Configurable depeg alert threshold (basis points). Catches USDC's 2023-style depegs in real time. |
+| `token-burn-stats` | (0.005 USDC/call) Token burn stats / total burned / latest burn tx / burn-as-% supply / supply-burn auditor. Walks all transfers TO the canonical burn addresses (0x0…0 and 0x…dEaD) for any ERC-20 on Ethereum, Base, Polygon, Arbitrum, or Optimism via Etherscan v2 and reports total burned (raw + human), most-recent burn tx + timestamp, count of burn transfers, and burn percentage of total supply. |
+| `token-honeypot` | (0.05 USDC/call) EVM token honeypot detection / can-i-sell check / rug-pull scanner / sell-tax simulator / buy-tax simulator / scam token detector / Base honeypot / Ethereum honeypot / BSC honeypot. Simulates a buy + sell of an ERC-20 token via honeypot.is, returning whether the token is a honeypot, the realized buy/sell/transfer tax percentages, max buy/sell amounts (atomic units), proxy/owner contract flags, and a normalized risk level (low/medium/high/critical) with human-readable reasons. Free public API — no auth. |
+| `token-price` | (0.02 USDC/call) Crypto token price API / CoinGecko wrapper. Lookup by id (bitcoin), symbol (BTC), or contract address (with chain). USD + native currency, 24h/7d change, market cap, volume, supply, ATH, ATL. |
+| `token-risk` | (0.10 USDC/call) Token risk score / token security audit / rug-pull score / token safety check. Composite 0-100 score from honeypot.is + GoPlus Security + Etherscan contract age. Subscores: honeypot, taxes, holder concentration, liquidity, contract age, ownership. Verdict: safe / caution / high_risk. |
+| `token-risk-score` | (0.10 USDC/call) Composite EVM token risk score / token security audit / rug-pull score / token safety check / honeypot + tax + holder concentration / GoPlus + honeypot.is composite / Base token vetting / Ethereum token vetting / BSC token vetting. Pulls three independent signals in parallel — honeypot.is (sell simulation + buy/sell tax), GoPlus Security (holder concentration, LP holders + lock, ownership flags, mintable/proxy/hidden-owner detection), and Etherscan v2 contract creation block (for age) — and rolls them up into a 0-100 score (higher = safer) with subscores (honeypot, taxes, holder_concentration, liquidity, contract_age, ownership) and a verdict (safe / caution / high_risk). Each backend failure degrades just that subscore and adds a warning; the rest still computes. |
+| `token-volatility` | (0.005 USDC/call) Token volatility / historical volatility / annualized vol / standard deviation of returns / crypto vol calculator. For any CoinGecko-listed token, computes log-return standard deviation over the last N days (default 30) and annualizes by sqrt(365). Returns daily and annualized volatility as percent, count of return observations, first and last close prices. Backed by CoinGecko's free public market_chart endpoint. |
+| `tx-receipt-decode` | (0.02 USDC/call) EVM transaction receipt decoder / log decoder / event log reader / Etherscan tx debug / receipt parser / Basescan tx explainer / tenderly-style trace lite. Given a tx hash, fetches the receipt + transaction via Etherscan v2 and decodes every log: ERC-20 / ERC-721 Transfer + Approval + ApprovalForAll are decoded canonically (from/to/value/tokenId etc.); other logs use the contract's verified ABI when available; remaining unknown topics are looked up against 4byte.directory's event-signature index. Returns status (success/failed), block number, gas used + gas price (gwei), from/to/value, and a structured array of decoded logs with named params and contract names where verified. |
+| `tx-simulate-swap` | (0.02 USDC/call) Tx simulate swap / pre-trade quote / DEX swap simulator / 1inch + LlamaSwap quote / would-it-succeed check. Given (from_token, to_token, amount_in, chain), pulls a routed quote from a free DEX meta-aggregator and returns expected output, min-out at user-supplied slippage (default 1%), gas estimate, router address, and a would_succeed verdict. Quote-only depth — full Tenderly-style state simulation requires a paid API and is documented in the response's simulation_caveat. |
+| `wallet-label` | (0.005 USDC/call) Wallet label / address tagger / known-address lookup / EOA-vs-contract check / deployer tracer. Best-effort labelling for any EVM address against an in-handler dictionary of well-known CEX hot/cold wallets, DEX routers, NFT marketplaces, popular MEV bots, bridges, and stablecoins. Etherscan v2 'getcontractcreation' adds is_contract + deployer for unknown contracts. Returns label, category, and the source of the match. |
+| `wallet-pnl` | (0.05 USDC/call) Wallet token P&L / FIFO cost basis / realized + unrealized profit / EVM portfolio analytics. For any (wallet, ERC-20, chain) triple, pulls all transfers from Etherscan v2, prices each one at the historical USD spot via CoinGecko, runs FIFO accounting and reports cost basis, realized gain, unrealized gain, current balance, and tx count. Capped at the most recent 500 transfers. |
+
+## How it works
+
+1. Agent calls a tool (e.g. `agent-card-resolve`).
+2. MCP server POSTs to `https://x402.agentutility.ai/agent-card-resolve`.
+3. The endpoint responds **HTTP 402** with payment instructions.
+4. The MCP server signs an EIP-3009 USDC transfer authorization with `X402_PRIVATE_KEY` and retries.
+5. CDP facilitator settles on Base.
+6. The endpoint returns the actual response.
+
+The agent never sees the payment flow — it just gets the result.
+
+## Links
+
+- Cluster overview: https://agentutility.ai/edge-market/
+- All MCP packages: https://mcp.agentutility.ai/
+- Source: https://github.com/rooz21/x402/tree/main/packages/mcp-edge-market
+
+---
+
+**Version:** 0.1.8 · **License:** MIT

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @agentutility/mcp-<cluster> — stdio MCP server exposing the cluster's
+ * x402-paid endpoints as MCP tools. Forwards every CallToolRequest to
+ * x402.agentutility.ai, where @x402/fetch handles 402 → payment → retry
+ * using the agent's own wallet (X402_PRIVATE_KEY env var).
+ *
+ * Boilerplate is single-sourced at packages/_template/src/index.ts and
+ * copied verbatim into each packages/mcp-<cluster>/src/index.ts by
+ * scripts/generate-mcp-clusters.mjs. The codegen also writes a matching
+ * tools.generated.ts so this file imports CLUSTER_SLUG + VERSION + TOOLS
+ * rather than hard-coding.
+ *
+ * Required env: X402_PRIVATE_KEY (hex EVM key, USDC on Base).
+ * Optional env: X402_BASE_URL (default https://x402.agentutility.ai)
+ *               X402_RPC_URL  (default https://mainnet.base.org)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { TOOLS, CLUSTER_SLUG, VERSION } from "./tools.generated.js";
+const BASE_URL = (process.env.X402_BASE_URL || "https://x402.agentutility.ai").replace(/\/$/, "");
+const RPC_URL = process.env.X402_RPC_URL || "https://mainnet.base.org";
+const PK = process.env.X402_PRIVATE_KEY;
+if (!PK) {
+    console.error(`[@agentutility/mcp-${CLUSTER_SLUG}] FATAL: X402_PRIVATE_KEY env var is required.`);
+    console.error("Set it to a hex-encoded EVM private key with USDC balance on Base (chain 8453).");
+    console.error("USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+    process.exit(1);
+}
+const account = privateKeyToAccount((PK.startsWith("0x") ? PK : `0x${PK}`));
+const publicClient = createPublicClient({
+    chain: base,
+    transport: http(RPC_URL),
+});
+const signer = toClientEvmSigner(account, publicClient);
+const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+async function trackedFetch(url, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("X-Agent-Channel", `mcp-stdio-${CLUSTER_SLUG}`);
+    headers.set("X-Agent-Id", "47167");
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", `agentutility-mcp/${CLUSTER_SLUG}/${VERSION}`);
+    }
+    return paidFetch(url, { ...init, headers });
+}
+const server = new Server({ name: `agentutility-${CLUSTER_SLUG}`, version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.input_schema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    try {
+        const res = await trackedFetch(`${BASE_URL}/${tool.http_name}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req.params.arguments ?? {}),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: `HTTP ${res.status}: ${body}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: body }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `tool call failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+await server.connect(new StdioServerTransport());