TypeScript SDK Reference

import { ContextClient } from "@ctxprotocol/sdk";

const client = new ContextClient({
  apiKey: "sk_live_...",
});

const answer = await client.query.run({
  query: "What are the top whale movements on Base?",
  responseShape: "answer_with_evidence",
});

console.log(answer.response);
console.log(answer.summary);
console.log(answer.evidence?.facts);

const executeTools = await client.discovery.search({
  query: "gas prices",
  mode: "execute",
  surface: "execute",
  requireExecutePricing: true,
});

const method = executeTools[0]?.mcpTools?.[0];
if (!method) throw new Error("No execute method available");

const session = await client.tools.startSession({ maxSpendUsd: "1.00" });
const result = await client.tools.execute({
  toolId: executeTools[0].id,
  toolName: method.name,
  args: { chainId: 1 },
  sessionId: session.session.sessionId ?? undefined,
});
console.log(result.result);
console.log(result.session); // methodPrice, spent, remaining, maxSpend, status...

// Production
const client = new ContextClient({
  apiKey: process.env.CONTEXT_API_KEY!,
});

// Local development
const client = new ContextClient({
  apiKey: "sk_test_...",
  baseUrl: "http://localhost:3000",
});

const tools = await client.discovery.search("ethereum gas", 10);

const executeTools = await client.discovery.search({
  query: "ethereum gas",
  mode: "execute",
  surface: "execute",
  requireExecutePricing: true,
});

const favoriteOnlyTools = await client.discovery.search({
  query: "crypto",
  favoritesOnly: true,
});

const featured = await client.discovery.getFeatured(5);
const featuredExecute = await client.discovery.getFeatured(5, {
  mode: "execute",
  requireExecutePricing: true,
});

const tool = await client.discovery.get("uuid-of-tool");
console.log(tool.name);
console.log(tool.mcpTools);

const session = await client.tools.startSession({ maxSpendUsd: "2.50" });

const result = await client.tools.execute({
  toolId: "uuid-of-tool",
  toolName: "get_gas_prices",
  args: { chainId: 1 },
  idempotencyKey: crypto.randomUUID(),
  sessionId: session.session.sessionId ?? undefined,
});

console.log(result.method.executePriceUsd); // explicit method price
console.log(result.session); // { methodPrice, spent, remaining, maxSpend, ... }

const started = await client.tools.startSession({ maxSpendUsd: "5.00" });
console.log(started.session.sessionId);
console.log(started.session.maxSpend);

const status = await client.tools.getSession("sess_123");
console.log(status.session.status); // open | closed | expired
console.log(status.session.spent);

const closed = await client.tools.closeSession("sess_123");
console.log(closed.session.status); // closed

const updated = await client.developer.updateTool("uuid-of-tool", {
  description: "Updated coverage and data freshness notes.",
  suggestedPrompts: ["Which Base wallets had the largest inflows today?"],
});

console.log(updated.tool);

const answer = await client.query.run("What are the top whale movements on Base?");
console.log(answer.response);     // response text or summary
console.log(answer.toolsUsed);    // [{ id, name, skillCalls }]
console.log(answer.cost);         // { modelCostUsd, toolCostUsd, totalCostUsd }
// `orchestrationMetrics` and `developerTrace` are only populated when
// `includeDeveloperTrace: true` is passed — see the next example.

const answer = await client.query.run({
  query: "Analyze whale activity on Base",
  favoritesOnly: true,
  agentModelId: "kimi-k2.6-model",
  responseShape: "answer_with_evidence",
  includeData: true,
  includeDataUrl: true,
  includeDeveloperTrace: true,
  idempotencyKey: crypto.randomUUID(),
});

console.log(answer.responseShape); // "answer_with_evidence"
console.log(answer.summary); // short machine-friendly summary
console.log(answer.evidence?.facts); // canonical evidence facts
console.log(answer.artifacts?.dataUrl); // artifact refs used by the answer package
console.log(answer.freshness?.asOf); // freshness metadata
console.log(answer.confidence?.level); // high | medium | low
console.log(answer.developerTrace?.summary); // retries/fallbacks/loops summary
console.log(answer.developerTrace?.diagnostics?.selection); // internal runtime policy diagnostics
console.log(answer.orchestrationMetrics); // first-pass / capability-miss / rediscovery metrics (gated on includeDeveloperTrace)

const result = await client.query.run({
  query: "Which exchanges are seeing the largest BTC inflows and outflows over the last 24 hours?",
  responseShape: "evidence_only",
});

console.log(result.response); // machine-friendly summary for evidence_only
console.log(result.summary);
console.log(result.evidence?.sourceRefs);
console.log(result.evidence?.marketIntelligence?.venueBreakdown);
console.log(result.stopReason, result.issueClass, result.actionsTaken);
console.log(result.usage?.toolsUsed);

const first = await client.query.run({
  query: "Find the biggest Base whale movements today",
  includeDeveloperTrace: true,
});

const handle = first.querySession;
if (handle) {
  const resumed = await client.query.run({
    query: "Focus only on wallets with exchange interactions",
    resumeFrom: {
      sessionId: handle.sessionId,
      attemptId: handle.attemptId,
    },
  });

  const forked = await client.query.run({
    query: "Try the same question with stricter evidence requirements",
    forkFrom: {
      sessionId: handle.sessionId,
      attemptId: handle.attemptId,
      reason: "manual_fork",
    },
  });

  console.log(resumed.response);
  console.log(forked.response);
}

for await (const event of client.query.stream({
  query: "What are the top whale movements?",
})) {
  switch (event.type) {
    case "tool-status":
      console.log(`Tool ${event.tool.name}: ${event.status}`);
      break;
    case "text-delta":
      process.stdout.write(event.delta);
      break;
    case "done":
      console.log("\nTotal cost:", event.result.cost.totalCostUsd);
      break;
  }
}

const job = await client.query.start({
  query: "Build a chart-ready dataset of Base whale movements over the last 30 days",
  responseShape: "evidence_only",
  includeDataUrl: true,
});

const status = await client.query.getStatus(job.jobId);
console.log(status.status); // queued | running | completed | failed

const completed = await client.query.poll(job.jobId, {
  intervalMs: 2000,
  timeoutMs: 15 * 60_000,
});
console.log(completed.result);

import {
  // Auth utilities for tool contributors
  verifyContextRequest,
  isProtectedMcpMethod,
  isOpenMcpMethod,
} from "@ctxprotocol/sdk";

import type {
  // Client types
  ContextClientOptions,
  Tool,
  McpTool,
  McpToolMeta,
  McpToolRateLimitHints,
  ExecuteOptions,
  ExecutionResult,
  QueryOptions,
  QueryResult,
  QueryDeveloperTrace,
  QueryOrchestrationMetrics,
  QueryResponseEnvelope,
  QueryComputedArtifact,
  QueryCapabilityMissPayload,
  QueryAssumptionMetadata,
  ContextErrorCode,
  // Auth types (for MCP server contributors)
  VerifyRequestOptions,
  // Context types (for MCP server contributors receiving injected data)
  ContextRequirementType,
  HyperliquidContext,
  PolymarketContext,
  WalletContext,
  UserContext,
} from "@ctxprotocol/sdk";

interface Tool {
  id: string;
  name: string;
  description: string;
  price: string; // Listing-level response price metadata (legacy field name)
  category?: string;
  isVerified?: boolean;
  mcpTools?: McpTool[];
}

interface McpTool {
  name: string;
  description: string;
  inputSchema?: Record<string, unknown>;   // JSON Schema for arguments
  outputSchema?: Record<string, unknown>;  // JSON Schema for response
  _meta?: McpToolMeta;                     // mode/eligibility/pricing/context metadata
  executeEligible?: boolean;               // derived discovery field
  executePriceUsd?: string | null;         // explicit execute price visibility
}

interface McpToolRateLimitHints {
  maxRequestsPerMinute?: number;
  maxConcurrency?: number;
  cooldownMs?: number;
  supportsBulk?: boolean;
  recommendedBatchTools?: string[];
  notes?: string;
}

interface McpToolMeta {
  surface?: "answer" | "execute" | "both";
  queryEligible?: boolean;
  latencyClass?: "instant" | "fast" | "slow" | "streaming";
  pricing?: {
    executeUsd?: string; // required for execute eligibility
    queryUsd?: string;   // optional metadata only in this rollout
  };
  executeEligible?: boolean;
  executePriceUsd?: string;
  contextRequirements?: ContextRequirementType[];
  rateLimit?: McpToolRateLimitHints;
  rateLimitHints?: McpToolRateLimitHints;
}

const TOOLS = [{
  name: "get_price_history",
  inputSchema: {
    type: "object",
    properties: {
      symbol: { type: "string", default: "BTC", examples: ["BTC", "ETH", "SOL"] },
      interval: { type: "string", enum: ["1h", "4h", "1d"], default: "1h", examples: ["1h", "4h"] },
      limit: { type: "number", default: 100, examples: [50, 100, 200] },
    },
    required: [],
  },
}];

interface ExecutionResult<T = unknown> {
  mode: "execute";
  result: T;
  tool: { id: string; name: string };
  method: { name: string; executePriceUsd: string };
  session: ExecuteSessionSpend;
  durationMs: number;
}

interface ExecuteSessionSpend {
  mode: "execute";
  sessionId: string | null;
  methodPrice: string;
  spent: string;
  remaining: string | null;
  maxSpend: string | null;
  status?: "open" | "closed" | "expired";
  expiresAt?: string;
  closeRequested?: boolean;
  pendingAccruedCount?: number;
  pendingAccruedUsd?: string;
}

interface QueryResult {
  response: string;                     // prose answer or machine-friendly summary
  toolsUsed: QueryToolUsage[];          // [{ id, name, skillCalls }]
  cost: QueryCost;                      // { modelCostUsd, toolCostUsd, totalCostUsd }
  durationMs: number;
  data?: unknown;                       // Bounded data/preview when includeData=true
  dataUrl?: string;                     // Optional blob URL (includeDataUrl=true)
  computedArtifacts?: QueryComputedArtifact[]; // Charts/dataframes computed by code_interpreter
  developerTrace?: QueryDeveloperTrace; // Optional runtime trace + diagnostics
  orchestrationMetrics?: QueryOrchestrationMetrics; // Optional first-pass metrics
  responseShape?: "answer_with_evidence" | "evidence_only";
  summary?: string;
  evidence?: QueryResponseEnvelope["evidence"];
  artifacts?: QueryResponseEnvelope["artifacts"];   // Provenance: source refs + dataset handles
  view?: QueryResponseEnvelope["view"];
  freshness?: QueryResponseEnvelope["freshness"];
  confidence?: QueryResponseEnvelope["confidence"];
  usage?: QueryResponseEnvelope["usage"];
  outcomeType: "answer" | "capability_miss";
  capabilityMiss?: QueryCapabilityMissPayload;
  assumptionMade?: QueryAssumptionMetadata;
}

import type { ContextRequirementType } from "@ctxprotocol/sdk";

/** Context types supported by the marketplace */
type ContextRequirementType = "polymarket" | "hyperliquid" | "wallet";

// Usage: Declare context requirements in _meta at the tool level (MCP spec)
const TOOLS = [{
  name: "analyze_my_positions",
  description: "Analyze your positions with personalized insights",

  // REQUIRED: Context requirements in _meta (MCP spec for arbitrary metadata)
  // The Context platform reads this to inject user data + pacing hints
  _meta: {
    contextRequirements: ["hyperliquid"] as ContextRequirementType[],
    rateLimit: {
      maxRequestsPerMinute: 30,
      cooldownMs: 2000,
      maxConcurrency: 1,
      supportsBulk: true,
      recommendedBatchTools: ["get_portfolio_snapshot"],
      notes: "Hobby tier: use snapshot methods before per-asset loops.",
    },
  },

  inputSchema: {
    type: "object",
    properties: {
      portfolio: { 
        type: "object",
        description: "Portfolio context (injected by platform)",
      },
    },
    required: ["portfolio"],
  },
  outputSchema: { /* ... */ },
}];

interface HyperliquidContext {
  walletAddress: string;
  perpPositions: HyperliquidPerpPosition[];
  spotBalances: HyperliquidSpotBalance[];
  openOrders: HyperliquidOrder[];
  accountSummary: HyperliquidAccountSummary;
  fetchedAt: string;
}

interface PolymarketContext {
  walletAddress: string;
  positions: PolymarketPosition[];
  openOrders: PolymarketOrder[];
  totalValue?: number;
  fetchedAt: string;
}

interface WalletContext {
  address: string;
  chainId: number;
  nativeBalance?: string;
}

interface ERC20TokenBalance {
  address: string;
  symbol: string;
  decimals: number;
  balance: string;
}

interface ERC20Context {
  tokens: ERC20TokenBalance[];
}

import {
  buildContributorSearchValidationArtifact,
  createSearchIntent,
  extractContributorSearchesFromDeveloperTrace,
  mergeContributorSearchConfig,
  resolveContributorSearch,
} from "@ctxprotocol/sdk/contrib/search";

import { ContextError } from "@ctxprotocol/sdk";

try {
  const result = await client.tools.execute({ ... });
} catch (error) {
  if (error instanceof ContextError) {
    switch (error.code) {
      case "no_wallet":
        // User needs to set up wallet
        console.log("Setup required:", error.helpUrl);
        break;
      case "insufficient_allowance":
        // User needs to set a spending cap
        console.log("Set spending cap:", error.helpUrl);
        break;
      case "payment_failed":
        // Insufficient USDC balance
        break;
      case "execution_failed":
        // Tool execution error
        break;
    }
  }
}

import express from "express";
import { createContextMiddleware } from "@ctxprotocol/sdk";

const app = express();
app.use(express.json());

// 1 line of code to secure your endpoint
app.use("/mcp", createContextMiddleware());

app.post("/mcp", (req, res) => {
  // req.context contains verified JWT payload (on protected methods)
  // Handle MCP request...
});

import { 
  verifyContextRequest, 
  isProtectedMcpMethod, 
  ContextError 
} from "@ctxprotocol/sdk";

// Check if a method requires auth
if (isProtectedMcpMethod(body.method)) {
  const payload = await verifyContextRequest({
    authorizationHeader: req.headers.authorization,
    audience: "https://your-tool.com/mcp", // optional
  });
  // payload contains verified JWT claims
}