SODAX Builders MCP

Instructions

Implementation Reference

• src/services/sodaxApi.ts:203-219 (handler)

  The getOrderbook function implements the core logic to fetch orderbook data from the SODAX API. It accepts optional limit parameter, constructs the API request to /solver/orderbook endpoint, and returns an array of OrderbookEntry objects.

  export async function getOrderbook(options?: {
    limit?: number;
  }): Promise<OrderbookEntry[]> {
    try {
      const params = new URLSearchParams();
      if (options?.limit) params.append("limit", options.limit.toString());
  
      const queryString = params.toString();
      const url = `/solver/orderbook${queryString ? `?${queryString}` : ""}`;
      const response = await apiClient.get(url);
      // API returns { total, data }
      return response.data?.data || response.data || [];
    } catch (error) {
      console.error("Error fetching orderbook:", error);
      throw new Error("Failed to fetch orderbook from SODAX API");
    }
  }

• src/tools/sodaxApi.ts:278-305 (registration)

  Tool registration with MCP server, defining the tool name 'sodax_get_orderbook', description, input schema (limit and format parameters), and the async handler that calls getOrderbook service and formats the response.

  // Tool 6: Get Orderbook
  server.tool(
    "sodax_get_orderbook",
    "Get current orderbook entries showing pending/open intents",
    {
      limit: z.number().min(1).max(100).optional().default(20)
        .describe("Maximum number of orders to return (1-100)"),
      format: z.nativeEnum(ResponseFormat).optional().default(ResponseFormat.MARKDOWN)
        .describe("Response format: 'json' for raw data or 'markdown' for formatted text")
    },
    READ_ONLY,
    async ({ limit, format }) => {
      try {
        const orderbook = await getOrderbook({ limit });
        return {
          content: [{
            type: "text",
            text: `## Orderbook\n\n${orderbook.length} orders found\n\n` + formatResponse(orderbook, format)
          }]
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }],
          isError: true
        };
      }
    }
  );

• src/types.ts:101-119 (schema)

  TypeScript interface defining the OrderbookEntry schema with fields for orderId, chainId, maker, tokenIn, tokenOut, price, status, createdAt, and expiresAt.

  export interface OrderbookEntry {
    orderId: string;
    chainId: string;
    maker: string;
    tokenIn: {
      address: string;
      symbol: string;
      amount: string;
    };
    tokenOut: {
      address: string;
      symbol: string;
      amount: string;
    };
    price: number;
    status: "open" | "partial" | "filled" | "cancelled";
    createdAt: number;
    expiresAt?: number;
  }

• src/index.ts:193-205 (registration)

  Tool metadata registration listing 'sodax_get_orderbook' as part of the api tools array in the server configuration.

  api: [
    "sodax_get_supported_chains",
    "sodax_get_swap_tokens",
    "sodax_get_transaction",
    "sodax_get_user_transactions",
    "sodax_get_volume",
    "sodax_get_orderbook",
    "sodax_get_money_market_assets",
    "sodax_get_user_position",
    "sodax_get_partners",
    "sodax_get_token_supply",
    "sodax_refresh_cache"
  ],

• src/services/analytics.ts:26-44 (helper)

  Analytics mapping that categorizes 'sodax_get_orderbook' under the 'api' group for PostHog event tracking.

  const TOOL_GROUPS: Record<string, string> = {
    // SODAX API tools
    sodax_get_supported_chains: "api",
    sodax_get_swap_tokens: "api",
    sodax_get_transaction: "api",
    sodax_get_user_transactions: "api",
    sodax_get_volume: "api",
    sodax_get_orderbook: "api",
    sodax_get_money_market_assets: "api",
    sodax_get_user_position: "api",
    sodax_get_partners: "api",
    sodax_get_token_supply: "api",
    sodax_refresh_cache: "api",
  
    // GitBook SDK docs meta-tools
    docs_health: "sdk-docs",
    docs_refresh: "sdk-docs",
    docs_list_tools: "sdk-docs",
  };