@ctxprotocol/sdk 0.1.3 → 0.4.0

package/dist/index.d.cts

@@ -1,277 +1,262 @@
+export { ContextClient, ContextClientOptions, ContextError, ContextErrorCode, Discovery, ExecuteApiErrorResponse, ExecuteApiResponse, ExecuteApiSuccessResponse, ExecuteOptions, ExecutionResult, McpTool, SearchOptions, SearchResponse, Tool, Tools } from './client/index.cjs';
+
 /**
- * Configuration options for initializing the ContextClient
+ * Wallet context types for portfolio tracking.
+ *
+ * These types represent wallet and token holdings that can be
+ * injected into MCP tools for personalized analysis.
+ *
+ * @packageDocumentation
  */
-interface ContextClientOptions {
-    /**
-     * Your Context Protocol API key
-     * @example "sk_live_abc123..."
-     */
-    apiKey: string;
-    /**
-     * Base URL for the Context Protocol API
-     * @default "https://ctxprotocol.com"
-     */
-    baseUrl?: string;
-}
 /**
- * An individual MCP tool exposed by a tool listing
+ * Base wallet context - address and chain info
  */
-interface McpTool {
-    /** Name of the MCP tool method */
-    name: string;
-    /** Description of what this method does */
-    description: string;
-    /**
-     * JSON Schema for the input arguments this tool accepts.
-     * Used by LLMs to generate correct arguments.
-     */
-    inputSchema?: Record<string, unknown>;
-    /**
-     * JSON Schema for the output this tool returns.
-     * Used by LLMs to understand the response structure.
-     */
-    outputSchema?: Record<string, unknown>;
+interface WalletContext {
+    /** Wallet address (checksummed) */
+    address: string;
+    /** Chain ID (137 for Polygon, 1 for Ethereum, etc.) */
+    chainId: number;
+    /** Native token balance in wei (string for precision) */
+    nativeBalance?: string;
 }
 /**
- * Represents a tool available on the Context Protocol marketplace
+ * ERC20 token holdings
  */
-interface Tool {
-    /** Unique identifier for the tool (UUID) */
-    id: string;
-    /** Human-readable name of the tool */
-    name: string;
-    /** Description of what the tool does */
-    description: string;
-    /** Price per execution in USDC */
-    price: string;
-    /** Tool category (e.g., "defi", "nft") */
-    category?: string;
-    /** Whether the tool is verified by Context Protocol */
-    isVerified?: boolean;
-    /**
-     * Available MCP tool methods
-     * Use items from this array as `toolName` when executing
-     */
-    mcpTools?: McpTool[];
-    /** Creation timestamp */
-    createdAt?: string;
-    /** Last update timestamp */
-    updatedAt?: string;
+interface ERC20TokenBalance {
+    /** Token contract address */
+    address: string;
+    /** Token symbol (e.g., "USDC") */
+    symbol: string;
+    /** Token decimals */
+    decimals: number;
+    /** Balance in smallest unit (string for precision) */
+    balance: string;
 }
 /**
- * Response from the tools search endpoint
+ * Collection of ERC20 token balances
  */
-interface SearchResponse {
-    /** Array of matching tools */
-    tools: Tool[];
-    /** The search query that was used */
-    query: string;
-    /** Total number of results */
-    count: number;
+interface ERC20Context {
+    /** Array of token balances */
+    tokens: ERC20TokenBalance[];
 }
+
 /**
- * Options for searching tools
+ * Polymarket context types for portfolio tracking.
+ *
+ * These types represent Polymarket positions and orders that can be
+ * injected into MCP tools for personalized portfolio analysis.
+ *
+ * @packageDocumentation
  */
-interface SearchOptions {
-    /** Search query (semantic search) */
-    query?: string;
-    /** Maximum number of results (1-50, default 10) */
-    limit?: number;
-}
 /**
- * Options for executing a tool
+ * A single Polymarket position
  */
-interface ExecuteOptions {
-    /** The UUID of the tool to execute (from search results) */
-    toolId: string;
-    /** The specific MCP tool name to call (from tool's mcpTools array) */
-    toolName: string;
-    /** Arguments to pass to the tool */
-    args?: Record<string, unknown>;
+interface PolymarketPosition {
+    /** The market's condition ID */
+    conditionId: string;
+    /** The specific outcome token ID */
+    tokenId: string;
+    /** Which outcome this position is for */
+    outcome: "YES" | "NO";
+    /** Number of shares held */
+    shares: number;
+    /** Average entry price (0-1 scale) */
+    avgEntryPrice: number;
+    /** Market question/title for display */
+    marketTitle?: string;
 }
 /**
- * Successful execution response from the API
+ * An open order on Polymarket
  */
-interface ExecuteApiSuccessResponse {
-    success: true;
-    /** The result data from the tool execution */
-    result: unknown;
-    /** Information about the executed tool */
-    tool: {
-        id: string;
-        name: string;
-    };
-    /** Execution duration in milliseconds */
-    durationMs: number;
+interface PolymarketOrder {
+    /** Order ID */
+    orderId: string;
+    /** The market's condition ID */
+    conditionId: string;
+    /** Order side */
+    side: "BUY" | "SELL";
+    /** Which outcome this order is for */
+    outcome: "YES" | "NO";
+    /** Limit price (0-1 scale) */
+    price: number;
+    /** Order size in shares */
+    size: number;
+    /** Amount already filled */
+    filled: number;
 }
 /**
- * Error response from the API
+ * Complete Polymarket portfolio context.
+ * This is what gets passed to MCP tools for personalized analysis.
  */
-interface ExecuteApiErrorResponse {
-    /** Human-readable error message */
-    error: string;
-    /** Error code for programmatic handling */
-    code?: ContextErrorCode;
-    /** URL to help resolve the issue */
-    helpUrl?: string;
+interface PolymarketContext {
+    /** The wallet address this context is for */
+    walletAddress: string;
+    /** All open positions */
+    positions: PolymarketPosition[];
+    /** All open orders */
+    openOrders: PolymarketOrder[];
+    /** Total portfolio value in USD (sum of position values) */
+    totalValue?: number;
+    /** When this context was fetched (ISO 8601 string) */
+    fetchedAt: string;
 }
+
 /**
- * Raw API response from the execute endpoint
+ * Hyperliquid context types for portfolio tracking.
+ *
+ * These types represent Hyperliquid perpetual positions, orders, and account
+ * data that can be injected into MCP tools for personalized portfolio analysis.
+ *
+ * @packageDocumentation
  */
-type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;
 /**
- * The resolved result returned to the user after SDK processing
+ * Hyperliquid Perpetual Position
  */
-interface ExecutionResult<T = unknown> {
-    /** The data returned by the tool */
-    result: T;
-    /** Information about the executed tool */
-    tool: {
-        id: string;
-        name: string;
+interface HyperliquidPerpPosition {
+    /** Asset symbol (e.g., "ETH", "BTC") */
+    coin: string;
+    /** Position size (positive = long, negative = short) */
+    size: number;
+    /** Entry price */
+    entryPrice: number;
+    /** Current mark price */
+    markPrice?: number;
+    /** Unrealized PnL in USD */
+    unrealizedPnl: number;
+    /** Liquidation price */
+    liquidationPrice: number;
+    /** Position value in USD */
+    positionValue: number;
+    /** Leverage info */
+    leverage: {
+        type: "cross" | "isolated";
+        value: number;
+    };
+    /** Margin used for this position */
+    marginUsed: number;
+    /** Return on equity percentage */
+    returnOnEquity: number;
+    /** Cumulative funding paid/received */
+    cumFunding: {
+        allTime: number;
+        sinceOpen: number;
     };
-    /** Execution duration in milliseconds */
-    durationMs: number;
 }
 /**
- * Specific error codes returned by the Context Protocol API
+ * Hyperliquid Open Order
  */
-type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed";
+interface HyperliquidOrder {
+    /** Order ID */
+    oid: number;
+    /** Asset symbol */
+    coin: string;
+    /** Order side: "B" = Buy, "A" = Ask/Sell */
+    side: "B" | "A";
+    /** Limit price */
+    limitPrice: number;
+    /** Order size */
+    size: number;
+    /** Original order size */
+    originalSize: number;
+    /** Order type */
+    orderType: "Limit" | "Market" | "Stop" | "TakeProfit";
+    /** Is reduce-only order */
+    reduceOnly: boolean;
+    /** Is trigger order */
+    isTrigger: boolean;
+    /** Trigger price (if trigger order) */
+    triggerPrice?: number;
+    /** Order timestamp */
+    timestamp: number;
+}
 /**
- * Error thrown by the Context Protocol client
+ * Hyperliquid Spot Balance
  */
-declare class ContextError extends Error {
-    readonly code?: (ContextErrorCode | string) | undefined;
-    readonly statusCode?: number | undefined;
-    readonly helpUrl?: string | undefined;
-    constructor(message: string, code?: (ContextErrorCode | string) | undefined, statusCode?: number | undefined, helpUrl?: string | undefined);
+interface HyperliquidSpotBalance {
+    /** Token symbol */
+    token: string;
+    /** Token balance */
+    balance: number;
+    /** USD value */
+    usdValue?: number;
 }
-
 /**
- * Discovery resource for searching and finding tools on the Context Protocol marketplace
+ * Hyperliquid Account Summary
  */
-declare class Discovery {
-    private client;
-    constructor(client: ContextClient);
-    /**
-     * Search for tools matching a query string
-     *
-     * @param query - The search query (e.g., "gas prices", "nft metadata")
-     * @param limit - Maximum number of results (1-50, default 10)
-     * @returns Array of matching tools
-     *
-     * @example
-     * ```typescript
-     * const tools = await client.discovery.search("gas prices");
-     * console.log(tools[0].name); // "Gas Price Oracle"
-     * console.log(tools[0].mcpTools); // Available methods
-     * ```
-     */
-    search(query: string, limit?: number): Promise<Tool[]>;
-    /**
-     * Get featured/popular tools (empty query search)
-     *
-     * @param limit - Maximum number of results (1-50, default 10)
-     * @returns Array of featured tools
-     *
-     * @example
-     * ```typescript
-     * const featured = await client.discovery.getFeatured(5);
-     * ```
-     */
-    getFeatured(limit?: number): Promise<Tool[]>;
+interface HyperliquidAccountSummary {
+    /** Total account value in USD */
+    accountValue: number;
+    /** Total margin used */
+    totalMarginUsed: number;
+    /** Total notional position value */
+    totalNotionalPosition: number;
+    /** Withdrawable amount */
+    withdrawable: number;
+    /** Cross margin summary */
+    crossMargin: {
+        accountValue: number;
+        totalMarginUsed: number;
+    };
 }
-
 /**
- * Tools resource for executing tools on the Context Protocol marketplace
+ * Complete Hyperliquid portfolio context.
+ * This is what gets passed to MCP tools for personalized analysis.
  */
-declare class Tools {
-    private client;
-    constructor(client: ContextClient);
-    /**
-     * Execute a tool with the provided arguments
-     *
-     * @param options - Execution options
-     * @param options.toolId - The UUID of the tool (from search results)
-     * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)
-     * @param options.args - Arguments to pass to the tool
-     * @returns The execution result with the tool's output data
-     *
-     * @throws {ContextError} With code `no_wallet` if wallet not set up
-     * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled
-     * @throws {ContextError} With code `payment_failed` if on-chain payment fails
-     * @throws {ContextError} With code `execution_failed` if tool execution fails
-     *
-     * @example
-     * ```typescript
-     * // First, search for a tool
-     * const tools = await client.discovery.search("gas prices");
-     * const tool = tools[0];
-     *
-     * // Execute a specific method from the tool's mcpTools
-     * const result = await client.tools.execute({
-     *   toolId: tool.id,
-     *   toolName: tool.mcpTools[0].name, // e.g., "get_gas_prices"
-     *   args: { chainId: 1 }
-     * });
-     *
-     * console.log(result.result); // The tool's output
-     * console.log(result.durationMs); // Execution time
-     * ```
-     */
-    execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>>;
+interface HyperliquidContext {
+    /** The wallet address this context is for */
+    walletAddress: string;
+    /** Perpetual positions */
+    perpPositions: HyperliquidPerpPosition[];
+    /** Open orders */
+    openOrders: HyperliquidOrder[];
+    /** Spot balances */
+    spotBalances: HyperliquidSpotBalance[];
+    /** Account summary */
+    accountSummary: HyperliquidAccountSummary;
+    /** When this context was fetched (ISO 8601 string) */
+    fetchedAt: string;
 }
 
 /**
- * The official TypeScript client for the Context Protocol.
+ * Context types for portfolio and protocol data injection.
  *
- * Use this client to discover and execute AI tools programmatically.
+ * These types allow MCP tools to receive personalized user context
+ * (wallet addresses, positions, balances) for analysis.
  *
  * @example
  * ```typescript
- * import { ContextClient } from "@contextprotocol/client";
+ * import type { PolymarketContext, UserContext } from "@ctxprotocol/sdk";
  *
- * const client = new ContextClient({
- *   apiKey: "sk_live_..."
- * });
+ * // Build context for a user's portfolio
+ * const context: UserContext = {
+ *   wallet: { address: "0x...", chainId: 137 },
+ *   polymarket: {
+ *     walletAddress: "0x...",
+ *     positions: [...],
+ *     openOrders: [],
+ *     fetchedAt: new Date().toISOString(),
+ *   },
+ * };
+ * ```
  *
- * // Discover tools
- * const tools = await client.discovery.search("gas prices");
+ * @packageDocumentation
+ */
+
+/**
+ * Composite context for tools that need multiple data sources.
  *
- * // Execute a tool method
- * const result = await client.tools.execute({
- *   toolId: tools[0].id,
- *   toolName: tools[0].mcpTools[0].name,
- *   args: { chainId: 1 }
- * });
- * ```
+ * This is the unified structure that can be passed to MCP tools
+ * to provide comprehensive user context.
  */
-declare class ContextClient {
-    private readonly apiKey;
-    private readonly baseUrl;
-    /**
-     * Discovery resource for searching tools
-     */
-    readonly discovery: Discovery;
-    /**
-     * Tools resource for executing tools
-     */
-    readonly tools: Tools;
-    /**
-     * Creates a new Context Protocol client
-     *
-     * @param options - Client configuration options
-     * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
-     * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
-     */
-    constructor(options: ContextClientOptions);
-    /**
-     * Internal method for making authenticated HTTP requests
-     * All requests include the Authorization header with the API key
-     *
-     * @internal
-     */
-    fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+interface UserContext {
+    /** Base wallet information */
+    wallet?: WalletContext;
+    /** ERC20 token holdings */
+    erc20?: ERC20Context;
+    /** Polymarket positions and orders */
+    polymarket?: PolymarketContext;
+    /** Hyperliquid perpetual positions and account data */
+    hyperliquid?: HyperliquidContext;
 }
 
-export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecutionResult, type McpTool, type SearchOptions, type SearchResponse, type Tool, Tools };
+export type { ERC20Context, ERC20TokenBalance, HyperliquidAccountSummary, HyperliquidContext, HyperliquidOrder, HyperliquidPerpPosition, HyperliquidSpotBalance, PolymarketContext, PolymarketOrder, PolymarketPosition, UserContext, WalletContext };