list_polymarket_events

Instructions

Implementation Reference

• src/index.ts:1049-1094 (registration)

  Tool registration for 'list_polymarket_events'. This is where the tool is registered with the MCP server, defining its name, description, input schema, and handler. The handler calls listEvents() from polymarketApi.

  // Tool 23: list_polymarket_events
  // ---------------------------------------------------------------------------
  server.registerTool(
    "list_polymarket_events",
    {
      description:
        "List Polymarket events (groups of related markets). Events bundle multiple Yes/No markets under one topic (e.g. 'US Presidential Election 2024' contains many candidate markets). Uses the Gamma API.",
      inputSchema: {
        limit: z.number().min(1).max(100).default(10).describe("Number of events (1-100)"),
        active: z.boolean().optional().describe("Filter: only active events"),
        closed: z.boolean().optional().describe("Filter: only closed events"),
        tag: z.string().optional().describe("Filter by tag (e.g. 'politics', 'crypto', 'sports')"),
        orderBy: z
          .enum(["volume", "liquidity", "startDate", "endDate", "createdAt"])
          .optional()
          .describe("Sort field"),
        ascending: z.boolean().default(false).describe("Sort ascending"),
      },
    },
    async ({ limit, active, closed, tag, orderBy, ascending }) => {
      try {
        const events = await listEvents({ limit, active, closed, tag, orderBy, ascending });
        return textResult({
          count: events.length,
          events: events.map((e) => ({
            id: e.id,
            title: e.title,
            slug: e.slug,
            description: e.description,
            startDate: e.startDate,
            endDate: e.endDate,
            marketCount: e.markets?.length ?? 0,
            markets: (e.markets ?? []).map((m) => ({
              id: m.id,
              question: m.question,
              outcomePrices: m.outcomePrices,
              volume: m.volume,
              active: m.active,
            })),
          })),
        });
      } catch (error) {
        return errorResult(error);
      }
    }
  );

• src/index.ts:1068-1094 (handler)

  Handler function for the list_polymarket_events tool. Calls listEvents() and formats the response with event metadata including id, title, slug, description, dates, and nested market info.

    async ({ limit, active, closed, tag, orderBy, ascending }) => {
      try {
        const events = await listEvents({ limit, active, closed, tag, orderBy, ascending });
        return textResult({
          count: events.length,
          events: events.map((e) => ({
            id: e.id,
            title: e.title,
            slug: e.slug,
            description: e.description,
            startDate: e.startDate,
            endDate: e.endDate,
            marketCount: e.markets?.length ?? 0,
            markets: (e.markets ?? []).map((m) => ({
              id: m.id,
              question: m.question,
              outcomePrices: m.outcomePrices,
              volume: m.volume,
              active: m.active,
            })),
          })),
        });
      } catch (error) {
        return errorResult(error);
      }
    }
  );

• src/index.ts:1056-1067 (schema)

  Zod input schema for the list_polymarket_events tool: limit (1-100, default 10), optional active/closed/tag filters, optional orderBy enum, and ascending boolean.

    inputSchema: {
      limit: z.number().min(1).max(100).default(10).describe("Number of events (1-100)"),
      active: z.boolean().optional().describe("Filter: only active events"),
      closed: z.boolean().optional().describe("Filter: only closed events"),
      tag: z.string().optional().describe("Filter by tag (e.g. 'politics', 'crypto', 'sports')"),
      orderBy: z
        .enum(["volume", "liquidity", "startDate", "endDate", "createdAt"])
        .optional()
        .describe("Sort field"),
      ascending: z.boolean().default(false).describe("Sort ascending"),
    },
  },

• src/polymarketApi.ts:97-111 (helper)

  Helper function listEvents() that calls the Gamma API to fetch events. Builds query params from the options and returns a Promise of GammaEvent array.

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

• src/polymarketApi.ts:60-69 (helper)

  Type definition for GammaEvent used by listEvents() and the tool handler. Contains id, slug, title, description, dates, and nested markets array.

  export interface GammaEvent {
    id: string;
    slug: string;
    title: string;
    description: string;
    startDate: string;
    endDate: string;
    markets: GammaMarket[];
    [key: string]: unknown;
  }