Lightning Wallet MCP

Instructions

Implementation Reference

• src/lightning-faucet.ts:684-716 (handler)

  The getBudgetStatus method in the LightningFaucetClient class fetches budget status from the API.

   */
  async getBudgetStatus(agentId?: number): Promise<{
    agentId: number;
    budgetLimitSats: number | null;
    totalSpentSats: number;
    remainingSats: number | null;
    hasBudget: boolean;
    rawResponse: ApiResponse;
  }> {
    const data: Record<string, unknown> = {};
    if (agentId) data.agent_id = agentId;
  
    const result = await this.request<ApiResponse & {
      agent_id?: number;
      budget_limit_sats?: number | null;
      total_spent?: number;
      total_spent_sats?: number;
      remaining_sats?: number | null;
      has_budget?: boolean;
    }>('get_budget_status', data);
  
    const budgetLimit = result.budget_limit_sats ?? null;
    const totalSpent = result.total_spent_sats || result.total_spent || 0;
  
    return {
      agentId: result.agent_id || agentId || 0,
      budgetLimitSats: budgetLimit,
      totalSpentSats: totalSpent,
      remainingSats: budgetLimit !== null ? budgetLimit - totalSpent : null,
      hasBudget: budgetLimit !== null,
      rawResponse: result,
    };
  }

• src/index.ts:1231-1249 (handler)

  MCP tool handler implementation for get_budget_status.

  case 'get_budget_status': {
    const parsed = GetBudgetStatusSchema.parse(args);
    const result = await session.requireClient().getBudgetStatus(parsed.agent_id);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            agent_id: result.agentId,
            budget_limit_sats: result.budgetLimitSats,
            total_spent_sats: result.totalSpentSats,
            remaining_sats: result.remainingSats,
            has_budget: result.hasBudget,
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:179-181 (schema)

  Input schema for get_budget_status tool.

  const GetBudgetStatusSchema = z.object({
    agent_id: z.number().int().positive().optional().describe('Agent ID (operators only, defaults to current agent)'),
  });