@scriptmasterlabs/mcp-x402 2.0.0

package/src/server/tools/launchpad.ts

@@ -0,0 +1,173 @@
+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 { LaunchpadAPI } from '../../lib/sml-api/launchpad.js';
+
+const CreateSchema = z.object({
+  name: z.string().min(1).max(64),
+  symbol: z.string().min(1).max(10).toUpperCase(),
+  description: z.string().max(512),
+  creator_address: z.string().min(10),
+  initial_supply: z.number().int().positive(),
+  target_liquidity_xrp: z.number().positive(),
+  wallet_address: z.string().optional(),
+});
+
+const BuySchema = z.object({
+  token_address: z.string().min(10),
+  buyer_address: z.string().min(10),
+  xrp_amount: z.number().positive(),
+  wallet_address: z.string().optional(),
+});
+
+export function registerLaunchpad(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── FREE: launchpad_status ─────────────────────────────────────────────────
+  server.tool(
+    'launchpad_status',
+    {},
+    async () => {
+      try {
+        const data = await LaunchpadAPI.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: launchpad_list ───────────────────────────────────────────────────
+  server.tool(
+    'launchpad_list',
+    {},
+    async () => {
+      if (!RateLimiter.getInstance().checkTool('launchpad_list')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await LaunchpadAPI.list();
+        audit.info('launchpad_list', {});
+        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: launchpad_create (0.10 USDC) ────────────────────────────────────
+  server.tool(
+    'launchpad_create',
+    {
+      name: z.string().describe('Token name (e.g. "Moon Rocket").'),
+      symbol: z.string().describe('Ticker symbol (e.g. MNRKT, max 10 chars).'),
+      description: z.string().describe('Token description (max 512 chars).'),
+      creator_address: z.string().describe('XRPL address of the token creator.'),
+      initial_supply: z.number().describe('Total token supply (integer).'),
+      target_liquidity_xrp: z.number().describe('XRP target to graduate from bonding curve to DEX.'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(CreateSchema, rawArgs);
+
+      if (!RateLimiter.getInstance().checkTool('launchpad_create')) {
+        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('launchpad_create');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'launchpad_create', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('launchpad_create_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await LaunchpadAPI.create({
+          name: args.name,
+          symbol: args.symbol,
+          description: args.description,
+          creatorAddress: args.creator_address,
+          initialSupply: args.initial_supply,
+          targetLiquidityXrp: args.target_liquidity_xrp,
+        });
+        audit.info('launchpad_create_success', { symbol: args.symbol, 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('launchpad_create_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── PAID: launchpad_buy (0.01 USDC) ───────────────────────────────────────
+  server.tool(
+    'launchpad_buy',
+    {
+      token_address: z.string().describe('Token contract/address on XRPL.'),
+      buyer_address: z.string().describe('XRPL address of the buyer.'),
+      xrp_amount: z.number().describe('Amount of XRP to spend on the bonding curve.'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(BuySchema, rawArgs);
+
+      if (!RateLimiter.getInstance().checkTool('launchpad_buy')) {
+        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('launchpad_buy');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'launchpad_buy', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('launchpad_buy_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await LaunchpadAPI.buy({
+          tokenAddress: args.token_address,
+          buyerAddress: args.buyer_address,
+          xrpAmount: args.xrp_amount,
+        });
+        audit.info('launchpad_buy_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('launchpad_buy_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+}

package/src/server/tools/leviathan.ts

@@ -0,0 +1,81 @@
+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 { LeviathanClient } from '../../lib/sml-api/leviathan.js';
+import { PriceRegistry } from '../registry/pricing.js';
+
+const InputSchema = z.object({
+  ticker: z.string().regex(/^[A-Z]{1,5}$/).optional(),
+  signal_type: z.enum(['squeeze', 'momentum', 'dark_pool', 'all']),
+  min_confidence: z.number().min(0).max(100).default(60),
+  wallet_address: z.string().optional(),
+});
+
+export function registerLeviathan(server: McpServer): void {
+  server.tool(
+    'leviathan_signal',
+    {
+      ticker: z.string().describe('Ticker symbol (e.g. TSLA, MSTR). Optional — omit for top signals.'),
+      signal_type: z.enum(['squeeze', 'momentum', 'dark_pool', 'all']).describe('Signal category.'),
+      min_confidence: z.number().describe('Minimum confidence score 0-100. Default: 60.'),
+      wallet_address: z.string().describe('Agent wallet address for payment. Auto-provisioned if omitted.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(InputSchema, rawArgs);
+      const audit = AuditLogger.getInstance();
+
+      if (!RateLimiter.getInstance().checkTool('leviathan_signal')) {
+        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('leviathan_signal');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable', message: 'Cannot determine price. Try again shortly.' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({
+          price,
+          currency: 'USDC',
+          toolName: 'leviathan_signal',
+          walletAddress: args.wallet_address,
+        });
+      } catch (err) {
+        audit.warn('leviathan_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      const client = LeviathanClient.getInstance();
+      const data = await client.getSignal({
+        ticker: args.ticker,
+        signalType: args.signal_type,
+        minConfidence: args.min_confidence ?? 60,
+      });
+
+      audit.info('leviathan_success', { ticker: args.ticker ?? 'all', 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,
+              },
+            }),
+          },
+        ],
+      };
+    },
+  );
+}

package/src/server/tools/nexus.ts

@@ -0,0 +1,76 @@
+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 { NexusClient } from '../../lib/sml-api/nexus.js';
+
+const InputSchema = z.object({
+  capability: z.string().min(1).max(200),
+  max_budget: z.string().regex(/^\d+(\.\d+)?$/),
+  chain_preference: z.enum(['base', 'xrpl', 'solana']).optional(),
+  action: z.enum(['query', 'hire']).default('query'),
+  agent_id: z.string().optional(),
+  wallet_address: z.string().optional(),
+});
+
+const COMMISSION_RATE = 0.05;
+
+export function registerNexus(server: McpServer): void {
+  server.tool(
+    'nexus_agent_hire',
+    {
+      capability: z.string().describe('Capability or skill to search for (e.g. "options flow analysis").'),
+      max_budget: z.string().describe('Max budget in USDC for hire (e.g. "1.00").'),
+      chain_preference: z.enum(['base', 'xrpl', 'solana']).describe('Preferred payment chain.'),
+      action: z.enum(['query', 'hire']).describe('"query" is free. "hire" charges 5% commission on agent fee.'),
+      agent_id: z.string().describe('Agent ID to hire (required for action=hire).'),
+      wallet_address: z.string().describe('Agent wallet for payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(InputSchema, rawArgs);
+      const audit = AuditLogger.getInstance();
+
+      if (!RateLimiter.getInstance().checkTool('nexus_agent_hire')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded' }) }], isError: true };
+      }
+
+      const client = NexusClient.getInstance();
+
+      // Free query tier
+      if (args.action === 'query') {
+        const results = await client.queryAgents({ capability: args.capability, maxBudget: args.max_budget });
+        audit.info('nexus_query_success', { capability: args.capability });
+        return { content: [{ type: 'text', text: JSON.stringify({ data: results, tier: 'free' }) }] };
+      }
+
+      // Hire — commission-based payment
+      if (!args.agent_id) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'agent_id_required', message: 'Specify agent_id to hire.' }) }], isError: true };
+      }
+
+      const agentFee = parseFloat(args.max_budget);
+      const commission = (agentFee * COMMISSION_RATE).toFixed(4);
+
+      let payment;
+      try {
+        payment = await executeX402Payment({
+          price: commission,
+          currency: 'USDC',
+          toolName: 'nexus_agent_hire',
+          walletAddress: args.wallet_address,
+        });
+      } catch (err) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      const hireResult = await client.hireAgent({ agentId: args.agent_id, budget: args.max_budget, chainPreference: args.chain_preference });
+
+      audit.info('nexus_hire_success', { agentId: args.agent_id, commission, receiptId: payment.receiptId });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ data: hireResult, commission: `${commission} USDC (5%)`, _meta: { receipt_id: payment.receiptId, tx_hash: payment.txHash, chain: payment.chain } }) }],
+      };
+    },
+  );
+}

package/src/server/tools/proof402.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RateLimiter } from '../security/rate-limit.js';
+import { Sandbox } from '../security/sandbox.js';
+import { AuditLogger } from '../security/audit.js';
+import { Proof402API } from '../../lib/sml-api/proof402.js';
+
+const InvoiceSchema = z.object({
+  endpoint_id: z.string().uuid(),
+});
+
+const VerifySchema = z.object({
+  tx_hash: z.string().min(10),
+  endpoint_id: z.string().uuid(),
+});
+
+const CreditSchema = z.object({
+  wallet_address: z.string().min(10),
+});
+
+export function registerProof402(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── FREE: proof_invoice ────────────────────────────────────────────────────
+  server.tool(
+    'proof_invoice',
+    {
+      endpoint_id: z.string().describe('UUID of the premium endpoint to get a payment invoice for.'),
+    },
+    async (rawArgs) => {
+      const { endpoint_id } = Sandbox.validate(InvoiceSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('proof_invoice')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await Proof402API.invoice(endpoint_id);
+        audit.info('proof_invoice', { endpoint_id });
+        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: proof_verify ─────────────────────────────────────────────────────
+  server.tool(
+    'proof_verify',
+    {
+      tx_hash: z.string().describe('XRPL transaction hash to verify.'),
+      endpoint_id: z.string().describe('UUID of the endpoint the payment was for.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(VerifySchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('proof_verify')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await Proof402API.verify(args.tx_hash, args.endpoint_id);
+        audit.info('proof_verify', { tx_hash: args.tx_hash });
+        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: proof_credit_score ───────────────────────────────────────────────
+  server.tool(
+    'proof_credit_score',
+    {
+      wallet_address: z.string().describe('Agent wallet address to look up credit score for (300-850 scale).'),
+    },
+    async (rawArgs) => {
+      const { wallet_address } = Sandbox.validate(CreditSchema, rawArgs);
+      if (!RateLimiter.getInstance().checkTool('proof_credit_score')) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'rate_limit_exceeded', retry_after: 60 }) }], isError: true };
+      }
+      try {
+        const data = await Proof402API.creditScore(wallet_address);
+        audit.info('proof_credit_score', { 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 };
+      }
+    },
+  );
+}

package/src/server/tools/rails.ts

@@ -0,0 +1,92 @@
+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 { RailsAPI } from '../../lib/sml-api/rails.js';
+
+const TransferSchema = z.object({
+  from_address: z.string().min(10),
+  to_address: z.string().min(10),
+  amount: z.string().min(1),
+  currency: z.enum(['RLUSD', 'XRP']),
+  memo: z.string().max(256).optional(),
+  wallet_address: z.string().optional(),
+});
+
+export function registerRails(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── FREE: rails_status ────────────────────────────────────────────────────
+  server.tool(
+    'rails_status',
+    {},
+    async () => {
+      try {
+        const data = await RailsAPI.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 };
+      }
+    },
+  );
+
+  // ── PAID: rails_transfer (0.01 USDC) ──────────────────────────────────────
+  server.tool(
+    'rails_transfer',
+    {
+      from_address: z.string().describe('Sender XRPL address.'),
+      to_address: z.string().describe('Recipient XRPL or Xahau address.'),
+      amount: z.string().describe('Amount to transfer (as string to preserve precision).'),
+      currency: z.enum(['RLUSD', 'XRP']).describe('Token to transfer.'),
+      memo: z.string().describe('Optional transfer memo (max 256 chars).'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(TransferSchema, rawArgs);
+
+      if (!RateLimiter.getInstance().checkTool('rails_transfer')) {
+        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('rails_transfer');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'rails_transfer', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('rails_transfer_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await RailsAPI.transfer({
+          fromAddress: args.from_address,
+          toAddress: args.to_address,
+          amount: args.amount,
+          currency: args.currency,
+          memo: args.memo,
+        });
+        audit.info('rails_transfer_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('rails_transfer_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+}

package/src/server/tools/shadow.ts

@@ -0,0 +1,128 @@
+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 { ShadowDeskAPI } from '../../lib/sml-api/shadow.js';
+
+const QuerySchema = z.object({
+  query: z.string().min(1).max(2048),
+  context: z.string().max(1024).optional(),
+  wallet_address: z.string().optional(),
+});
+
+const IngestSchema = z.object({
+  source: z.string().min(1).max(256),
+  payload: z.record(z.unknown()),
+  wallet_address: z.string().optional(),
+});
+
+export function registerShadow(server: McpServer): void {
+  const audit = AuditLogger.getInstance();
+
+  // ── PAID: shadow_query (0.02 USDC) ────────────────────────────────────────
+  server.tool(
+    'shadow_query',
+    {
+      query: z.string().describe('Natural language query for signal intelligence (max 2048 chars).'),
+      context: z.string().describe('Optional context to refine the query (max 1024 chars).'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(QuerySchema, rawArgs);
+
+      if (!RateLimiter.getInstance().checkTool('shadow_query')) {
+        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('shadow_query');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'shadow_query', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('shadow_query_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await ShadowDeskAPI.query({
+          query: args.query,
+          context: args.context,
+          walletAddress: args.wallet_address ?? payment.walletAddress ?? 'anonymous',
+        });
+        audit.info('shadow_query_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('shadow_query_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+
+  // ── PAID: shadow_ingest (0.01 USDC) ───────────────────────────────────────
+  server.tool(
+    'shadow_ingest',
+    {
+      source: z.string().describe('Source identifier for the data being ingested (e.g. "discord", "twitter", "on-chain").'),
+      payload: z.record(z.unknown()).describe('Signal data payload as a JSON object.'),
+      wallet_address: z.string().describe('Agent wallet for x402 payment.'),
+    },
+    async (rawArgs) => {
+      const args = Sandbox.validate(IngestSchema, rawArgs);
+
+      if (!RateLimiter.getInstance().checkTool('shadow_ingest')) {
+        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('shadow_ingest');
+      if (!price) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'price_unavailable' }) }], isError: true };
+      }
+
+      let payment;
+      try {
+        payment = await executeX402Payment({ price, currency: 'USDC', toolName: 'shadow_ingest', walletAddress: args.wallet_address });
+      } catch (err) {
+        audit.warn('shadow_ingest_payment_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'payment_failed', message: String(err) }) }], isError: true };
+      }
+
+      try {
+        const data = await ShadowDeskAPI.ingest({
+          source: args.source,
+          payload: args.payload,
+          walletAddress: args.wallet_address ?? payment.walletAddress ?? 'anonymous',
+        });
+        audit.info('shadow_ingest_success', { source: args.source, 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('shadow_ingest_api_fail', { error: String(err) });
+        return { content: [{ type: 'text', text: JSON.stringify({ error: 'api_error', message: String(err) }) }], isError: true };
+      }
+    },
+  );
+}