SODAX Builders MCP

Instructions

Implementation Reference

• src/tools/sodaxApi.ts:220-276 (handler)

  Main MCP tool handler for sodax_get_volume. Defines the tool registration with schema validation, executes getVolume API call, formats response with pagination info, and handles errors.
  server.tool( "sodax_get_volume", "Get solver volume data showing filled intents with filtering and pagination. Requires inputToken and outputToken. Optional filters: chain, solver, block range OR time range (don't mix both).", { inputToken: z.string() .describe("REQUIRED: Input token address"), outputToken: z.string() .describe("REQUIRED: Output token address"), chainId: z.number().optional() .describe("Filter by chain ID (e.g., 146 for Sonic)"), solver: z.string().optional() .describe("Filter by solver address (0x0...0 for default solver)"), fromBlock: z.number().optional() .describe("Start block number (don't mix with since/until)"), toBlock: z.number().optional() .describe("End block number (don't mix with since/until)"), since: z.string().optional() .describe("Start time ISO format (don't mix with fromBlock/toBlock)"), until: z.string().optional() .describe("End time ISO format (don't mix with fromBlock/toBlock)"), sort: z.enum(["asc", "desc"]).optional().default("desc") .describe("Sort order by block number"), limit: z.number().min(1).max(100).optional().default(50) .describe("Maximum number of filled intents to return (1-100)"), includeData: z.boolean().optional().default(false) .describe("Include raw intent data in response"), cursor: z.string().optional() .describe("Pagination cursor from previous response's nextCursor"), format: z.nativeEnum(ResponseFormat).optional().default(ResponseFormat.MARKDOWN) .describe("Response format: 'json' for raw data or 'markdown' for formatted text") }, READ_ONLY, async ({ inputToken, outputToken, chainId, solver, fromBlock, toBlock, since, until, sort, limit, includeData, cursor, format }) => { try { const volume = await getVolume({ chainId, inputToken, outputToken, solver, fromBlock, toBlock, since, until, sort, limit, includeData, cursor }); const header = `## SODAX Filled Intents\n\n`; const pagination = volume.hasMore && volume.nextCursor ? `\n\n*Has more results. Use cursor: \`${volume.nextCursor.substring(0, 30)}...\`*` : "\n\n*No more results.*"; return { content: [{ type: "text", text: header + formatResponse(volume.items, format) + pagination }] }; } catch (error) { return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }], isError: true }; } } );
• src/services/sodaxApi.ts:154-198 (handler)

  Core getVolume service function that builds API request parameters, implements caching, calls the SODAX API endpoint (/solver/volume), and returns VolumeData with filled intents.
  export async function getVolume(options: { inputToken: string; outputToken: string; chainId?: number; solver?: string; fromBlock?: number; toBlock?: number; since?: string; until?: string; sort?: "asc" | "desc"; limit?: number; includeData?: boolean; cursor?: string; }): Promise<VolumeData> { // Build cache key from significant params const cacheKey = `volume-${options.inputToken}-${options.outputToken}-${options.chainId || "all"}-${options.limit || 50}-${options.cursor || "start"}`; const cached = getCached<VolumeData>(cacheKey); if (cached) return cached; try { const params = new URLSearchParams(); params.append("inputToken", options.inputToken); params.append("outputToken", options.outputToken); params.append("includeData", (options.includeData ?? false).toString()); if (options.chainId) params.append("chainId", options.chainId.toString()); if (options.solver) params.append("solver", options.solver); if (options.fromBlock) params.append("fromBlock", options.fromBlock.toString()); if (options.toBlock) params.append("toBlock", options.toBlock.toString()); if (options.since) params.append("since", options.since); if (options.until) params.append("until", options.until); if (options.sort) params.append("sort", options.sort); if (options.limit) params.append("limit", options.limit.toString()); if (options.cursor) params.append("cursor", options.cursor); const queryString = params.toString(); const url = `/solver/volume${queryString ? `?${queryString}` : ""}`; const response = await apiClient.get(url); const volumeData = response.data; setCache(cacheKey, volumeData); return volumeData; } catch (error) { console.error("Error fetching volume:", error); throw new Error("Failed to fetch volume data from SODAX API"); } }
• src/tools/sodaxApi.ts:223-250 (schema)

  Zod schema defining all input parameters for sodax_get_volume: required inputToken/outputToken, optional filters (chainId, solver, fromBlock/toBlock or since/until), sorting, pagination, and response format options.
  { inputToken: z.string() .describe("REQUIRED: Input token address"), outputToken: z.string() .describe("REQUIRED: Output token address"), chainId: z.number().optional() .describe("Filter by chain ID (e.g., 146 for Sonic)"), solver: z.string().optional() .describe("Filter by solver address (0x0...0 for default solver)"), fromBlock: z.number().optional() .describe("Start block number (don't mix with since/until)"), toBlock: z.number().optional() .describe("End block number (don't mix with since/until)"), since: z.string().optional() .describe("Start time ISO format (don't mix with fromBlock/toBlock)"), until: z.string().optional() .describe("End time ISO format (don't mix with fromBlock/toBlock)"), sort: z.enum(["asc", "desc"]).optional().default("desc") .describe("Sort order by block number"), limit: z.number().min(1).max(100).optional().default(50) .describe("Maximum number of filled intents to return (1-100)"), includeData: z.boolean().optional().default(false) .describe("Include raw intent data in response"), cursor: z.string().optional() .describe("Pagination cursor from previous response's nextCursor"), format: z.nativeEnum(ResponseFormat).optional().default(ResponseFormat.MARKDOWN) .describe("Response format: 'json' for raw data or 'markdown' for formatted text") },
• src/types.ts:75-96 (schema)

  Type definitions for VolumeData (paginated response with items, nextCursor, hasMore) and FilledIntent (intent data structure with hash, solver, tokens, amounts, chain, block, timestamp).
  export interface FilledIntent { intentHash: string; solver: string; inputToken: string; outputToken: string; amount: string; chainId: number; blockNumber: number; txHash: string; logIndex: number; timestamp: string; data?: string; } /** * Paginated response for solver volume (filled intents) */ export interface VolumeData { items: FilledIntent[]; nextCursor?: string; hasMore: boolean; }
• src/index.ts:198-198 (registration)

  Tool registration listing sodax_get_volume in the API tools array for server metadata endpoint.
  "sodax_get_volume",