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",