agentsapi-sec-filings 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# agentsapi-sec-filings
+
+MCP server exposing **SEC EDGAR filings** as agent-callable tools — pay-per-call in USDC on Base via [x402](https://x402.org). No API key, no subscription: every call settles a micropayment on-chain and returns data immediately.
+
+## Tools
+
+| Tool | Description | Price |
+|---|---|---|
+| `sec_filings_today` | Latest 10-K / 10-Q / 8-K filings across US markets, newest first (max 40) | **$0.01 USDC / call** |
+| `sec_filings_8k` | Real-time **8-K material events** stream (M&A, executive changes, earnings, delisting, bankruptcy) | **$0.005 USDC / call** |
+| `sec_filings_service_info` | Free discovery: endpoints, prices, payment network, wallet | free |
+
+Every paid response carries a `receipt` block (`paid`, `payer`, `amount`, `transaction`) so the caller can audit settlement.
+
+## Requirements
+
+- Node.js >= 18
+- An EVM wallet holding **USDC on Base** (mainnet, `eip155:8453`) plus a small amount of ETH for gas on the first transfer
+- The private key is used **locally** to sign the x402 payment payload; it is never sent to the server
+
+## Install
+
+```bash
+npx agentsapi-sec-filings
+```
+
+## Configuration
+
+| Env var | Required | Default | Purpose |
+|---|---|---|---|
+| `X402_PRIVATE_KEY` | yes | — | EVM private key (`0x...`) used to sign payments |
+| `X402_RPC_URL` | no | `https://mainnet.base.org` | Base RPC endpoint |
+| `AGENTSAPI_BASE` | no | `https://agentsapi.top` | API base URL |
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "sec-filings": {
+      "command": "npx",
+      "args": ["-y", "agentsapi-sec-filings"],
+      "env": {
+        "X402_PRIVATE_KEY": "0x<your-base-wallet-key>"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / any stdio MCP client
+
+```json
+{
+  "mcpServers": {
+    "sec-filings": {
+      "command": "npx",
+      "args": ["-y", "agentsapi-sec-filings"],
+      "env": { "X402_PRIVATE_KEY": "0x<your-base-wallet-key>" }
+    }
+  }
+}
+```
+
+## Example agent usage
+
+> "Any 8-K filings in the last few hours that look like M&A activity?"
+
+The agent calls `sec_filings_8k`, the client answers the HTTP 402 challenge with a signed USDC transfer, and the filing list comes back with EDGAR links — $0.005 settled, no signup.
+
+## Payment flow
+
+1. Tool call issues `GET https://agentsapi.top/api/filings/8k`
+2. Server replies `402 Payment Required` with x402 terms (USDC, Base, amount, payTo)
+3. Client signs an EIP-3009 USDC authorization and retries with `X-PAYMENT`
+4. Facilitator settles on-chain; server returns data + `X-PAYMENT-RESPONSE` receipt
+
+## Pricing rationale
+
+- Data is refreshed every 10 minutes; each response contains up to 40 filings.
+- No rate limits, no API keys — cost scales exactly with usage, which keeps agents free to call as needed.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agentsapi-sec-filings",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "agentsapi-sec-filings": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test/client.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "sec",
+    "edgar",
+    "filings",
+    "usdc",
+    "base"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "description": "MCP server for SEC EDGAR filings (10-K / 10-Q / 8-K), pay-per-call in USDC on Base via x402.",
+  "files": [
+    "src",
+    "test",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@x402/core": "^2.25.0",
+    "@x402/evm": "^2.25.0",
+    "viem": "^2.56.3",
+    "zod": "^4.6.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * agentsapi-sec-filings — MCP server for SEC EDGAR filings (x402 pay-per-call)
+ *
+ * Exposes two paid data tools to any MCP-capable agent:
+ *   - sec_filings_today  ($0.01 USDC per call)  latest 10-K / 10-Q / 8-K filings
+ *   - sec_filings_8k     ($0.005 USDC per call) 8-K material-event stream
+ *
+ * Payment is handled automatically in-protocol via x402 (HTTP 402 -> USDC on Base).
+ * The calling side supplies its own wallet key through X402_PRIVATE_KEY.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { x402Client } from "@x402/core/client";
+import { x402HTTPClient } from "@x402/core/http";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+const BASE_URL = (process.env.AGENTSAPI_BASE || "https://agentsapi.top").replace(/\/$/, "");
+const PRIVATE_KEY = (process.env.X402_PRIVATE_KEY || "").trim();
+const RPC_URL = process.env.X402_RPC_URL || "https://mainnet.base.org";
+
+const PAY_TO = "0x381cdbb664608bf7b1dd4f9403a572c1c57332c2";
+const NETWORK = "eip155:8453 (Base mainnet)";
+
+let cachedClient = null;
+
+function buildClient() {
+  if (!PRIVATE_KEY) {
+    throw new Error(
+      "X402_PRIVATE_KEY is not set. Provide an EVM wallet private key (0x...) that holds USDC on Base; " +
+        "payment is signed locally and sent in-protocol, the key is never transmitted."
+    );
+  }
+  if (cachedClient) return cachedClient;
+  const account = privateKeyToAccount(PRIVATE_KEY);
+  const core = new x402Client();
+  registerExactEvmScheme(core, {
+    signer: account,
+    schemeOptions: { rpcUrl: RPC_URL },
+  });
+  cachedClient = { account, client: new x402HTTPClient(core) };
+  return cachedClient;
+}
+
+/**
+ * Call a paid endpoint, completing the x402 handshake when a 402 is returned.
+ */
+async function callPaidEndpoint(path) {
+  const { account, client } = buildClient();
+  const url = `${BASE_URL}${path}`;
+
+  let res = await fetch(url, { headers: { accept: "application/json" } });
+
+  let required = null;
+  if (res.status === 402) {
+    const body = await res.json().catch(() => ({}));
+    required = client.getPaymentRequiredResponse((name) => res.headers.get(name), body);
+    const payload = await client.createPaymentPayload(required);
+    res = await fetch(url, {
+      headers: { accept: "application/json", ...client.encodePaymentSignatureHeader(payload) },
+    });
+  }
+
+  const text = await res.text();
+  if (res.status !== 200) {
+    throw new Error(`Upstream returned HTTP ${res.status}: ${text.slice(0, 300)}`);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error(`Upstream returned non-JSON payload: ${text.slice(0, 300)}`);
+  }
+
+  let settlement = null;
+  try {
+    settlement = client.getPaymentSettleResponse((name) => res.headers.get(name));
+  } catch {
+    settlement = null;
+  }
+
+  const accepted = required?.accepts?.[0];
+  const receipt = {
+    paid: Boolean(settlement?.success ?? true),
+    payer: account.address,
+    payTo: PAY_TO,
+    network: NETWORK,
+    amount: accepted?.amount ? `${Number(accepted.amount) / 1e6} USDC` : undefined,
+    transaction: settlement?.transaction ?? null,
+  };
+
+  return { data, receipt, source: `${BASE_URL}${path}` };
+}
+
+function asText(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+function asError(err) {
+  return {
+    content: [{ type: "text", text: `Error: ${err?.message || String(err)}` }],
+    isError: true,
+  };
+}
+
+const server = new McpServer({
+  name: "agentsapi-sec-filings",
+  version: "1.0.0",
+});
+
+server.registerTool(
+  "sec_filings_today",
+  {
+    title: "Latest SEC filings (10-K / 10-Q / 8-K)",
+    description:
+      "Latest SEC EDGAR filings across 10-K, 10-Q and 8-K form types, sorted by filing time descending " +
+      "(max 40 per call, refreshed every 10 minutes). Each item: form type, company name + CIK, filing time (UTC), " +
+      "EDGAR archive URL. Paid per call: $0.01 USDC on Base, settled automatically over x402.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async () => {
+    try {
+      const { data, receipt, source } = await callPaidEndpoint("/api/filings/today");
+      return asText({ source, receipt, ...data });
+    } catch (err) {
+      return asError(err);
+    }
+  }
+);
+
+server.registerTool(
+  "sec_filings_8k",
+  {
+    title: "SEC 8-K material events (real-time)",
+    description:
+      "Real-time stream of SEC EDGAR 8-K current reports — material corporate events such as M&A, officer changes, " +
+      "earnings releases, delisting and bankruptcy. Sorted by filing time descending, max 40 per call. " +
+      "Paid per call: $0.005 USDC on Base, settled automatically over x402.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async () => {
+    try {
+      const { data, receipt, source } = await callPaidEndpoint("/api/filings/8k");
+      return asText({ source, receipt, ...data });
+    } catch (err) {
+      return asError(err);
+    }
+  }
+);
+
+server.registerTool(
+  "sec_filings_service_info",
+  {
+    title: "SEC filings API service info (free)",
+    description:
+      "Free discovery endpoint: describes the available SEC EDGAR data endpoints, their prices, payment network " +
+      "and wallet address. Use this first to check pricing before calling a paid tool.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async () => {
+    try {
+      const res = await fetch(`${BASE_URL}/openapi.json`, { headers: { accept: "application/json" } });
+      const spec = await res.json();
+      const paths = Object.keys(spec?.paths || {});
+      return asText({
+        service: "agentsapi.top",
+        payment: { protocol: "x402", network: NETWORK, asset: "USDC", payTo: PAY_TO },
+        endpoints: paths,
+        tools: {
+          sec_filings_today: "$0.01 USDC / call",
+          sec_filings_8k: "$0.005 USDC / call",
+        },
+      });
+    } catch (err) {
+      return asError(err);
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/test/client.mjs

@@ -0,0 +1,43 @@
+/**
+ * Local end-to-end test: spawn the MCP server over stdio, list tools,
+ * then call the paid 8-K tool with a real $0.005 USDC payment on Base.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const PRIVATE_KEY = process.env.TEST_X402_PRIVATE_KEY || process.argv[2];
+if (!PRIVATE_KEY) {
+  console.error("usage: node test/client.mjs 0x<privateKey>");
+  process.exit(1);
+}
+
+const transport = new StdioClientTransport({
+  command: "node",
+  args: ["src/index.js"],
+  env: {
+    ...process.env,
+    X402_PRIVATE_KEY: PRIVATE_KEY,
+    X402_RPC_URL: process.env.X402_RPC_URL || "https://mainnet.base.org",
+  },
+  stderr: "inherit",
+});
+
+const client = new Client({ name: "mcp-e2e-test", version: "1.0.0" });
+await client.connect(transport);
+console.log("[1] MCP 连接成功");
+
+const tools = await client.listTools();
+console.log("[2] 工具清单:", tools.tools.map((t) => t.name).join(", "));
+
+console.log("[3] 调用 sec_filings_service_info（免费）...");
+const info = await client.callTool({ name: "sec_filings_service_info", arguments: {} });
+console.log(info.content[0].text.slice(0, 600));
+
+console.log("[4] 调用 sec_filings_8k（真钱 $0.005）...");
+const paid = await client.callTool({ name: "sec_filings_8k", arguments: {} });
+const text = paid.content[0].text;
+console.log("[5] 返回前 900 字符:\n" + text.slice(0, 900));
+console.log("[6] isError:", paid.isError === true);
+
+await client.close();
+console.log("=== MCP 端到端测试结束 ===");

package/test/client_installed.mjs

@@ -0,0 +1,38 @@
+/**
+ * Simulate an external user: install the published tarball into a clean dir,
+ * spawn it over stdio as an MCP server, and call tools through the MCP protocol.
+ * Usage: node test/client_installed.mjs 0x<privateKey>
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const PRIVATE_KEY = process.env.TEST_X402_PRIVATE_KEY || process.argv[2];
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["--no-install", "agentsapi-sec-filings"],
+  env: { ...process.env, X402_PRIVATE_KEY: PRIVATE_KEY || "" },
+  stderr: "inherit",
+});
+
+const client = new Client({ name: "external-user-sim", version: "1.0.0" });
+await client.connect(transport);
+console.log("[1] 通过 npx 启动已安装的 MCP server 成功");
+
+const tools = await client.listTools();
+console.log("[2] 工具:", tools.tools.map((t) => t.name).join(", "));
+
+const info = await client.callTool({ name: "sec_filings_service_info", arguments: {} });
+console.log("[3] 免费工具返回:", info.content[0].text.replace(/\s+/g, " ").slice(0, 300));
+
+if (PRIVATE_KEY) {
+  const paid = await client.callTool({ name: "sec_filings_8k", arguments: {} });
+  const t = paid.content[0].text;
+  console.log("[4] 付费工具 isError:", paid.isError === true);
+  console.log("[5] 付费返回片段:", t.replace(/\s+/g, " ").slice(0, 700));
+} else {
+  console.log("[4] 未提供私钥，跳过付费调用");
+}
+
+await client.close();
+console.log("=== 安装分发链路验证结束 ===");