@scriptmasterlabs/mcp-x402 2.0.0

package/src/server/tools/agentcard.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeX402Payment } from '../payments/x402.js';
+import { RateLimiter } from '../security/rate-limit.js';
+import { Sandbox } from '../security/sandbox.js';
+import { AuditLogger } from '../security/audit.js';
+import { PriceRegistry } from '../registry/pricing.js';
+import { AgentCardAPI } from '../../lib/sml-api/agentcard.js';
+
+const LookupSchema = z.object({
+  identifier: z.string().min(1),
+});
+
+const VerifySchema = z.object({
+  wallet_address: z.string().min(10),
+  message: z.string().min(1),
+  signature: z.string().min(1),
+});
+
+const MintSchema = z.object({
+  wallet_address: z.string().min(10),
+  name: z.string().min(1).max(64),
+  did: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+  payment_wallet: z.string().optional(),
+});
+
+export function registerAgentCard(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── FREE: agentcard_lookup ─────────────────────────────────────────────────
+  server.tool(
+    'agentcard_lookup',
+    {
+      identifier: z.string().describe('Agent wallet address or DID to look up.'),
+    },
+    async (rawArgs) => {
+      const { identifier } = Sandbox.validate(LookupSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('agentcard_lookup')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await AgentCardAPI.lookup(identifier);
+        audit.info('agentcard_lookup', { identifier });
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── FREE: agentcard_verify ─────────────────────────────────────────────────
+  server.tool(
+    'agentcard_verify',
+    {
+      wallet_address: z.string().describe('Agent wallet address that signed the message.'),
+      message: z.string().describe('Original message that was signed.'),
+      signature: z.string().describe('Ed25519 signature (hex or base64).'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(VerifySchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('agentcard_verify')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await AgentCardAPI.verify({
+          walletAddress: args.wallet_address,
+          message: args.message,
+          signature: args.signature,
+        });
+        audit.info('agentcard_verify', { wallet_address: args.wallet_address });
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── PAID: agentcard_mint (0.01 USDC) ──────────────────────────────────────
+  server.tool(
+    'agentcard_mint',
+    {
+      wallet_address: z.string().describe('XRPL wallet address for the new agent identity.'),
+      name: z.string().describe('Human-readable agent name (max 64 chars).'),
+      did: z.string().describe('Optional DID (decentralized identifier) for the agent.'),
+      metadata: z.record(z.unknown()).describe('Optional metadata object (capabilities, version, etc.).'),
+      payment_wallet: z.string().describe('Wallet to pay x402 fee from (defaults to wallet_address).'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(MintSchema, rawArgs);
+      const paymentWallet = args.payment_wallet ?? args.wallet_address;
+
+      if (!RateLimiter.getInstance().checkTool('agentcard_mint')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+
+      await PriceRegistry.getInstance().seedDefaults();
+      const price = await PriceRegistry.getInstance().getPrice('agentcard_mint');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'agentcard_mint', walletAddress: paymentWallet });
+      } catch (err) {
+        audit.warn('agentcard_mint_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await AgentCardAPI.mint({
+          walletAddress: args.wallet_address,
+          name: args.name,
+          did: args.did,
+          metadata: args.metadata,
+        });
+        audit.info('agentcard_mint_success', { name: args.name, receiptId: payment.receiptId });
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              data,
+              _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain, amount_paid: `${payment.amountPaid} ${payment.currency}`, timestamp: payment.timestamp },
+            }),
+          }],
+        };
+      } catch (err) {
+        audit.error('agentcard_mint_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+}

package/src/server/tools/backtest.ts

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeX402Payment } from '../payments/x402.js';
+import { RateLimiter } from '../security/rate-limit.js';
+import { Sandbox } from '../security/sandbox.js';
+import { AuditLogger } from '../security/audit.js';
+import { PriceRegistry } from '../registry/pricing.js';
+import { BacktestAPI } from '../../lib/sml-api/backtest.js';
+
+const BacktestSchema = z.object({
+  ticker: z.string().min(1).max(10).toUpperCase(),
+  lookback_days: z.number().int().min(30).max(1260).default(252),
+  fees: z.number().min(0).max(0.05).default(0.001),
+  slippage: z.number().min(0).max(0.05).default(0.0005),
+  momentum_window: z.number().int().min(2).max(50).default(10),
+  momentum_threshold: z.number().min(0).max(0.1).default(0.001),
+  wallet_address: z.string().optional(),
+});
+
+const ValidateSchema = z.object({
+  ticker: z.string().min(1).max(10).toUpperCase(),
+  lookback_days: z.number().int().min(60).max(1260).default(504),
+  train_ratio: z.number().min(0.5).max(0.9).default(0.7),
+  fees: z.number().min(0).max(0.05).default(0.001),
+  slippage: z.number().min(0).max(0.05).default(0.0005),
+  wallet_address: z.string().optional(),
+});
+
+export function registerBacktest(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── backtest_run — full backtest on live price data (FREE) ─────────────────
+  server.tool(
+    'backtest_run',
+    {
+      ticker: z.string().describe('Ticker symbol (e.g. NVDA, SPY, GME)'),
+      lookback_days: z.number().describe('Days of history to backtest (30–1260, default 252)'),
+      fees: z.number().describe('Round-trip commission rate (default 0.001 = 0.1%)'),
+      slippage: z.number().describe('Slippage per side (default 0.0005)'),
+      momentum_window: z.number().describe('Momentum rolling window in days (default 10)'),
+      momentum_threshold: z.number().describe('Minimum momentum to enter long (default 0.001)'),
+      wallet_address: z.string().describe('Agent wallet address (optional)'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(BacktestSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('backtest_run')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      try {
+        const result = await BacktestAPI.backtest({
+          ticker: args.ticker,
+          lookback_days: args.lookback_days,
+          fees: args.fees,
+          slippage: args.slippage,
+          momentum_window: args.momentum_window,
+          momentum_threshold: args.momentum_threshold,
+        });
+        audit.info('backtest_run_success', { ticker: args.ticker });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      } catch (err) {
+        audit.warn('backtest_run_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── backtest_validate — walk-forward OOS validation ($0.02) ───────────────
+  server.tool(
+    'backtest_validate',
+    {
+      ticker: z.string().describe('Ticker symbol to validate'),
+      lookback_days: z.number().describe('Total history window (60–1260, default 504 = 2 years)'),
+      train_ratio: z.number().describe('Train/test split ratio (default 0.7 = 70% in-sample)'),
+      fees: z.number().describe('Round-trip commission rate (default 0.001)'),
+      slippage: z.number().describe('Slippage per side (default 0.0005)'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment (AP2 required)'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(ValidateSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('backtest_validate')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      await PriceRegistry.getInstance().seedDefaults();
+      const price = await PriceRegistry.getInstance().getPrice('backtest_validate');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'backtest_validate', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('backtest_validate_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+      try {
+        const result = await BacktestAPI.walkForward({
+          ticker: args.ticker,
+          lookback_days: args.lookback_days,
+          train_ratio: args.train_ratio,
+          fees: args.fees,
+          slippage: args.slippage,
+        });
+        audit.info('backtest_validate_success', { ticker: args.ticker });
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              ...(result as object),
+              _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain, amount_paid: `${payment.amountPaid} ${payment.currency}` },
+            }),
+          }],
+        };
+      } catch (err) {
+        audit.warn('backtest_validate_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+}

package/src/server/tools/brokers.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeX402Payment } from '../payments/x402.js';
+import { RateLimiter } from '../security/rate-limit.js';
+import { Sandbox } from '../security/sandbox.js';
+import { AuditLogger } from '../security/audit.js';
+import { PriceRegistry } from '../registry/pricing.js';
+import { TradierAPI, RobinhoodAPI } from '../../lib/sml-api/brokers.js';
+
+// ── Schemas ────────────────────────────────────────────────────────────────
+
+const TradierQuoteSchema = z.object({
+  symbols: z.string().min(1).max(200),
+});
+
+const TradierOrderSchema = z.object({
+  account_id: z.string().min(1),
+  symbol: z.string().min(1).max(10).toUpperCase(),
+  side: z.enum(['buy', 'sell']),
+  quantity: z.number().int().min(1).max(10000),
+  type: z.enum(['market', 'limit', 'stop', 'stop_limit']),
+  duration: z.enum(['day', 'gtc', 'pre', 'post']),
+  price: z.number().positive().optional(),
+  stop: z.number().positive().optional(),
+  wallet_address: z.string().optional(),
+});
+
+const RobinhoodQuoteSchema = z.object({
+  symbol: z.string().min(1).max(10).toUpperCase(),
+});
+
+const RobinhoodOrderSchema = z.object({
+  symbol: z.string().min(1).max(10).toUpperCase(),
+  side: z.enum(['buy', 'sell']),
+  quantity: z.number().int().min(1).max(10000),
+  type: z.enum(['market', 'limit']),
+  time_in_force: z.enum(['gfd', 'gtc', 'ioc', 'opg']),
+  price: z.number().positive().optional(),
+  wallet_address: z.string().optional(),
+});
+
+const AccountSchema = z.object({
+  account_id: z.string().min(1),
+});
+
+// ── Registration ───────────────────────────────────────────────────────────
+
+export function registerBrokers(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── tradier_quote — FREE ─────────────────────────────────────────────────
+  server.tool(
+    'tradier_quote',
+    {
+      symbols: z.string().describe('Comma-separated ticker symbols (e.g. "NVDA,SPY,AAPL")'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(TradierQuoteSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('tradier_quote')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      try {
+        const data = await TradierAPI.quote({ symbols: args.symbols });
+        audit.info('tradier_quote_success', { symbols: args.symbols });
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+      } catch (err) {
+        audit.warn('tradier_quote_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── tradier_order — $0.01 x402 ──────────────────────────────────────────
+  server.tool(
+    'tradier_order',
+    {
+      account_id: z.string().describe('Tradier brokerage account ID'),
+      symbol: z.string().describe('Ticker symbol (e.g. NVDA)'),
+      side: z.string().describe('"buy" or "sell"'),
+      quantity: z.number().describe('Number of shares (integer)'),
+      type: z.string().describe('"market" | "limit" | "stop" | "stop_limit"'),
+      duration: z.string().describe('"day" | "gtc" | "pre" | "post"'),
+      price: z.number().describe('Limit price (required for limit/stop_limit orders)'),
+      stop: z.number().describe('Stop price (required for stop/stop_limit orders)'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment (AP2 required)'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(TradierOrderSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('tradier_order')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      await PriceRegistry.getInstance().seedDefaults();
+      const price = await PriceRegistry.getInstance().getPrice('tradier_order');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'tradier_order', walletAddress: args.wallet_address });
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+      try {
+        const result = await TradierAPI.order({
+          account_id: args.account_id,
+          symbol: args.symbol,
+          side: args.side,
+          quantity: args.quantity,
+          type: args.type,
+          duration: args.duration,
+          price: args.price,
+          stop: args.stop,
+        });
+        audit.info('tradier_order_success', { symbol: args.symbol, side: args.side, quantity: args.quantity });
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              ...(result as object),
+              _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain, amount_paid: `${payment.amountPaid} ${payment.currency}` },
+            }),
+          }],
+        };
+      } catch (err) {
+        audit.warn('tradier_order_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── tradier_positions — FREE ─────────────────────────────────────────────
+  server.tool(
+    'tradier_positions',
+    {
+      account_id: z.string().describe('Tradier brokerage account ID'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(AccountSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('tradier_positions')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      try {
+        const [positions, balances] = await Promise.all([
+          TradierAPI.positions(args.account_id),
+          TradierAPI.balances(args.account_id),
+        ]);
+        return { content: [{ type: 'text', text: JSON.stringify({ positions, balances }) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── robinhood_quote — FREE ───────────────────────────────────────────────
+  server.tool(
+    'robinhood_quote',
+    {
+      symbol: z.string().describe('Ticker symbol (e.g. NVDA)'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(RobinhoodQuoteSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('robinhood_quote')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      try {
+        const data = await RobinhoodAPI.quote(args.symbol);
+        audit.info('robinhood_quote_success', { symbol: args.symbol });
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+      } catch (err) {
+        audit.warn('robinhood_quote_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── robinhood_order — $0.01 x402 ────────────────────────────────────────
+  server.tool(
+    'robinhood_order',
+    {
+      symbol: z.string().describe('Ticker symbol (e.g. NVDA)'),
+      side: z.string().describe('"buy" or "sell"'),
+      quantity: z.number().describe('Number of shares (integer)'),
+      type: z.string().describe('"market" or "limit"'),
+      time_in_force: z.string().describe('"gfd" (good for day) | "gtc" | "ioc" | "opg"'),
+      price: z.number().describe('Limit price (required for limit orders)'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment (AP2 required)'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(RobinhoodOrderSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('robinhood_order')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      await PriceRegistry.getInstance().seedDefaults();
+      const price = await PriceRegistry.getInstance().getPrice('robinhood_order');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'robinhood_order', walletAddress: args.wallet_address });
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+      try {
+        const result = await RobinhoodAPI.order({
+          symbol: args.symbol,
+          side: args.side,
+          quantity: args.quantity,
+          type: args.type,
+          time_in_force: args.time_in_force,
+          price: args.price,
+        });
+        audit.info('robinhood_order_success', { symbol: args.symbol, side: args.side, quantity: args.quantity });
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              ...(result as object),
+              _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain, amount_paid: `${payment.amountPaid} ${payment.currency}` },
+            }),
+          }],
+        };
+      } catch (err) {
+        audit.warn('robinhood_order_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── robinhood_portfolio — FREE ───────────────────────────────────────────
+  server.tool(
+    'robinhood_portfolio',
+    {},
+    async () => {
+      if (!RateLimiter.getInstance().checkTool('robinhood_portfolio')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+      try {
+        const [portfolio, positions, orders] = await Promise.all([
+          RobinhoodAPI.portfolio(),
+          RobinhoodAPI.positions(),
+          RobinhoodAPI.orderHistory(),
+        ]);
+        return { content: [{ type: 'text', text: JSON.stringify({ portfolio, positions, recent_orders: orders }) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };
+      }
+    },
+  );
+}

package/src/server/tools/copytrader.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeX402Payment } from '../payments/x402.js';
+import { RateLimiter } from '../security/rate-limit.js';
+import { Sandbox } from '../security/sandbox.js';
+import { AuditLogger } from '../security/audit.js';
+import { PriceRegistry } from '../registry/pricing.js';
+import { CopyTraderAPI } from '../../lib/sml-api/copytrader.js';
+
+const SubscribeSchema = z.object({
+  whale_address: z.string().min(10),
+  subscriber_address: z.string().min(10),
+  max_copy_amount_xrp: z.number().positive(),
+  wallet_address: z.string().optional(),
+});
+
+export function registerCopyTrader(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── FREE: copytrader_status ────────────────────────────────────────────────
+  server.tool(
+    'copytrader_status',
+    {},
+    async () => {
+      try {
+        const data = await CopyTraderAPI.status();
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── FREE: copytrader_whales ────────────────────────────────────────────────
+  server.tool(
+    'copytrader_whales',
+    {},
+    async () => {
+      if (!RateLimiter.getInstance().checkTool('copytrader_whales')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await CopyTraderAPI.whales();
+        audit.info('copytrader_whales', {});
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── PAID: copytrader_subscribe (0.05 USDC) ────────────────────────────────
+  server.tool(
+    'copytrader_subscribe',
+    {
+      whale_address: z.string().describe('XRPL address of the whale to copy.'),
+      subscriber_address: z.string().describe('Your XRPL address that will mirror trades.'),
+      max_copy_amount_xrp: z.number().describe('Maximum XRP to allocate per copied trade.'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(SubscribeSchema, rawArgs);
+
+      if (!RateLimiter.getInstance().checkTool('copytrader_subscribe')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+
+      await PriceRegistry.getInstance().seedDefaults();
+      const price = await PriceRegistry.getInstance().getPrice('copytrader_subscribe');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'copytrader_subscribe', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('copytrader_subscribe_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await CopyTraderAPI.subscribe({
+          whaleAddress: args.whale_address,
+          subscriberAddress: args.subscriber_address,
+          maxCopyAmountXrp: args.max_copy_amount_xrp,
+        });
+        audit.info('copytrader_subscribe_success', { receiptId: payment.receiptId });
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              data,
+              _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain, amount_paid: `${payment.amountPaid} ${payment.currency}`, timestamp: payment.timestamp },
+            }),
+          }],
+        };
+      } catch (err) {
+        audit.error('copytrader_subscribe_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+}

package/src/server/tools/crawl.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeX402Payment } from '../payments/x402.js';
+import { RateLimiter } from '../security/rate-limit.js';
+import { Sandbox } from '../security/sandbox.js';
+import { AuditLogger } from '../security/audit.js';
+import { CrawlClient } from '../../lib/sml-api/crawl.js';
+import { PriceRegistry } from '../registry/pricing.js';
+
+const InputSchema = z.object({
+  url: z.string().url(),
+  extract: z.enum(['text', 'links', 'tables', 'structured', 'all']).default('text'),
+  wallet_address: z.string().optional(),
+  user_agent: z.string().optional(),
+});
+
+export function registerCrawl(server: McpServer): void {
+  server.tool(
+    'crawl_paid_fetch',
+    {
+      url: z.string().describe('URL to fetch and parse. Must be http or https.'),
+      extract: z.enum(['text', 'links', 'tables', 'structured', 'all']).describe('What to extract. Default: text.'),
+      wallet_address: z.string().describe('Agent wallet for payment. Humans bypass automatically.'),
+      user_agent: z.string().describe('Custom user-agent string.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(InputSchema, rawArgs);
+      const audit = AuditLogger.getInstance();
+
+      // Validate URL safety
+      Sandbox.validateUrl(args.url);
+
+      if (!RateLimiter.getInstance().checkTool('crawl_paid_fetch')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+
+      await PriceRegistry.getInstance().seedDefaults();
+      const price = await PriceRegistry.getInstance().getPrice('crawl_paid_fetch');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({
+          price,
+          currency: 'USDC',
+          toolName: 'crawl_paid_fetch',
+          walletAddress: args.wallet_address,
+        });
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      const client = CrawlClient.getInstance();
+      const data = await client.fetch({ url: args.url, extract: args.extract ?? 'text', userAgent: args.user_agent });
+
+      // Sanitize response to prevent prompt injection
+      const safeContent = typeof data.content === 'string'
+        ? Sandbox.sanitizeApiResponse(data.content)
+        : data.content;
+
+      audit.info('crawl_success', { receiptId: payment.receiptId });
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ data: { ...data, content: safeContent }, _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain, amount_paid: `${payment.amountPaid} ${payment.currency}` } }) }],
+      };
+    },
+  );
+}