SODAX Builders MCP

Instructions

Implementation Reference

• src/tools/sodaxApi.ts:150-182 (handler)

  Tool registration and handler for sodax_get_transaction. Defines the input schema (txHash, format) using Zod validation, executes the getTransaction service call, and formats the response with error handling. Returns transaction details or 'not found' message.

  // Tool 3: Get Transaction
  server.tool(
    "sodax_get_transaction",
    "Look up a specific transaction by its hash to see status, amounts, and details",
    {
      txHash: z.string()
        .describe("The transaction hash to look up (e.g., '0x...')"),
      format: z.nativeEnum(ResponseFormat).optional().default(ResponseFormat.MARKDOWN)
        .describe("Response format: 'json' for raw data or 'markdown' for formatted text")
    },
    READ_ONLY,
    async ({ txHash, format }) => {
      try {
        const transaction = await getTransaction(txHash);
        if (!transaction) {
          return {
            content: [{ type: "text", text: `Transaction not found: ${txHash}` }]
          };
        }
        return {
          content: [{
            type: "text",
            text: `## Transaction Details\n\n${formatResponse(transaction, format)}`
          }]
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }],
          isError: true
        };
      }
    }
  );

• src/services/sodaxApi.ts:109-123 (handler)

  Service implementation of getTransaction function. Makes an HTTP GET request to the SODAX API endpoint '/intent/tx/{txHash}' to fetch transaction data by hash. Returns null for 404 errors, otherwise throws on failure.

  /**
   * Look up a transaction/intent by hash
   */
  export async function getTransaction(txHash: string): Promise<Transaction | null> {
    try {
      const response = await apiClient.get(`/intent/tx/${txHash}`);
      return response.data?.data || response.data || null;
    } catch (error) {
      if (axios.isAxiosError(error) && error.response?.status === 404) {
        return null;
      }
      console.error("Error fetching transaction:", error);
      throw new Error("Failed to fetch transaction from SODAX API");
    }
  }

• src/types.ts:41-67 (schema)

  TypeScript interface definition for Transaction type. Defines the structure of transaction data including txHash, chainId, status, type, from/to addresses, token in/out details, timestamp, block number, and gas information.

  /**
   * Transaction record
   */
  export interface Transaction {
    txHash: string;
    chainId: string;
    status: "pending" | "completed" | "failed";
    type: "swap" | "bridge" | "deposit" | "withdraw" | "borrow" | "repay";
    fromAddress: string;
    toAddress?: string;
    tokenIn?: {
      address: string;
      symbol: string;
      amount: string;
      amountUsd?: number;
    };
    tokenOut?: {
      address: string;
      symbol: string;
      amount: string;
      amountUsd?: number;
    };
    timestamp: number;
    blockNumber?: number;
    gasUsed?: string;
    gasFee?: string;
  }

• src/index.ts:32-46 (registration)

  Main server setup that calls registerSodaxApiTools(server) to register all SODAX API tools including sodax_get_transaction. This is the entry point where all tools are registered with the MCP server instance.

  async function createServer(): Promise<McpServer> {
    const server = new McpServer({
      name: "builders-sodax-mcp-server",
      version: "1.0.0"
    });
  
    // Wrap server.tool() so every tool call is tracked in PostHog
    // ⚠️  Must be called BEFORE registering any tools
    withAnalytics(server);
  
    registerSodaxApiTools(server);
    await registerGitBookProxyTools(server);
  
    return server;
  }

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

  Analytics mapping configuration that groups sodax_get_transaction under the 'api' category for PostHog event tracking. This enables automatic usage analytics for the tool.

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