OKX MCP Server

Instructions

Implementation Reference

• src/index.ts:559-663 (handler)

  The handler function for the 'get_price' tool within the CallToolRequestSchema handler. It fetches the latest ticker data from the OKX REST API, handles JSON or Markdown formatting, calculates price changes, and generates a visual price range bar.

  if (request.params.name === "get_price") {
    console.error(
      `[API] Fetching price for instrument: ${args.instrument}`
    );
    const response = await this.axiosInstance.get<OKXTickerResponse>(
      "/market/ticker",
      {
        params: {instId: args.instrument},
      }
    );
  
    if (response.data.code !== "0") {
      throw new Error(`OKX API error: ${response.data.msg}`);
    }
  
    if (!response.data.data || response.data.data.length === 0) {
      throw new Error("No data returned from OKX API");
    }
  
    const ticker = response.data.data[0];
  
    if (args.format === "json") {
      // Original JSON format
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                instrument: ticker.instId,
                lastPrice: ticker.last,
                bid: ticker.bidPx,
                ask: ticker.askPx,
                high24h: ticker.high24h,
                low24h: ticker.low24h,
                volume24h: ticker.vol24h,
                timestamp: new Date(parseInt(ticker.ts)).toISOString(),
              },
              null,
              2
            ),
          },
        ],
      };
    } else {
      // Enhanced markdown format with visualization elements
      const priceChange =
        parseFloat(ticker.last) - parseFloat(ticker.open24h);
      const priceChangePercent =
        (priceChange / parseFloat(ticker.open24h)) * 100;
      const changeSymbol = priceChange >= 0 ? "▲" : "▼";
      const changeColor = priceChange >= 0 ? "green" : "red";
  
      // Create price range visual
      const low24h = parseFloat(ticker.low24h);
      const high24h = parseFloat(ticker.high24h);
      const range = high24h - low24h;
      const currentPrice = parseFloat(ticker.last);
      const position =
        Math.min(Math.max((currentPrice - low24h) / range, 0), 1) * 100;
  
      const priceBar = `Low ${low24h.toFixed(2)} [${"▮".repeat(
        Math.floor(position / 5)
      )}|${"▯".repeat(20 - Math.floor(position / 5))}] ${high24h.toFixed(
        2
      )} High`;
  
      return {
        content: [
          {
            type: "text",
            text:
              `# ${ticker.instId} Price Summary\n\n` +
              `## Current Price: $${parseFloat(
                ticker.last
              ).toLocaleString()}\n\n` +
              `**24h Change:** ${changeSymbol} $${Math.abs(
                priceChange
              ).toLocaleString()} (${
                priceChangePercent >= 0 ? "+" : ""
              }${priceChangePercent.toFixed(2)}%)\n\n` +
              `**Bid:** $${parseFloat(
                ticker.bidPx
              ).toLocaleString()} | **Ask:** $${parseFloat(
                ticker.askPx
              ).toLocaleString()}\n\n` +
              `### 24-Hour Price Range\n\n` +
              `\`\`\`\n${priceBar}\n\`\`\`\n\n` +
              `**24h High:** $${parseFloat(
                ticker.high24h
              ).toLocaleString()}\n` +
              `**24h Low:** $${parseFloat(
                ticker.low24h
              ).toLocaleString()}\n\n` +
              `**24h Volume:** ${parseFloat(
                ticker.vol24h
              ).toLocaleString()} units\n\n` +
              `**Last Updated:** ${new Date(
                parseInt(ticker.ts)
              ).toLocaleString()}\n\n` +
              `*Note: For real-time updates, use the subscribe_ticker and get_live_ticker tools.*`,
          },
        ],
      };
    }

• src/index.ts:287-305 (registration)

  Registration of the 'get_price' tool in the ListToolsRequestSchema response, defining its name, description, and input schema.

    name: "get_price",
    description:
      "Get latest price for an OKX instrument with formatted visualization",
    inputSchema: {
      type: "object",
      properties: {
        instrument: {
          type: "string",
          description: "Instrument ID (e.g. BTC-USDT)",
        },
        format: {
          type: "string",
          description: "Output format (json or markdown)",
          default: "markdown",
        },
      },
      required: ["instrument"],
    },
  },

• src/index.ts:290-304 (schema)

  Input schema for the 'get_price' tool, defining required 'instrument' parameter and optional 'format' parameter.

  inputSchema: {
    type: "object",
    properties: {
      instrument: {
        type: "string",
        description: "Instrument ID (e.g. BTC-USDT)",
      },
      format: {
        type: "string",
        description: "Output format (json or markdown)",
        default: "markdown",
      },
    },
    required: ["instrument"],
  },

• src/index.ts:14-28 (schema)

  TypeScript interface defining the OKX ticker API response structure used in the get_price handler for type safety.

  interface OKXTickerResponse {
    code: string;
    msg: string;
    data: Array<{
      instId: string;
      last: string;
      askPx: string;
      bidPx: string;
      open24h: string;
      high24h: string;
      low24h: string;
      volCcy24h: string;
      vol24h: string;
      ts: string;
    }>;

• src/index.ts:390-396 (registration)

  Validation registration listing 'get_price' as an allowed tool name in the CallToolRequestSchema dispatcher.

  const validTools = [
    "get_price",
    "get_candlesticks",
    "subscribe_ticker",
    "get_live_ticker",
    "unsubscribe_ticker",
  ];