transfer_to_agent

Transfer Bitcoin Lightning payments between AI agents or from operator to agents using the Lightning Wallet MCP server. Enables autonomous agent-to-agent transactions with spending controls.

Instructions

Transfer sats between agents or from operator to agent. REQUIRES OPERATOR KEY.

Input Schema

TableJSON Schema

Name	Required	Description
`from_agent_id`	No	Source agent ID (omit to use operator balance)
`to_agent_id`	Yes	Destination agent ID
`amount_sats`	Yes	Amount to transfer

Implementation Reference

src/index.ts:1581-1602 (handler)

MCP tool request handler for 'transfer_to_agent' which calls the LightningFaucetClient.transferToAgent method.

case 'transfer_to_agent': {
  const parsed = TransferToAgentSchema.parse(args);
  const result = await session.requireClient().transferToAgent(
    parsed.to_agent_id,
    parsed.amount_sats,
    parsed.from_agent_id
  );
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: `Transferred ${result.amountTransferred} sats`,
          amount_transferred: result.amountTransferred,
          from_balance: result.fromBalance,
          to_balance: result.toBalance,
        }, null, 2),
      },
    ],
  };
}

src/lightning-faucet.ts:1116-1155 (handler)

The actual implementation of transferToAgent in the LightningFaucetClient class. It handles both operator-to-agent and agent-to-agent transfers.

async transferToAgent(
  toAgentId: number,
  amountSats: number,
  fromAgentId?: number
): Promise<{
  amountTransferred: number;
  fromBalance: number;
  toBalance: number;
  rawResponse: ApiResponse;
}> {
  // If fromAgentId is provided, it's agent-to-agent; otherwise operator-to-agent
  if (fromAgentId) {
    // This would need a new backend endpoint for agent-to-agent
    const result = await this.request<ApiResponse & {
      amount_transferred?: number;
      from_balance?: number;
      to_balance?: number;
    }>('transfer_between_agents', {
      from_agent_id: fromAgentId,
      to_agent_id: toAgentId,
      amount_sats: amountSats,
    });

    return {
      amountTransferred: result.amount_transferred || amountSats,
      fromBalance: result.from_balance || 0,
      toBalance: result.to_balance || 0,
      rawResponse: result,
    };
  } else {
    // Use existing fund_agent
    const result = await this.fundAgent(toAgentId, amountSats);
    return {
      amountTransferred: result.amountTransferred,
      fromBalance: result.newOperatorBalance,
      toBalance: result.newAgentBalance,
      rawResponse: result.rawResponse,
    };
  }
}

src/index.ts:252-256 (schema)

Input validation schema for the 'transfer_to_agent' tool using Zod.

const TransferToAgentSchema = z.object({
  from_agent_id: z.number().int().positive().optional().describe('Source agent ID (optional, defaults to operator balance)'),
  to_agent_id: z.number().int().positive().describe('Destination agent ID'),
  amount_sats: z.number().int().positive().describe('Amount to transfer'),
});

src/index.ts:729-740 (registration)

Registration of the 'transfer_to_agent' tool within the MCP server's tool list.

  name: 'transfer_to_agent',
  description: 'Transfer sats between agents or from operator to agent. REQUIRES OPERATOR KEY.',
  inputSchema: {
    type: 'object',
    properties: {
      from_agent_id: { type: 'integer', description: 'Source agent ID (omit to use operator balance)' },
      to_agent_id: { type: 'integer', description: 'Destination agent ID' },
      amount_sats: { type: 'integer', minimum: 1, description: 'Amount to transfer' },
    },
    required: ['to_agent_id', 'amount_sats'],
  },
},

Lightning Wallet MCP