search_markets

Instructions

Implementation Reference

• src/polymarketApi.ts:71-85 (handler)

  The actual async function that queries the Gamma API to search Polymarket markets by text query. Builds URL params (_limit, _q, active, closed, _sort, _order) and returns typed GammaMarket[].

  export async function searchMarkets(
    query: string,
    opts: { limit?: number; active?: boolean; closed?: boolean; orderBy?: string; ascending?: boolean } = {}
  ): Promise<GammaMarket[]> {
    const params = new URLSearchParams();
    params.set("_limit", String(opts.limit ?? 10));
    if (query) params.set("_q", query);
    if (opts.active !== undefined) params.set("active", String(opts.active));
    if (opts.closed !== undefined) params.set("closed", String(opts.closed));
    if (opts.orderBy) {
      params.set("_sort", opts.orderBy);
      params.set("_order", opts.ascending ? "asc" : "desc");
    }
    return fetchJson<GammaMarket[]>(`${GAMMA_BASE}/markets?${params}`);
  }

• src/polymarketApi.ts:37-58 (schema)

  The GammaMarket interface defines the shape of market data returned by searchMarkets, including fields like question, conditionId, slug, outcomePrices, clobTokenIds, volume, liquidity, etc.

  export interface GammaMarket {
    id: string;
    question: string;
    conditionId: string;
    slug: string;
    resolutionSource: string;
    endDate: string;
    liquidity: string;
    volume: string;
    active: boolean;
    closed: boolean;
    marketMakerAddress: string;
    outcomePrices: string;
    outcomes: string;
    clobTokenIds: string;
    bestBid: string;
    bestAsk: string;
    lastTradePrice: string;
    spread: string;
    description: string;
    [key: string]: unknown;
  }

• src/index.ts:969-1015 (registration)

  Registers the 'search_markets' tool with the MCP server. Defines the input schema (query, limit, active, closed, orderBy, ascending) and the handler that calls the searchMarkets function from polymarketApi.ts, transforming results into a JSON response.

  server.registerTool(
    "search_markets",
    {
      description:
        "Search Polymarket prediction markets by text query. Returns market metadata including question, prices, volume, liquidity, and CLOB token IDs. Uses the Gamma API for real-time market discovery. Chain with: get_clob_market(conditionId) for live order books, get_live_prices(clobTokenIds) for token-level pricing, get_market_open_interest for capital locked, or get_market_resolution for oracle status.",
      inputSchema: {
        query: z.string().describe("Search text (e.g. 'Trump', 'Bitcoin', 'World Cup')"),
        limit: z.number().min(1).max(100).default(10).describe("Number of results (1-100)"),
        active: z.boolean().optional().describe("Filter: only active markets"),
        closed: z.boolean().optional().describe("Filter: only closed/resolved markets"),
        orderBy: z
          .enum(["volume", "liquidity", "endDate", "startDate", "createdAt"])
          .optional()
          .describe("Sort field"),
        ascending: z.boolean().default(false).describe("Sort ascending (default: descending)"),
      },
    },
    async ({ query, limit, active, closed, orderBy, ascending }) => {
      try {
        const markets = await searchMarkets(query, { limit, active, closed, orderBy, ascending });
        return textResult({
          count: markets.length,
          markets: markets.map((m) => ({
            id: m.id,
            question: m.question,
            slug: m.slug,
            conditionId: m.conditionId,
            active: m.active,
            closed: m.closed,
            outcomePrices: m.outcomePrices,
            outcomes: m.outcomes,
            bestBid: m.bestBid,
            bestAsk: m.bestAsk,
            lastTradePrice: m.lastTradePrice,
            spread: m.spread,
            volume: m.volume,
            liquidity: m.liquidity,
            endDate: m.endDate,
            clobTokenIds: m.clobTokenIds,
            description: m.description,
          })),
        });
      } catch (error) {
        return errorResult(error);
      }
    }
  );

• src/polymarketApi.ts:19-31 (helper)

  The fetchJson helper function used by searchMarkets to make HTTP requests to the Gamma API with proper error handling.

  async function fetchJson<T>(url: string): Promise<T> {
    const response = await fetch(url, {
      headers: { Accept: "application/json" },
    });
    if (!response.ok) {
      throw new PolymarketApiError(
        `HTTP ${response.status}: ${response.statusText}`,
        response.status,
        url
      );
    }
    return response.json() as Promise<T>;
  }