m2m-sentinel-sdk 1.2.3 → 1.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M2M Sentinel
+
+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,158 +1,152 @@
-# M2M Sentinel SDKs
+# M2M Sentinel SDK & MCP Server
 
-Production API Base URL: `https://api.m2msentinel.com` (with fallback `https://m2msentinel.com`).
+Official multi-language client library, **Model Context Protocol (MCP) server**, and **Coinbase AgentKit ActionProvider** for M2M Sentinel — deterministic EVM bytecode capability observations and common-proxy resolution for autonomous applications operating on Base. Callers own transaction policy.
 
-Deterministic EVM bytecode and proxy capability intelligence on Base. Factual static capability observation — not a formal reachability audit, safety guarantee, or transaction advice. Live latency depends on RPC availability and deployment geography; transaction middleware requires a caller-defined policy and has no built-in decision threshold.
+[![npm version](https://img.shields.io/npm/v/m2m-sentinel-sdk.svg)](https://www.npmjs.com/package/m2m-sentinel-sdk)
+[![PyPI version](https://img.shields.io/pypi/v/m2m-sentinel.svg)](https://pypi.org/project/m2m-sentinel/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Smithery](https://smithery.ai/badge/m2m-sentinel-sdk)](https://smithery.ai/server/m2m-sentinel-sdk)
 
 ---
 
-## 🏗️ Recommended Defense-in-Depth Pipeline for Agents
-
-Autonomous agents handling value must never rely on a single oracle or heuristic. M2M Sentinel can supply static observations as Layer 1 of a caller-owned pipeline:
-
-```text
-[Agent Intent] 
-       │
-       ▼
-[Transaction Builder]
-       │
-       ▼
-[Stage 1: M2M Sentinel Observation] ── (Bytecode hash, proxy target, selected opcode/selector evidence)
-       │
-       ▼
-[Stage 2: Local Policy Engine]    ── (Caller-defined rules: Check spending bounds, reject DELEGATECALL, verify allowlist)
-       │
-       ▼
-[Stage 3: Execution Simulation]   ── (eth_call / Tenderly / Trace state simulation)
-       │
-       ▼
-[Stage 4: Sub-Wallet Signing]     ── (Scoped ephemeral wallet signs & broadcasts on Base)
-```
-
----
-
-## Installation
+## ⚡ 1. Model Context Protocol (MCP) Server
 
-### JavaScript / TypeScript (npm)
+Connect M2M Sentinel directly to **Claude Desktop**, **Cursor**, **Windsurf**, or any MCP-compliant LLM agent.
 
+### Option A: 1-Click via Smithery
 ```bash
-# Scoped package (recommended)
-npm install @m2msentinel/sdk
+npx -y @smithery/cli mcp add M2M-Sentinel/m2m-sentinel-sdk --client claude
+```
 
-# Or unscoped package
-npm install m2m-sentinel-sdk@1.2.3
+### Option B: Local Stdio (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "m2m-sentinel": {
+      "command": "npx",
+      "args": ["-y", "m2m-sentinel-sdk"],
+      "env": {
+        "M2M_SENTINEL_API_KEY": ""
+      }
+    }
+  }
+}
 ```
 
-### Python (PyPI)
+### Option C: Remote Streamable HTTP
+* **Current MCP endpoint**: `https://api.m2msentinel.com/mcp`
+* **Legacy HTTP+SSE compatibility**: `https://api.m2msentinel.com/sse` with messages at `https://api.m2msentinel.com/messages`
 
-```bash
-pip install m2m-sentinel==1.2.3
-```
+---
 
-### MCP Server (Model Context Protocol)
+## 🤖 2. Coinbase AgentKit Integration
 
-```bash
-npx -y @m2msentinel/sdk
-# or
-npx -y m2m-sentinel-sdk
+```typescript
+import { AgentKit } from "@coinbase/agentkit";
+import { m2mSentinelActionProvider } from "m2m-sentinel-sdk";
+
+const agentKit = await AgentKit.from({
+  walletProvider,
+  actionProviders: [
+    m2mSentinelActionProvider({
+      apiKey: process.env.M2M_SENTINEL_API_KEY
+    })
+  ]
+});
 ```
 
 ---
 
-## Quickstart: JavaScript / TypeScript
+## 📦 3. JavaScript / TypeScript Client
+
+```bash
+npm install m2m-sentinel-sdk
+```
 
 ```javascript
-const { M2MSentinelClient, X402SignerClient } = require('@m2msentinel/sdk');
+const { M2MSentinelClient } = require('m2m-sentinel-sdk');
 
-// 1. Standard API Client (Header Authentication)
-const client = new M2MSentinelClient({
-  apiKey: process.env.M2M_SENTINEL_API_KEY,
-  baseUrl: 'https://api.m2msentinel.com'
-});
+const client = new M2MSentinelClient();
 
-// Inspect contract capabilities before transaction
-const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
-console.log('Contract capabilities:', audit.audit.verdict.executableCapabilities);
-console.log('Capability evidence:', audit.audit.dissection.capabilities);
-console.log('Proxy Target:', audit.audit.proxyResolution.targetAddress);
-console.log('Reachability:', audit.audit.reachability || 'NOT_ESTABLISHED');
-
-// Transaction-specific observation before a caller-owned signing decision.
-const preflight = await client.preflightTransaction({
-  chainId: 8453,
-  to: '0x1111111111111111111111111111111111111111',
-  data: '0x40c10f19'
-});
-console.log('Selector:', preflight.selectorHex);
-console.log('Executing target:', preflight.resolvedExecutionTarget);
-console.log('Observation block:', preflight.observationBlock.blockNumber);
-// The caller must apply its own policy; M2M Sentinel does not return a safety verdict.
-
-// 2. Autonomous Headless x402 Micropayments (EIP-3009 Local Signing)
-const x402Client = new X402SignerClient({
-  walletSigner: myAgentWallet, // ethers / viem signer
-  baseUrl: 'https://api.m2msentinel.com',
-  maxPriceUsd: 0.01 // Optional: strict spending limit (default $0.05)
-});
+async function main() {
+  const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+  console.log('Proxy Detected:', audit.audit.proxyResolution.isProxy);
+  console.log('Proxy Target:', audit.audit.proxyResolution.targetAddress);
+  console.log('Capabilities:', audit.audit.verdict.executableCapabilities);
+  console.log('Evidence:', audit.audit.dissection.capabilities);
+}
 
-const res = await x402Client.fetchWithAutoPayment('/v1/audit/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
-console.log('Paid analysis result:', res.json);
+main().catch(console.error);
 ```
 
 ---
 
-## 🛡️ Autonomous Wallet Policy & Security Boundaries
+## 🛡️ Base Account `wallet_sendCalls` Guard
 
-To prevent autonomous AI agents from blindly signing arbitrary or spoofed HTTP 402 challenges from untrusted sources, `X402SignerClient` enforces **4 strict client-side invariants** locally before generating any cryptographic signature:
+The public SDK includes `guardWalletSendCalls`, a customer-side execution-identity
+boundary for Base Account / EIP-5792 batches. It preflights the anchor call and
+evaluates its caller policy before scheduling any remaining call, then pins
+remaining calls to the first trusted block identity in waves of at most four.
+Each settled wave is validated and policy-checked in ascending request-index
+order before a later wave starts; a failure or rejection stops later scheduling.
+The original detached request is forwarded only after all checks pass. It does
+not sign, broadcast, custody funds, infer inner UserOperation semantics, or
+make a safety claim. See `examples/base_account_paymaster_guard.js` for a no-network fixture.
 
-| Client Invariant | Enforced Value | Security Protection |
-| :--- | :--- | :--- |
-| **Chain ID** | `8453` (Base Mainnet) | Rejects signing on any unapproved EVM chain. |
-| **Asset Contract** | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | Rejects signing for unapproved tokens (Base USDC only). |
-| **Payout Recipient** | `0x6d6c398390cfb88f1cd42715b84906a0bd6652aa` | Rejects signing payments to unexpected recipient addresses. |
-| **Price Ceiling** | `maxPriceUsd` (Default: `$0.05`) | Throws if remote challenge requests funds exceeding caller's authorized ceiling. |
+---
 
-```javascript
-import { X402SignerClient } from '@m2msentinel/sdk';
+## 🐍 4. Python Client
 
-// Fully policy-constrained autonomous signer with immutable recipient & domain constants
-const signer = new X402SignerClient({
-  wallet: agentWallet,
-  maxPriceUsd: 0.005 // Strict spending limit: 0.5 cents max per decision (default $0.05)
-});
+```bash
+pip install m2m-sentinel
+```
+
+```python
+from m2m_sentinel import M2MSentinelClient
+
+client = M2MSentinelClient()
+audit = client.audit_contract("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
+print("Proxy detected:", audit["audit"]["proxyResolution"]["isProxy"])
+print("Proxy target:", audit["audit"]["proxyResolution"].get("targetAddress"))
+print("Capabilities:", audit["audit"]["verdict"]["executableCapabilities"])
+print("Evidence:", audit["audit"]["dissection"]["capabilities"])
 ```
 
 ---
 
-## Authentication and x402
+## Transaction-specific preflight example
 
-Send API keys only in `x-api-key` (or `Authorization: Bearer`). Query-string credentials are rejected with HTTP 401. Payable routes also support x402 v2 on Base USDC. An unpaid call returns a base64 `PAYMENT-REQUIRED` challenge; a successful settlement returns `PAYMENT-RESPONSE`. `POST /v1/transaction/preflight` is API-key/RapidAPI metered and is deliberately not in the x402 catalog; it has no x402 price.
+The public repository includes a standalone, mock-only transaction boundary
+example at [`examples/transaction_preflight.js`](examples/transaction_preflight.js).
+From this repository root, run:
 
----
+```bash
+node examples/transaction_preflight.js
+```
+
+It observes one caller-supplied Base transaction, passes the observation to a
+caller-owned policy, and reaches only a mock signing/send callback. It refuses
+to continue on unverified evidence, unresolved execution, an observation
+mismatch, or a missing Diamond selector mapping. It never signs or sends a
+transaction; optional live mode uses only a caller-supplied API-key header and
+remains the caller's responsibility.
 
-## Public Routes
+---
 
-- `GET /v1/status`
-- `GET /v1/stats` (public privacy envelope; exact aggregate commercial counters are operator-only)
-- `GET /v1/plans`
-- `GET /v1/demo/audit/:address` for the published sample allowlist
-- `GET /v1/audit/:address` (requires API key or x402 payment)
-- `POST /v1/transaction/preflight` (requires an API key or verified RapidAPI proxy authentication; not x402-payable)
+## 💳 5. Autonomous x402 Micropayments (Headless M2M)
 
-The JavaScript, TypeScript, and Python clients expose multi-period purchase/renewal and wallet recovery without requiring callers to hand-build requests:
+```typescript
+import { x402SignerClient } from "m2m-sentinel-sdk";
 
-```javascript
-await client.createSubscriptionIntent('GROWTH', wallet, {
-  durationDays: 90,
-  renewExistingKey: true,
-  apiKey: existingPaidKey
+const client = new x402SignerClient({
+  walletSigner: myAgentWallet,
+  baseUrl: "https://api.m2msentinel.com"
 });
-const challenge = await client.createRecoveryChallenge(wallet, { txHash });
-await client.claimRecoveredKey(challenge.intent.id, walletSignature);
+
+const result = await client.request("/v1/audit/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
 ```
 
 ---
 
-## Disclaimer & Limitations
-
-Deterministic EVM bytecode and proxy capability intelligence on Base. Factual static capability observation — not a formal reachability audit, safety guarantee, or transaction advice. Live latency depends on RPC availability and deployment geography.
+## 📜 License
+MIT License. Copyright (c) 2026 M2M Sentinel.

package/agent_adapter.js

@@ -67,7 +67,7 @@ class M2MSentinelActionProvider {
 
     const headers = {
       Accept: 'application/json',
-      'User-Agent': 'M2MSentinel-AgentKit/1.2.3',
+      'User-Agent': 'M2MSentinel-AgentKit/1.2.7',
       ...options.headers
     };
     if (this.apiKey && !headers['x-api-key']) {
@@ -161,18 +161,16 @@ class M2MSentinelActionProvider {
     return JSON.stringify(res.body);
   }
 
-  async getDexLiquidity(args = {}) {
-    const pair = String(args.pair || 'WETH-USDC').trim();
-    const res = await this._queryApi(`/v1/dex/metrics?pair=${encodeURIComponent(pair)}`);
+  async getDexLiquidity(_args = {}) {
+    const res = await this._queryApi('/v1/dex/metrics');
     if (!res.ok) {
       return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve DEX liquidity' });
     }
     return JSON.stringify(res.body);
   }
 
-  async getWhaleSignals(args = {}) {
-    const limit = Number(args.limit || 10);
-    const res = await this._queryApi(`/v1/whales/signals?limit=${encodeURIComponent(limit)}`);
+  async getWhaleSignals(_args = {}) {
+    const res = await this._queryApi('/v1/whales/signals');
     if (!res.ok) {
       return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve whale signals' });
     }
@@ -198,7 +196,7 @@ class M2MSentinelActionProvider {
       },
       {
         name: 'm2m_get_gas_metrics',
-        description: 'Get real-time Base network gas execution metrics and recommendations before submitting on-chain transactions.',
+        description: 'Fetch current Base gas price in wei/gwei with RPC provenance. Read-only telemetry; does not authorize or submit transactions.',
         schema: {
           type: 'object',
           properties: {}
@@ -207,7 +205,7 @@ class M2MSentinelActionProvider {
       },
       {
         name: 'm2m_get_token_price',
-        description: 'Observe real-time Base DEX token price for slippage check and valuation.',
+        description: 'Fetch the median Base DEX spot price in USD across up to five deepest indexed pools for one allowlisted token symbol. No historical price series.',
         schema: {
           type: 'object',
           properties: {
@@ -222,29 +220,19 @@ class M2MSentinelActionProvider {
       },
       {
         name: 'm2m_get_dex_liquidity',
-        description: 'Get tracked Base DEX pool reserve and liquidity metrics.',
+        description: 'Fetch aggregate reserve, depth, and volume metrics across tracked Base DEX liquidity pools; no individual pair filtering.',
         schema: {
           type: 'object',
-          properties: {
-            pair: {
-              type: 'string',
-              description: 'DEX pair identifier (e.g. WETH-USDC)'
-            }
-          }
+          properties: {}
         },
         invoke: (args) => this.getDexLiquidity(args)
       },
       {
         name: 'm2m_get_whale_signals',
-        description: 'Get tracked Base whale transfer and concentration signals.',
+        description: 'Fetch up to 50 tracked recent high-value ERC-20 transfer signals on Base; no query parameter limit filtering.',
         schema: {
           type: 'object',
-          properties: {
-            limit: {
-              type: 'number',
-              description: 'Maximum signals to retrieve (1-50)'
-            }
-          }
+          properties: {}
         },
         invoke: (args) => this.getWhaleSignals(args)
       },