m2m-sentinel-sdk 1.2.5 → 1.2.7

package/agent_adapter.js

@@ -67,7 +67,7 @@ class M2MSentinelActionProvider {
 
     const headers = {
       Accept: 'application/json',
-      'User-Agent': 'M2MSentinel-AgentKit/1.2.5',
+      '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)
       },

package/base_account_paymaster_guard.js

@@ -810,10 +810,59 @@ class BaseAccountPaymasterGuard {
   sendCalls(provider, request, options = {}) {
     return this.request(provider, request, options);
   }
+
+  preflightTransaction(transaction, options = {}) {
+    return preflightBeforeSigning({
+      client: this.client,
+      transaction,
+      policy: options.policy === undefined ? this.policy : options.policy,
+      signAndSend: options.signAndSend,
+      context: options.context
+    });
+  }
+
+  guardTransaction(transaction, options = {}) {
+    return this.preflightTransaction(transaction, options);
+  }
 }
 
 const BaseAccountExecutionGuard = BaseAccountPaymasterGuard;
 
+/**
+ * Productized single-call preflight verification adapter.
+ *
+ * Preflights a caller transaction against M2M Sentinel, validates decision-grade
+ * evidence without invented safety claims, evaluates an affirmative caller-owned
+ * policy, and forwards to the caller's signing/send callback.
+ */
+async function preflightBeforeSigning({ client, transaction, policy, signAndSend, context } = {}) {
+  assertClient(client);
+  if (typeof policy !== 'function') throw new TypeError('An explicit caller-owned policy function is required.');
+  if (typeof signAndSend !== 'function') throw new TypeError('A caller-owned signing/send callback is required.');
+
+  // Validate and canonicalize input transaction
+  const transactionSnapshot = canonicalTransaction(transaction, 'transaction');
+  const observation = await client.preflightTransaction(cloneJson(transactionSnapshot, 'transaction'));
+  const observationSnapshot = cloneJson(observation, 'observation');
+  assertObservationReady(observationSnapshot, transactionSnapshot);
+
+  let callerContext = { transaction: cloneJson(transactionSnapshot, 'transaction') };
+  if (context !== undefined) {
+    if (!isPlainRecord(context)) throw new TypeError('context must be a JSON object when supplied.');
+    callerContext = { ...cloneJson(context, 'context'), ...callerContext };
+  }
+
+  const policyResult = await policy(cloneJson(observationSnapshot, 'observation'), callerContext);
+  if (!isAffirmativePolicyResult(policyResult)) {
+    blocked('CALLER_POLICY_REJECTED', `Transaction rejected: ${policyRejectionReason(policyResult)}`);
+  }
+
+  return signAndSend(cloneJson(transactionSnapshot, 'transaction'), cloneJson(observationSnapshot, 'observation'));
+}
+
+const guardTransaction = preflightBeforeSigning;
+const preflightTransactionBeforeSigning = preflightBeforeSigning;
+
 /** Construct the public SDK client while keeping credentials caller-owned. */
 function createPublicClient({ baseUrl, apiKey, timeoutMs, sdk } = {}) {
   if (typeof apiKey !== 'string' || apiKey.length === 0) {
@@ -861,6 +910,9 @@ module.exports = {
   preflightWalletSendCalls,
   sendCallsWithPreflight,
   executeWalletSendCalls,
+  preflightBeforeSigning,
+  guardTransaction,
+  preflightTransactionBeforeSigning,
   BaseAccountPaymasterGuard,
   BaseAccountExecutionGuard,
   createBaseAccountPaymasterGuard: (options) => new BaseAccountPaymasterGuard(options),

package/eliza_plugin.js

@@ -69,7 +69,7 @@ const m2mSentinelPlugin = {
     },
     {
       name: 'GET_GAS_FEES',
-      description: 'Fetches live Base gas fees.',
+      description: 'Fetches current Base gas-price telemetry with upstream provenance.',
       handler: async (runtime) => {
         try { return { text: JSON.stringify(await clientFor(runtime).getGasFees()) }; }
         catch (err) { return { text: errorText(err) }; }

package/index.d.ts

@@ -198,6 +198,17 @@ export interface BaseAccountGuardCallOptions {
   context?: Record<string, unknown>;
 }
 
+export interface PreflightBeforeSigningOptions {
+  client: Pick<M2MSentinelClient, 'preflightTransaction'>;
+  transaction: TransactionPreflightRequest;
+  policy: (
+    observation: BaseAccountPreflightObservation,
+    context: { transaction: TransactionPreflightRequest; [key: string]: unknown }
+  ) => BaseAccountCallerPolicyResult | Promise<BaseAccountCallerPolicyResult>;
+  signAndSend: (transaction: TransactionPreflightRequest, observation: BaseAccountPreflightObservation) => Promise<unknown>;
+  context?: Record<string, unknown>;
+}
+
 export interface M2MSentinelErrorOptions {
   status?: number;
   body?: unknown;
@@ -285,10 +296,16 @@ export const preflightWalletSendCalls: typeof guardWalletSendCalls;
 export const sendCallsWithPreflight: typeof guardWalletSendCalls;
 export const executeWalletSendCalls: typeof guardWalletSendCalls;
 
+export function preflightBeforeSigning(options: PreflightBeforeSigningOptions): Promise<unknown>;
+export const guardTransaction: typeof preflightBeforeSigning;
+export const preflightTransactionBeforeSigning: typeof preflightBeforeSigning;
+
 export class BaseAccountPaymasterGuard {
   constructor(options: BaseAccountPaymasterGuardOptions);
   request(provider: Eip1193Provider, request: WalletSendCallsRequest, options?: BaseAccountGuardCallOptions): Promise<unknown>;
   sendCalls(provider: Eip1193Provider, request: WalletSendCallsRequest, options?: BaseAccountGuardCallOptions): Promise<unknown>;
+  preflightTransaction(transaction: TransactionPreflightRequest, options?: { policy?: BaseAccountCallerPolicy; signAndSend: (tx: any, obs: any) => Promise<unknown>; context?: Record<string, unknown> }): Promise<unknown>;
+  guardTransaction(transaction: TransactionPreflightRequest, options?: { policy?: BaseAccountCallerPolicy; signAndSend: (tx: any, obs: any) => Promise<unknown>; context?: Record<string, unknown> }): Promise<unknown>;
 }
 
 export const BaseAccountExecutionGuard: typeof BaseAccountPaymasterGuard;

package/langchain_tool.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * LangChain & LangGraph Tool Provider for M2M Sentinel.
+ *
+ * Compatible with @langchain/core/tools StructuredTool and DynamicStructuredTool.
+ */
+
+const { M2MSentinelClient } = require('./index.js');
+
+class M2MSentinelLangChainTools {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.apiKey] M2M Sentinel API Key
+   * @param {string} [options.baseUrl] M2M Sentinel Base URL
+   */
+  constructor(options = {}) {
+    this.client = new M2MSentinelClient(options);
+  }
+
+  /**
+   * Return a list of tool definitions compatible with LangChain agents.
+   * Can be passed directly to `createOpenAIToolsAgent({ tools })` or `AgentExecutor`.
+   */
+  getTools() {
+    return [
+      {
+        name: 'm2m_audit_contract',
+        description: 'Deterministic EVM bytecode capability analysis and proxy resolution for Base contracts. Run before signing or sending transactions to unverified contracts.',
+        schema: {
+          type: 'object',
+          properties: {
+            address: {
+              type: 'string',
+              description: 'The 0x-prefixed 40-hex Ethereum address on Base (Chain ID 8453) to inspect.'
+            }
+          },
+          required: ['address']
+        },
+        func: async ({ address }) => {
+          try {
+            const res = await this.client.auditContract(address);
+            return JSON.stringify(res);
+          } catch (err) {
+            return JSON.stringify({ error: err.message, status: err.status || 500 });
+          }
+        }
+      },
+      {
+        name: 'm2m_get_gas_metrics',
+        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: {}
+        },
+        func: async () => {
+          try {
+            const res = await this.client.getGasFees();
+            return JSON.stringify(res);
+          } catch (err) {
+            return JSON.stringify({ error: err.message, status: err.status || 500 });
+          }
+        }
+      },
+      {
+        name: 'm2m_get_token_price',
+        description: 'Fetch sourced Base DEX spot price for one allowlisted token symbol (e.g. USDC, WETH), with pool provenance and no historical price series.',
+        schema: {
+          type: 'object',
+          properties: {
+            symbol: {
+              type: 'string',
+              description: 'The asset symbol (e.g., USDC, WETH).'
+            }
+          },
+          required: ['symbol']
+        },
+        func: async ({ symbol }) => {
+          try {
+            const res = await this.client.getTokenPrice(symbol);
+            return JSON.stringify(res);
+          } catch (err) {
+            return JSON.stringify({ error: err.message, status: err.status || 500 });
+          }
+        }
+      }
+    ];
+  }
+}
+
+module.exports = {
+  M2MSentinelLangChainTools
+};

package/mcp_server.js

@@ -5,75 +5,131 @@ const https = require('https');
 const http = require('http');
 const readline = require('readline');
 
+const pkg = require('./package.json');
+
 let BASE_URL = process.env.M2M_SENTINEL_BASE_URL || 'https://api.m2msentinel.com';
 let API_KEY = process.env.M2M_SENTINEL_API_KEY || '';
 const TIMEOUT_MS = Number(process.env.M2M_SENTINEL_TIMEOUT_MS || 30000);
-const VERSION = '1.2.5';
+const VERSION = pkg.version;
+
+const SERVER_INSTRUCTIONS =
+  'M2M Sentinel MCP server provides factual, read-only observations on Base Mainnet (chainId 8453).\n\n' +
+  '• Canonical Tools: The six m2m_* tool names (m2m_audit_contract, m2m_get_gas_metrics, m2m_get_token_price, m2m_get_dex_liquidity, m2m_get_whale_signals, m2m_get_service_status) are canonical.\n' +
+  '• Backwards Compatibility: Legacy tool names (audit_contract, get_capability_score, get_gas_fees, get_dex_metrics, get_token_price, get_whale_signals) are not advertised in tools/list but remain compatibility-callable.\n' +
+  '• Upstream Behavior: m2m_get_dex_liquidity returns aggregate tracked pool liquidity metrics without pair query filtering; m2m_get_whale_signals returns recent high-value transfer events (up to 50) without query limit filtering.\n' +
+  '• Access and Errors: The stdio wrapper reads M2M_SENTINEL_API_KEY when set. Protected upstream calls may return structured 401, 402, 429, or 503 responses; x402 payment metadata is surfaced, but this wrapper does not sign payments.\n' +
+  '• Observational Scope: All operations are factual, read-only observations. The server does not custody private keys, sign transactions, or execute on-chain state changes.\n' +
+  '• Limitation: Outputs reflect observed bytecode patterns and telemetry and are not safety, economic, or exploitability guarantees.';
 
 const TOOLS = [
   {
     name: 'm2m_audit_contract',
-    description: 'Return selected static bytecode capability observations, common proxy resolution, limitations, and provenance for a Base contract. This is factual capability observation, not a safety or exploitability guarantee.',
-    inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Base contract address (0x...)' } }, required: ['address'] }
+    description: 'Inspect static bytecode capabilities (e.g. mint, pause, freeze, upgradeability slots), common proxy target resolution, and coverage index for a single Base contract address. Factual capability observation only, not a safety or exploitability guarantee. Distinguishable from m2m_get_service_status (infrastructure status) and legacy score-only endpoints.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        address: {
+          type: 'string',
+          description: 'Base contract address (0x-prefixed 40-hex string, chainId 8453) to inspect.'
+        }
+      },
+      required: ['address']
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_gas_metrics',
-    description: 'Return sourced Base gas fee metrics and execution recommendations.',
-    inputSchema: { type: 'object', properties: {} }
+    description: 'Fetch current Base gas price in wei/gwei with RPC provenance for the upstream observation. Read-only telemetry; does not inspect contract code, return token/DEX pricing, or authorize or submit transactions.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_token_price',
-    description: 'Return sourced Base DEX token price observation for allowlisted assets (e.g. USDC, WETH).',
-    inputSchema: { type: 'object', properties: { symbol: { type: 'string', description: 'Token symbol (USDC, WETH)' } }, required: ['symbol'] }
+    description: 'Fetch the median Base DEX spot price in USD across up to five deepest indexed pools, with contract address, decimals, and pool provenance for one allowlisted token symbol (e.g. USDC, WETH, AERO). Does not return historical price series; contrast with m2m_get_dex_liquidity, which returns aggregate pool reserve depth rather than an asset price.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        symbol: {
+          type: 'string',
+          description: 'Allowlisted token symbol on Base (e.g. USDC, WETH, AERO). Lookups are case-insensitive single symbols.'
+        }
+      },
+      required: ['symbol']
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_dex_liquidity',
-    description: 'Return tracked Base DEX pool reserve and liquidity metrics.',
-    inputSchema: { type: 'object', properties: { pair: { type: 'string' } } }
+    description: 'Fetch aggregate pool reserve, depth, and volume metrics across tracked Base DEX liquidity pools. Reports tracked-pool metrics only and does not filter by individual trading pair; contrast with m2m_get_token_price, which observes token spot prices.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_whale_signals',
-    description: 'Return tracked Base whale transfer signals.',
-    inputSchema: { type: 'object', properties: { limit: { type: 'number' } } }
+    description: 'Fetch up to 50 tracked recent high-value ERC-20 transfer signals on Base with transaction hashes, token/sender/receiver addresses, amounts, and valuation provenance. Observes large on-chain transfer events without query parameter limits; does not inspect contract bytecode or query DEX pricing.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_service_status',
-    description: 'Return real-time operational status of M2M Sentinel upstream RPC and persistence rails.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  // Backwards compatibility aliases
-  {
-    name: 'audit_contract',
-    description: 'Alias for m2m_audit_contract.',
-    inputSchema: { type: 'object', properties: { address: { type: 'string' } }, required: ['address'] }
-  },
-  {
-    name: 'get_capability_score',
-    description: 'Return the static capability coverage index and provenance for a Base contract. This is not a safety score.',
-    inputSchema: { type: 'object', properties: { address: { type: 'string' } }, required: ['address'] }
-  },
-  {
-    name: 'get_gas_fees',
-    description: 'Alias for m2m_get_gas_metrics.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'get_dex_metrics',
-    description: 'Alias for m2m_get_dex_liquidity.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'get_token_price',
-    description: 'Alias for m2m_get_token_price.',
-    inputSchema: { type: 'object', properties: { symbol: { type: 'string' } }, required: ['symbol'] }
-  },
-  {
-    name: 'get_whale_signals',
-    description: 'Alias for m2m_get_whale_signals.',
-    inputSchema: { type: 'object', properties: {} }
+    description: 'Fetch operational status, upstream Base RPC quorum status, and persistence availability for M2M Sentinel infrastructure. Does not return blockchain or market telemetry.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   }
 ];
 
+// Backwards compatibility alias lookup
+const TOOL_ALIASES = Object.freeze({
+  audit_contract: 'm2m_audit_contract',
+  get_capability_score: 'm2m_audit_contract',
+  get_gas_fees: 'm2m_get_gas_metrics',
+  get_dex_metrics: 'm2m_get_dex_liquidity',
+  get_token_price: 'm2m_get_token_price',
+  get_whale_signals: 'm2m_get_whale_signals'
+});
+
 function parseX402Header(value) {
   if (!value) return null;
   try { return JSON.parse(value); } catch (_) {}
@@ -87,8 +143,8 @@ function parseX402Header(value) {
 }
 
 function queryApi(path, customApiKey = null, customBaseUrl = null) {
-  const activeBaseUrl = customBaseUrl || BASE_URL;
-  const activeApiKey = customApiKey !== null ? customApiKey : API_KEY;
+  const activeBaseUrl = customBaseUrl || process.env.M2M_SENTINEL_BASE_URL || BASE_URL;
+  const activeApiKey = customApiKey !== null ? customApiKey : (process.env.M2M_SENTINEL_API_KEY || API_KEY);
 
   return new Promise((resolve, reject) => {
     const url = new URL(path, activeBaseUrl);
@@ -129,12 +185,22 @@ function pathForTool(name, args) {
   const input = args || {};
   switch (name) {
     case 'm2m_audit_contract':
-    case 'audit_contract':
-      if (!input.address) throw new Error('address is required');
-      return '/v1/audit/' + encodeURIComponent(input.address);
-    case 'get_capability_score':
-      if (!input.address) throw new Error('address is required');
-      return '/v1/security/score/' + encodeURIComponent(input.address);
+    case 'audit_contract': {
+      const addr = input.address ? String(input.address).trim() : '';
+      if (!addr) throw new Error('address is required');
+      if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) {
+        throw new Error('A valid 40-hex 0x-prefixed Base contract address is required');
+      }
+      return '/v1/audit/' + encodeURIComponent(addr);
+    }
+    case 'get_capability_score': {
+      const addr = input.address ? String(input.address).trim() : '';
+      if (!addr) throw new Error('address is required');
+      if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) {
+        throw new Error('A valid 40-hex 0x-prefixed Base contract address is required');
+      }
+      return '/v1/security/score/' + encodeURIComponent(addr);
+    }
     case 'm2m_get_gas_metrics':
     case 'get_gas_fees':
       return '/v1/gas/fees';
@@ -142,9 +208,11 @@ function pathForTool(name, args) {
     case 'get_dex_metrics':
       return '/v1/dex/metrics';
     case 'm2m_get_token_price':
-    case 'get_token_price':
-      if (!input.symbol) throw new Error('symbol is required');
-      return '/v1/token/price/' + encodeURIComponent(input.symbol);
+    case 'get_token_price': {
+      const sym = input.symbol ? String(input.symbol).trim().toUpperCase() : '';
+      if (!sym) throw new Error('symbol is required');
+      return '/v1/token/price/' + encodeURIComponent(sym);
+    }
     case 'm2m_get_whale_signals':
     case 'get_whale_signals':
       return '/v1/whales/signals';
@@ -173,24 +241,32 @@ function failure(id, code, message, data) {
   send({ jsonrpc: '2.0', id, error });
 }
 
-async function handleMcpMessage(request) {
+async function handleMcpMessage(request, responder = null) {
+  const replySuccess = responder ? (id, res) => responder({ jsonrpc: '2.0', id, result: res }) : success;
+  const replyFailure = responder ? (id, code, msg, data) => {
+    const error = { code, message: msg };
+    if (data !== undefined) error.data = data;
+    responder({ jsonrpc: '2.0', id, error });
+  } : failure;
+
   if (!request || request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
-    failure(request && request.id !== undefined ? request.id : null, -32600, 'Invalid Request');
+    replyFailure(request && request.id !== undefined ? request.id : null, -32600, 'Invalid Request');
     return;
   }
   if (request.id === undefined || request.id === null) return;
 
   try {
     if (request.method === 'initialize') {
-      success(request.id, {
+      replySuccess(request.id, {
         protocolVersion: request.params && request.params.protocolVersion ? request.params.protocolVersion : '2024-11-05',
         capabilities: { tools: {} },
-        serverInfo: { name: 'm2m-sentinel-mcp', version: VERSION }
+        serverInfo: { name: 'm2m-sentinel-mcp', version: VERSION },
+        instructions: SERVER_INSTRUCTIONS
       });
       return;
     }
     if (request.method === 'tools/list') {
-      success(request.id, { tools: TOOLS });
+      replySuccess(request.id, { tools: TOOLS });
       return;
     }
     if (request.method === 'tools/call') {
@@ -198,7 +274,7 @@ async function handleMcpMessage(request) {
       const path = pathForTool(params.name, params.arguments || {});
       const apiResult = await queryApi(path);
       const isError = !apiResult.ok;
-      success(request.id, {
+      replySuccess(request.id, {
         content: [{ type: 'text', text: typeof apiResult.body === 'object' ? JSON.stringify(apiResult.body, null, 2) : String(apiResult.body) }],
         isError,
         structuredContent: apiResult.body,
@@ -212,9 +288,9 @@ async function handleMcpMessage(request) {
       });
       return;
     }
-    failure(request.id, -32601, 'Method not found');
+    replyFailure(request.id, -32601, 'Method not found');
   } catch (err) {
-    failure(request.id, -32603, err && err.message ? err.message : 'Internal error');
+    replyFailure(request.id, -32603, err && err.message ? err.message : 'Internal error');
   }
 }
 
@@ -250,10 +326,10 @@ USAGE:
 
 COMMANDS:
   audit <address>        Disassemble bytecode, detect capabilities & resolve proxies
-  gas                    Fetch real-time Base Mainnet gas metrics & advice
-  price <symbol>         Fetch DEX liquidity-weighted token price (USDC, WETH, AERO)
-  dex [pair]             Fetch tracked Base liquidity pool metrics
-  whales [limit]         Fetch large ERC-20 transfer signals on Base
+  gas                    Fetch current Base Mainnet gas-price telemetry
+  price <symbol>         Fetch median Base DEX token price from deepest pools (USDC, WETH, AERO)
+  dex                    Fetch aggregate tracked Base liquidity pool metrics
+  whales                 Fetch large ERC-20 transfer signals on Base (up to 50)
   status                 Check live API, RPC quorum, and persistence health
   mcp                    Launch Model Context Protocol stdio JSON-RPC server
 
@@ -419,13 +495,16 @@ async function runCli(args) {
 
     } else if (commandName === 'gas' || commandName === 'fees') {
       console.log('================================================================');
-      console.log('⛽ M2M SENTINEL — BASE GAS METRICS');
+      console.log('⛽ M2M SENTINEL — BASE GAS PRICE TELEMETRY');
       console.log(`Network: Base Mainnet (8453) | Sourced Latency: ${res.latencyMs}ms`);
       console.log('================================================================');
-      console.log(`• Standard Gas Price: ${data.standard || data.gasPriceGwei || '0.005'} gwei`);
-      if (data.fast) console.log(`• Fast Gas Price:     ${data.fast} gwei`);
-      if (data.instant) console.log(`• Instant Gas Price:  ${data.instant} gwei`);
-      if (data.recommendation) console.log(`• Execution Advice:   ${data.recommendation}`);
+      const gasPrice = data && data.gasPrice && typeof data.gasPrice === 'object' ? data.gasPrice : data;
+      const gwei = gasPrice && gasPrice.gwei !== undefined
+        ? gasPrice.gwei
+        : (data && data.gasPriceGwei !== undefined ? data.gasPriceGwei : (data && data.standard));
+      if (gwei !== undefined) console.log(`• Gas Price:          ${gwei} gwei`);
+      if (gasPrice && gasPrice.wei !== undefined) console.log(`• Gas Price:          ${gasPrice.wei} wei`);
+      if (data && data.provenance) console.log(`• RPC Provenance:     ${JSON.stringify(data.provenance)}`);
       console.log('================================================================\n');
 
     } else if (commandName === 'price') {
@@ -473,20 +552,33 @@ async function runCli(args) {
 // Entrypoint: Dual Mode Selection
 // ---------------------------------------------------------------------------
 
-const cliArgs = process.argv.slice(2);
+if (require.main === module) {
+  const cliArgs = process.argv.slice(2);
 
-// If arguments are passed or run in an interactive terminal, invoke CLI
-if (cliArgs.length > 0 || (process.stdin.isTTY && !process.env.M2M_MCP_FORCE)) {
-  if (cliArgs.length === 0) {
-    printHelp();
+  // If arguments are passed or run in an interactive terminal, invoke CLI
+  if (cliArgs.length > 0 || (process.stdin.isTTY && !process.env.M2M_MCP_FORCE)) {
+    if (cliArgs.length === 0) {
+      printHelp();
+    } else {
+      runCli(cliArgs).then((code) => {
+        if (code !== 0 && typeof code === 'number') process.exit(code);
+      });
+    }
   } else {
-    runCli(cliArgs).then((code) => {
-      if (code !== 0 && typeof code === 'number') process.exit(code);
-    });
+    // Piped execution without args -> start MCP stdio server
+    startMcpServer();
   }
-} else {
-  // Piped execution without args -> start MCP stdio server
-  startMcpServer();
 }
 
-module.exports = { TOOLS, pathForTool, parseX402Header, runCli, queryApi };
+module.exports = {
+  TOOLS,
+  TOOL_ALIASES,
+  SERVER_INSTRUCTIONS,
+  pathForTool,
+  parseX402Header,
+  runCli,
+  queryApi,
+  handleMcpMessage,
+  startMcpServer,
+  VERSION
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "m2m-sentinel-sdk",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "mcpName": "io.github.M2M-Sentinel/m2m-sentinel-sdk",
   "publishConfig": {
     "access": "public"
@@ -16,6 +16,9 @@
     "m2m-sentinel": "./mcp_server.js",
     "m2msentinel": "./mcp_server.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "license": "MIT",
   "homepage": "https://m2msentinel.com",
   "repository": {
@@ -54,6 +57,7 @@
     "agent_adapter.js",
     "x402_signer.js",
     "eliza_plugin.js",
+    "langchain_tool.js",
     "mcp_server.js",
     "smithery.yaml",
     "README.md",

package/smithery.yaml

@@ -13,7 +13,7 @@ startCommand:
       M2M_SENTINEL_API_KEY:
         type: string
         title: M2M Sentinel API Key
-        description: Optional API key for higher rate limits. Public free tier works without key.
+        description: Optional API key for prepaid access. Protected calls may return structured 401, 402, 429, or 503 responses without authorized access.
         default: ""
 
 configSchema:
@@ -22,6 +22,6 @@ configSchema:
     M2M_SENTINEL_API_KEY:
       type: string
       title: M2M Sentinel API Key
-      description: Optional API key for higher rate limits. Public free tier works without key.
+      description: Optional API key for prepaid access. Protected calls may return structured 401, 402, 429, or 503 responses without authorized access.
       default: ""
 

package/typescript/base_account_paymaster_guard.ts

@@ -186,6 +186,19 @@ interface ExecutionIdentityBlockedErrorInstance extends Error {
 interface BaseAccountPaymasterGuardInstance {
   request(provider: Eip1193Provider, request: WalletSendCallsRequest, options?: BaseAccountGuardCallOptions): Promise<unknown>;
   sendCalls(provider: Eip1193Provider, request: WalletSendCallsRequest, options?: BaseAccountGuardCallOptions): Promise<unknown>;
+  preflightTransaction(transaction: TransactionPreflightRequest, options?: { policy?: BaseAccountCallerPolicy; signAndSend: (tx: any, obs: any) => Promise<unknown>; context?: Record<string, unknown> }): Promise<unknown>;
+  guardTransaction(transaction: TransactionPreflightRequest, options?: { policy?: BaseAccountCallerPolicy; signAndSend: (tx: any, obs: any) => Promise<unknown>; context?: Record<string, unknown> }): Promise<unknown>;
+}
+
+export interface PreflightBeforeSigningOptions {
+  client: Pick<M2MSentinelClient, 'preflightTransaction'>;
+  transaction: TransactionPreflightRequest;
+  policy: (
+    observation: BaseAccountPreflightObservation,
+    context: { transaction: TransactionPreflightRequest; [key: string]: unknown }
+  ) => BaseAccountCallerPolicyResult | Promise<BaseAccountCallerPolicyResult>;
+  signAndSend: (transaction: TransactionPreflightRequest, observation: BaseAccountPreflightObservation) => Promise<unknown>;
+  context?: Record<string, unknown>;
 }
 
 // This source-distributed TypeScript entrypoint targets Node.js/CommonJS
@@ -243,6 +256,13 @@ export const preflightWalletSendCalls = guardWalletSendCalls;
 export const sendCallsWithPreflight = guardWalletSendCalls;
 export const executeWalletSendCalls = guardWalletSendCalls;
 
+export function preflightBeforeSigning(options: PreflightBeforeSigningOptions): Promise<unknown> {
+  return runtime().preflightBeforeSigning(options);
+}
+
+export const guardTransaction = preflightBeforeSigning;
+export const preflightTransactionBeforeSigning = preflightBeforeSigning;
+
 export const BaseAccountPaymasterGuard: {
   new (options: BaseAccountPaymasterGuardOptions): BaseAccountPaymasterGuardInstance;
 } = runtime().BaseAccountPaymasterGuard;

package/typescript/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "m2m-sentinel-sdk",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "m2m-sentinel-sdk",
-      "version": "1.2.5",
+      "version": "1.2.7",
       "devDependencies": {
         "@types/node": "^22.7.5",
         "typescript": "^5.0.0"

package/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "m2m-sentinel-sdk",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Source-distributed TypeScript client for M2M Sentinel Base capability intelligence API",
   "main": "index.ts",
   "types": "index.ts",

package/typescript/x402.ts

@@ -318,7 +318,7 @@ export class X402SignerClient {
 
   async fetchWithAutoPayment(path: string, options: any = {}): Promise<any> {
     const url = path.startsWith('http') ? path : `${this.baseUrl}/${path.replace(/^\/+/, '')}`;
-    const headers = { 'Accept': 'application/json', 'User-Agent': '@m2msentinel/sdk-ts/1.2.5', ...(options.headers || {}) };
+    const headers = { 'Accept': 'application/json', 'User-Agent': '@m2msentinel/sdk-ts/1.2.7', ...(options.headers || {}) };
 
     let res = await fetch(url, { method: options.method || 'GET', headers, body: options.body });
     if (res.status !== 402) {

package/x402_signer.js

@@ -271,7 +271,7 @@ class X402SignerClient {
         path: url.pathname + url.search,
         method: options.method || 'GET',
         headers: {
-          'User-Agent': 'M2M-Sentinel-X402Signer/1.2.5',
+          'User-Agent': 'M2M-Sentinel-X402Signer/1.2.7',
           'Accept': 'application/json',
           ...(options.headers || {})
         },