@scriptmasterlabs/mcp-x402 2.0.0

package/src/lib/sml-api/copytrader.ts

@@ -0,0 +1,33 @@
+const COPYTRADER_BASE = process.env['SML_COPYTRADER_URL'] ?? 'https://sml-copytrader.onrender.com';
+
+async function ctGet(path: string): Promise<unknown> {
+  const res = await fetch(`${COPYTRADER_BASE}${path}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`CopyTrader GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export interface CopyTraderSubscribeParams {
+  whaleAddress: string;
+  subscriberAddress: string;
+  maxCopyAmountXrp: number;
+}
+
+async function ctPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${COPYTRADER_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`CopyTrader POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const CopyTraderAPI = {
+  status: () => ctGet('/status'),
+  whales: () => ctGet('/whales'),
+  subscribe: (params: CopyTraderSubscribeParams) => ctPost('/subscribe', params),
+};

package/src/lib/sml-api/crawl.ts

@@ -0,0 +1,44 @@
+export interface CrawlParams {
+  url: string;
+  extract: 'text' | 'links' | 'tables' | 'structured' | 'all';
+  userAgent?: string;
+}
+
+export interface CrawlResult {
+  url: string;
+  content: string | unknown;
+  status_code: number;
+  content_type: string;
+  fetched_at: string;
+}
+
+export class CrawlClient {
+  private static instance: CrawlClient;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): CrawlClient {
+    if (!CrawlClient.instance) {
+      CrawlClient.instance = new CrawlClient();
+    }
+    return CrawlClient.instance;
+  }
+
+  async fetch(params: CrawlParams): Promise<CrawlResult> {
+    const res = await fetch(`${this.baseUrl}/crawl/v1/fetch`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(params.userAgent ? { 'X-Crawl-User-Agent': params.userAgent } : {}),
+      },
+      body: JSON.stringify({ url: params.url, extract: params.extract }),
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!res.ok) throw new Error(`Crawl API error: HTTP ${res.status}`);
+    return res.json() as Promise<CrawlResult>;
+  }
+}

package/src/lib/sml-api/echo.ts

@@ -0,0 +1,28 @@
+// echo-forge — historical pattern similarity engine (Polygon.io + ML cosine similarity)
+// Status: NOT YET DEPLOYED. Returns informative stub response until service is live.
+
+export interface EchoPatternParams {
+  symbol: string;
+  lookbackDays: number;
+  topN?: number;
+  walletAddress: string;
+}
+
+export const EchoForgeAPI = {
+  patternMatch: async (params: EchoPatternParams): Promise<unknown> => {
+    // Service not yet deployed to Render — surface clear coming-soon message.
+    return {
+      status: 'coming_soon',
+      service: 'echo-forge',
+      message:
+        'echo-forge (historical pattern similarity engine) is not yet deployed. ' +
+        'It uses Polygon.io data + ML cosine similarity to find historical analogs. ' +
+        'Check https://github.com/Timwal78/echo-forge for status updates.',
+      params_received: {
+        symbol: params.symbol,
+        lookback_days: params.lookbackDays,
+        top_n: params.topN ?? 5,
+      },
+    };
+  },
+};

package/src/lib/sml-api/forge.ts

@@ -0,0 +1,33 @@
+const FORGE_BASE = process.env['FORGE_GATEWAY_URL'] ?? 'https://forge-gateway-a822.onrender.com';
+
+async function forgeGet(path: string): Promise<unknown> {
+  const res = await fetch(`${FORGE_BASE}${path}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`Forge Gateway GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export interface ForgeLLMParams {
+  model: string;
+  prompt: string;
+  maxTokens?: number;
+  walletAddress: string;
+}
+
+async function forgePost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${FORGE_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(60_000),
+  });
+  if (!res.ok) throw new Error(`Forge Gateway POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const ForgeGatewayAPI = {
+  status: () => forgeGet('/health'),
+  llm: (params: ForgeLLMParams) => forgePost('/v1/llm', params),
+};

package/src/lib/sml-api/ftd.ts

@@ -0,0 +1,53 @@
+export interface FtdAlertParams {
+  ticker?: string;
+  minSpikeMultiplier: number;
+}
+
+export interface FtdScanParams {
+  ticker?: string;
+  scanType: 'full' | 'spike_history';
+  minSpikeMultiplier: number;
+}
+
+export class FtdClient {
+  private static instance: FtdClient;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): FtdClient {
+    if (!FtdClient.instance) {
+      FtdClient.instance = new FtdClient();
+    }
+    return FtdClient.instance;
+  }
+
+  async getAlerts(params: FtdAlertParams): Promise<unknown> {
+    const qs = new URLSearchParams({ min_spike: String(params.minSpikeMultiplier) });
+    if (params.ticker) qs.set('ticker', params.ticker);
+
+    const res = await fetch(`${this.baseUrl}/ftd/v1/alerts?${qs.toString()}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) throw new Error(`FTD API error: HTTP ${res.status}`);
+    return res.json();
+  }
+
+  async getFullScan(params: FtdScanParams): Promise<unknown> {
+    const qs = new URLSearchParams({
+      scan_type: params.scanType,
+      min_spike: String(params.minSpikeMultiplier),
+    });
+    if (params.ticker) qs.set('ticker', params.ticker);
+
+    const res = await fetch(`${this.baseUrl}/ftd/v1/scan?${qs.toString()}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) throw new Error(`FTD API error: HTTP ${res.status}`);
+    return res.json();
+  }
+}

package/src/lib/sml-api/ghost.ts

@@ -0,0 +1,35 @@
+const GHOST_BASE = process.env['GHOST_LAYER_URL'] ?? 'https://ghost-layer.onrender.com';
+
+async function ghostGet(path: string): Promise<unknown> {
+  const res = await fetch(`${GHOST_BASE}${path}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`Ghost Layer GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export interface GhostRouteParams {
+  fromChain: 'xrpl' | 'base';
+  toChain: 'xrpl' | 'base';
+  amount: string;
+  currency: string;
+  destinationAddress: string;
+  walletAddress: string;
+}
+
+async function ghostPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${GHOST_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`Ghost Layer POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const GhostLayerAPI = {
+  status: () => ghostGet('/api/status'),
+  route: (params: GhostRouteParams) => ghostPost('/api/route', params),
+};

package/src/lib/sml-api/launchpad.ts

@@ -0,0 +1,43 @@
+const LAUNCHPAD_BASE = process.env['SML_LAUNCHPAD_URL'] ?? 'https://sml-launchpad.onrender.com';
+
+async function lpGet(path: string): Promise<unknown> {
+  const res = await fetch(`${LAUNCHPAD_BASE}${path}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`Launchpad GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export interface LaunchpadCreateParams {
+  name: string;
+  symbol: string;
+  description: string;
+  creatorAddress: string;
+  initialSupply: number;
+  targetLiquidityXrp: number;
+}
+
+export interface LaunchpadBuyParams {
+  tokenAddress: string;
+  buyerAddress: string;
+  xrpAmount: number;
+}
+
+async function lpPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${LAUNCHPAD_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!res.ok) throw new Error(`Launchpad POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const LaunchpadAPI = {
+  status: () => lpGet('/status'),
+  list: () => lpGet('/tokens'),
+  create: (params: LaunchpadCreateParams) => lpPost('/tokens', params),
+  buy: (params: LaunchpadBuyParams) => lpPost('/tokens/buy', params),
+};

package/src/lib/sml-api/leviathan.ts

@@ -0,0 +1,49 @@
+export interface LeviathanSignalParams {
+  ticker?: string;
+  signalType: 'squeeze' | 'momentum' | 'dark_pool' | 'all';
+  minConfidence: number;
+}
+
+export interface LeviathanSignal {
+  ticker: string;
+  signal_type: string;
+  confidence: number;
+  directive: string;
+  regime: string;
+  timestamp: string;
+  source: string;
+}
+
+export class LeviathanClient {
+  private static instance: LeviathanClient;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): LeviathanClient {
+    if (!LeviathanClient.instance) {
+      LeviathanClient.instance = new LeviathanClient();
+    }
+    return LeviathanClient.instance;
+  }
+
+  async getSignal(params: LeviathanSignalParams): Promise<LeviathanSignal[]> {
+    const qs = new URLSearchParams({
+      signal_type: params.signalType,
+      min_confidence: String(params.minConfidence),
+    });
+    if (params.ticker) qs.set('ticker', params.ticker);
+
+    const res = await fetch(`${this.baseUrl}/leviathan/v1/signal?${qs.toString()}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Leviathan API error: HTTP ${res.status}`);
+    }
+
+    return (await res.json()) as LeviathanSignal[];
+  }
+}

package/src/lib/sml-api/nexus.ts

@@ -0,0 +1,50 @@
+export interface NexusQueryParams {
+  capability: string;
+  maxBudget: string;
+}
+
+export interface NexusHireParams {
+  agentId: string;
+  budget: string;
+  chainPreference?: string;
+}
+
+export class NexusClient {
+  private static instance: NexusClient;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): NexusClient {
+    if (!NexusClient.instance) {
+      NexusClient.instance = new NexusClient();
+    }
+    return NexusClient.instance;
+  }
+
+  async queryAgents(params: NexusQueryParams): Promise<unknown> {
+    const res = await fetch(`${this.baseUrl}/nexus/v1/agents`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ capability: params.capability, max_budget: params.maxBudget }),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) throw new Error(`Nexus API error: HTTP ${res.status}`);
+    return res.json();
+  }
+
+  async hireAgent(params: NexusHireParams): Promise<unknown> {
+    const res = await fetch(`${this.baseUrl}/nexus/v1/agents/${params.agentId}/hire`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ budget: params.budget, chain_preference: params.chainPreference }),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) throw new Error(`Nexus hire error: HTTP ${res.status}`);
+    return res.json();
+  }
+}

package/src/lib/sml-api/proof402.ts

@@ -0,0 +1,27 @@
+const PROOF402_BASE = process.env['PROOF402_SERVER_URL'] ?? 'https://four02proof.onrender.com';
+
+async function proofGet(path: string): Promise<unknown> {
+  const res = await fetch(`${PROOF402_BASE}${path}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`402Proof GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+async function proofPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${PROOF402_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`402Proof POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const Proof402API = {
+  invoice: (endpointId: string) => proofGet(`/v1/invoice/${encodeURIComponent(endpointId)}`),
+  verify: (txHash: string, endpointId: string) => proofPost('/v1/verify', { tx_hash: txHash, endpoint_id: endpointId }),
+  creditScore: (walletAddress: string) => proofGet(`/v1/credit/${encodeURIComponent(walletAddress)}`),
+};

package/src/lib/sml-api/rails.ts

@@ -0,0 +1,34 @@
+const RAILS_BASE = process.env['SML_RAILS_URL'] ?? 'https://sml-rails.onrender.com';
+
+async function railsGet(path: string): Promise<unknown> {
+  const res = await fetch(`${RAILS_BASE}${path}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`SML Rails GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export interface RailsTransferParams {
+  fromAddress: string;
+  toAddress: string;
+  amount: string;
+  currency: 'RLUSD' | 'XRP';
+  memo?: string;
+}
+
+async function railsPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${RAILS_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!res.ok) throw new Error(`SML Rails POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const RailsAPI = {
+  status: () => railsGet('/status'),
+  transfer: (params: RailsTransferParams) => railsPost('/transfer', params),
+};

package/src/lib/sml-api/shadow.ts

@@ -0,0 +1,35 @@
+const SHADOW_BASE = process.env['SHADOW_DESK_URL'] ?? 'https://shadow-desk.onrender.com';
+const SHADOW_ADMIN_KEY = process.env['SHADOW_ADMIN_API_KEY'] ?? '';
+
+async function shadowPost(path: string, body: unknown): Promise<unknown> {
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json',
+  };
+  if (SHADOW_ADMIN_KEY) headers['X-Admin-Key'] = SHADOW_ADMIN_KEY;
+  const res = await fetch(`${SHADOW_BASE}${path}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`Shadow Desk POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export interface ShadowQueryParams {
+  query: string;
+  context?: string;
+  walletAddress: string;
+}
+
+export interface ShadowIngestParams {
+  source: string;
+  payload: unknown;
+  walletAddress: string;
+}
+
+export const ShadowDeskAPI = {
+  query: (params: ShadowQueryParams) => shadowPost('/query', params),
+  ingest: (params: ShadowIngestParams) => shadowPost('/ingest', params),
+};

package/src/lib/sml-api/squeezeos.ts

@@ -0,0 +1,95 @@
+import { createHmac } from 'crypto';
+
+const SQUEEZEOS_BASE = process.env['SQUEEZEOS_BASE_URL'] ?? 'https://squeezeos-api.onrender.com';
+const PROOF402_SECRET = process.env['PROOF402_TOKEN_SECRET'] ?? '';
+
+// Endpoint UUIDs — override via env vars if they change
+const ENDPOINT_UUIDS: Record<string, string> = {
+  council: process.env['SQUEEZEOS_UUID_COUNCIL'] ?? '12a0e7a1-0000-0000-0000-000000000001',
+  scan: process.env['SQUEEZEOS_UUID_SCAN'] ?? '160cf28d-0000-0000-0000-000000000002',
+  options: process.env['SQUEEZEOS_UUID_OPTIONS'] ?? 'c951a374-0000-0000-0000-000000000003',
+  iwm: process.env['SQUEEZEOS_UUID_IWM'] ?? '60f48ce0-0000-0000-0000-000000000004',
+  marketplace_read: process.env['SQUEEZEOS_UUID_MARKETPLACE_READ'] ?? 'd1a2b3c4-0000-0000-0000-000000000005',
+};
+
+/**
+ * Generate a SqueezeOS JWT for a premium endpoint.
+ * Format: base64(json).HMAC-SHA256(secret, encoded)
+ */
+export function generateSqueezeOSToken(endpointKey: string, walletAddress: string): string {
+  const eid = ENDPOINT_UUIDS[endpointKey];
+  if (!eid) throw new Error(`Unknown SqueezeOS endpoint key: ${endpointKey}`);
+  if (!PROOF402_SECRET) throw new Error('PROOF402_TOKEN_SECRET is not set — cannot mint SqueezeOS JWT');
+
+  const payload = {
+    eid,
+    wlt: walletAddress,
+    iid: `mcp-x402-${Date.now()}`,
+    exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
+  };
+
+  const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const sig = createHmac('sha256', PROOF402_SECRET).update(encoded).digest('hex');
+  return `${encoded}.${sig}`;
+}
+
+async function squeezeGet(path: string, token?: string): Promise<unknown> {
+  const headers: Record<string, string> = { 'Accept': 'application/json' };
+  if (token) headers['X-Payment-Token'] = token;
+  const res = await fetch(`${SQUEEZEOS_BASE}${path}`, {
+    headers,
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`SqueezeOS GET ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+async function squeezePost(path: string, body: unknown, token?: string): Promise<unknown> {
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json',
+  };
+  if (token) headers['X-Payment-Token'] = token;
+  const res = await fetch(`${SQUEEZEOS_BASE}${path}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`SqueezeOS POST ${path}: HTTP ${res.status}`);
+  return res.json();
+}
+
+export const SqueezeOSAPI = {
+  // FREE
+  preview: (symbol: string) => squeezeGet(`/api/preview/${encodeURIComponent(symbol)}`),
+  history: (symbol?: string) => squeezeGet(symbol ? `/api/history/${encodeURIComponent(symbol)}` : '/api/history'),
+  oracle: (symbol?: string) => squeezeGet(symbol ? `/api/oracle/${encodeURIComponent(symbol)}` : '/api/oracle'),
+  ftd: () => squeezeGet('/api/ftd'),
+  status: () => squeezeGet('/api/status'),
+  demo: () => squeezeGet('/api/demo'),
+  marketplaceBrowse: () => squeezeGet('/api/marketplace'),
+  futuresLeaderboard: () => squeezeGet('/api/futures/leaderboard'),
+
+  // PAID — caller must supply walletAddress so we can mint the token
+  council: (symbol: string, walletAddress: string) => {
+    const token = generateSqueezeOSToken('council', walletAddress);
+    return squeezePost('/api/council', { symbol }, token);
+  },
+  scan: (walletAddress: string) => {
+    const token = generateSqueezeOSToken('scan', walletAddress);
+    return squeezeGet('/api/scan', token);
+  },
+  options: (walletAddress: string) => {
+    const token = generateSqueezeOSToken('options', walletAddress);
+    return squeezeGet('/api/options', token);
+  },
+  iwm: (walletAddress: string) => {
+    const token = generateSqueezeOSToken('iwm', walletAddress);
+    return squeezeGet('/api/iwm', token);
+  },
+  marketplaceRead: (listingId: string, walletAddress: string) => {
+    const token = generateSqueezeOSToken('marketplace_read', walletAddress);
+    return squeezePost('/api/marketplace/read', { listing_id: listingId }, token);
+  },
+};

package/src/lib/sml-api/xdeo.ts

@@ -0,0 +1,40 @@
+export interface XdeoEstimateParams {
+  ticker: string;
+  fiscalQuarter: string;
+  estimateType: 'eps' | 'revenue' | 'guidance' | 'all';
+}
+
+export class XdeoClient {
+  private static instance: XdeoClient;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): XdeoClient {
+    if (!XdeoClient.instance) {
+      XdeoClient.instance = new XdeoClient();
+    }
+    return XdeoClient.instance;
+  }
+
+  async getEstimate(params: XdeoEstimateParams): Promise<unknown> {
+    const res = await fetch(`${this.baseUrl}/xdeo/v1/estimate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        ticker: params.ticker,
+        fiscal_quarter: params.fiscalQuarter,
+        estimate_type: params.estimateType,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) {
+      throw new Error(`xDEO API error: HTTP ${res.status}`);
+    }
+
+    return res.json();
+  }
+}

package/src/lib/sml-api/xmit.ts

@@ -0,0 +1,40 @@
+export interface XmitDecodeParams {
+  filingUrl: string;
+  parseTarget: 'executive_pay' | 'holdings' | 'ownership_changes' | 'all';
+  format: 'json' | 'markdown';
+}
+
+export class XmitClient {
+  private static instance: XmitClient;
+  private readonly baseUrl: string;
+
+  private constructor() {
+    this.baseUrl = process.env['SML_API_BASE'] ?? 'https://api.scriptmasterlabs.com';
+  }
+
+  static getInstance(): XmitClient {
+    if (!XmitClient.instance) {
+      XmitClient.instance = new XmitClient();
+    }
+    return XmitClient.instance;
+  }
+
+  async decode(params: XmitDecodeParams): Promise<unknown> {
+    const res = await fetch(`${this.baseUrl}/xmit/v1/decode`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        filing_url: params.filingUrl,
+        parse_target: params.parseTarget,
+        format: params.format,
+      }),
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!res.ok) {
+      throw new Error(`xMIT API error: HTTP ${res.status}`);
+    }
+
+    return res.json();
+  }
+}