run402

Instructions

Implementation Reference

• src/tools/check-balance.ts:11-55 (handler)

  The handleCheckBalance function implements the check_balance tool logic. It takes a wallet address, makes an API request to fetch billing account information, and returns formatted balance information including available and held funds.

  export async function handleCheckBalance(args: {
    wallet: string;
  }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
    const wallet = args.wallet.toLowerCase();
  
    const res = await apiRequest(`/v1/billing/accounts/${wallet}`, {
      method: "GET",
    });
  
    if (!res.ok) return formatApiError(res, "checking balance");
  
    const body = res.body as {
      wallet: string;
      exists: boolean;
      available_usd_micros: number;
      held_usd_micros: number;
      status?: string;
    };
  
    if (!body.exists) {
      return {
        content: [
          {
            type: "text",
            text: `## Billing: ${wallet}\n\nNo billing account found. Top up via Stripe or on-chain USDC to create one.`,
          },
        ],
      };
    }
  
    const availableUsd = (body.available_usd_micros / 1_000_000).toFixed(2);
    const heldUsd = (body.held_usd_micros / 1_000_000).toFixed(2);
  
    const lines = [
      `## Billing: ${wallet}`,
      ``,
      `| Field | Value |`,
      `|-------|-------|`,
      `| available | $${availableUsd} |`,
      `| held | $${heldUsd} |`,
      `| status | ${body.status} |`,
    ];
  
    return { content: [{ type: "text", text: lines.join("\n") }] };
  }

• src/tools/check-balance.ts:5-9 (schema)

  The checkBalanceSchema defines the input schema for the check_balance tool, specifying that it requires a 'wallet' parameter as a string (wallet address starting with 0x).

  export const checkBalanceSchema = {
    wallet: z
      .string()
      .describe("Wallet address (0x...) to check billing balance for"),
  };

• src/index.ts:289-294 (registration)

  Registration of the check_balance tool with the MCP server using server.tool(), providing the tool name, description, schema, and handler function.

  server.tool(
    "check_balance",
    "Check billing account balance for a wallet address. Shows available and held funds.",
    checkBalanceSchema,
    async (args) => handleCheckBalance(args),
  );

• src/index.ts:48-48 (helper)

  Import statement bringing in checkBalanceSchema and handleCheckBalance from the tools/check-balance module.

  import { checkBalanceSchema, handleCheckBalance } from "./tools/check-balance.js";