get_user_fills

Instructions

Implementation Reference

• mcp-server.ts:176-197 (registration)

  Registration of the 'get_user_fills' tool via server.tool() with Zod schema for address (string) and limit (number, default 20).

  server.tool(
    'get_user_fills',
    'Get trade history for a user address',
    { address: z.string().describe('User wallet address'), limit: z.number().default(20).describe('Max number of fills to return') },
    async ({ address, limit }) => {
      const fills = await hlInfo<UserFill[]>({ type: 'userFills', user: address });
      const outcomeFills = fills.filter(f => f.coin.startsWith('#')).slice(0, limit);
  
      if (outcomeFills.length === 0) {
        return { content: [{ type: 'text', text: 'No outcome trades found for this address.' }] };
      }
  
      const lines = outcomeFills.map(f => {
        const date = new Date(f.time).toISOString().slice(0, 19);
        const pnl = parseFloat(f.closedPnl);
        const pnlStr = pnl !== 0 ? ` PnL: ${pnl > 0 ? '+' : ''}$${pnl.toFixed(2)}` : '';
        return `${date} ${f.side.toUpperCase()} ${f.coin} ${f.sz} @ ${(parseFloat(f.px) * 100).toFixed(1)}%${pnlStr}`;
      });
  
      return { content: [{ type: 'text', text: lines.join('\n') }] };
    },
  );

• mcp-server.ts:180-197 (handler)

  Handler function that calls HL API 'userFills', filters for outcome coins (# prefix), slices to limit, and formats output with date, side, coin, size, price, and PnL.

    async ({ address, limit }) => {
      const fills = await hlInfo<UserFill[]>({ type: 'userFills', user: address });
      const outcomeFills = fills.filter(f => f.coin.startsWith('#')).slice(0, limit);
  
      if (outcomeFills.length === 0) {
        return { content: [{ type: 'text', text: 'No outcome trades found for this address.' }] };
      }
  
      const lines = outcomeFills.map(f => {
        const date = new Date(f.time).toISOString().slice(0, 19);
        const pnl = parseFloat(f.closedPnl);
        const pnlStr = pnl !== 0 ? ` PnL: ${pnl > 0 ? '+' : ''}$${pnl.toFixed(2)}` : '';
        return `${date} ${f.side.toUpperCase()} ${f.coin} ${f.sz} @ ${(parseFloat(f.px) * 100).toFixed(1)}%${pnlStr}`;
      });
  
      return { content: [{ type: 'text', text: lines.join('\n') }] };
    },
  );

• mcp-server.ts:178-179 (schema)

  Zod schema definitions for the input parameters: address (required string) and limit (optional number, default 20).

  'Get trade history for a user address',
  { address: z.string().describe('User wallet address'), limit: z.number().default(20).describe('Max number of fills to return') },

• mcp-server.ts:21-29 (helper)

  Generic HL API helper function used by the handler to fetch user fills data from the /info endpoint.

  async function hlInfo<T>(body: object): Promise<T> {
    const res = await fetch(`${API_URL}/info`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (!res.ok) throw new Error(`HL API error: ${res.status}`);
    return res.json() as Promise<T>;
  }

• mcp-server.ts:48-51 (helper)

  TypeScript interface defining the shape of a user fill returned from the HL API (coin, px, sz, side, time, closedPnl, fee).

  interface UserFill {
    coin: string; px: string; sz: string; side: string;
    time: number; closedPnl: string; fee: string;
  }