AgentPay-mcp

Instructions

Implementation Reference

• src/tools/wallet.ts:259-336 (handler)

  The handleQueueApproval function processes listing, approving, and canceling pending transactions.

  export async function handleQueueApproval(
    input: QueueApprovalInput
  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
    try {
      const wallet = getWallet();
      const config = getConfig();
  
      if (input.action === 'list') {
        const pending = await getPendingApprovals(wallet, 0n);
  
        if (pending.length === 0) {
          return {
            content: [
              textContent(`📋 **Pending Approvals**\n\nNo transactions awaiting approval. ✅`),
            ],
          };
        }
  
        let out = `📋 **Pending Approvals** (${pending.length} transaction${pending.length > 1 ? 's' : ''})\n\n`;
        for (const tx of pending) {
          out += `─────────────────────────\n`;
          out += `  Queue ID:   ${tx.txId.toString()}\n`;
          out += `  To:         ${tx.to}\n`;
          out += `  Value:      ${formatEth(tx.value)}\n`;
          out += `  Token:      ${tx.token === NATIVE_TOKEN ? 'ETH' : tx.token}\n`;
          if (tx.token !== NATIVE_TOKEN) {
            out += `  Amount:     ${tx.amount.toString()} (base units)\n`;
          }
          out += `  Queued at:  ${formatTimestamp(tx.createdAt)}\n`;
          out += '\n';
        }
        out += `Use action="approve" with tx_id to approve, or action="cancel" to cancel.`;
  
        return { content: [textContent(out)] };
      }
  
      if (input.action === 'approve' || input.action === 'cancel') {
        if (!input.tx_id) {
          throw new Error(`tx_id is required for action="${input.action}"`);
        }
  
        const txId = BigInt(input.tx_id);
        let txHash: string;
  
        if (input.action === 'approve') {
          txHash = await approveTransaction(wallet, txId);
          return {
            content: [
              textContent(
                formatSuccess(`Transaction ${txId.toString()} approved!`, {
                  'Approval TX': txHash,
                  'Chain': chainName(config.chainId),
                })
              ),
            ],
          };
        } else {
          txHash = await cancelTransaction(wallet, txId);
          return {
            content: [
              textContent(
                formatSuccess(`Transaction ${txId.toString()} cancelled.`, {
                  'Cancel TX': txHash,
                })
              ),
            ],
          };
        }
      }
  
      throw new Error(`Unknown action: ${input.action}`);
    } catch (error: unknown) {
      return {
        content: [textContent(formatError(error, 'queue_approval'))],
        isError: true,
      };
    }
  }

• src/tools/wallet.ts:219-233 (schema)

  The QueueApprovalSchema defines the input validation for the queue_approval tool.

  export const QueueApprovalSchema = z.object({
    action: z
      .enum(['list', 'approve', 'cancel'])
      .describe(
        '"list" — show all pending transactions awaiting approval. ' +
        '"approve" — approve a queued transaction by ID. ' +
        '"cancel" — cancel a queued transaction by ID.'
      ),
    tx_id: z
      .string()
      .optional()
      .describe('Transaction queue ID (required for approve and cancel actions).'),
  });
  
  export type QueueApprovalInput = z.infer<typeof QueueApprovalSchema>;

• src/tools/wallet.ts:235-257 (registration)

  The queueApprovalTool definition and registration metadata.

  export const queueApprovalTool = {
    name: 'queue_approval',
    description:
      'Manage over-limit transactions queued for owner review. ' +
      'Use action="list" to see pending transactions, ' +
      '"approve" to approve one by ID, or "cancel" to cancel one by ID. ' +
      'Approve/cancel require the agent key to have owner privileges.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        action: {
          type: 'string',
          enum: ['list', 'approve', 'cancel'],
          description: 'Action: "list", "approve", or "cancel"',
        },
        tx_id: {
          type: 'string',
          description: 'Transaction queue ID (required for approve/cancel)',
        },
      },
      required: ['action'],
    },
  };