ALPHA TESTING

🚀 Invest in FinAegis CGO - Continuous Growth Offering

Learn More

Code Examples

Working examples and integration patterns for common use cases with the FinAegis API.

Browse by Category

Basic Operations

Account creation, balance queries, and simple transfers

Advanced Workflows

Multi-step transactions, batch operations, and saga patterns

Webhooks

Real-time notifications and event handling

Error Handling

Robust error handling and retry patterns

AI Agent Integration

Banking AI assistant and MCP tools

MCP Tools

Model Context Protocol integration

Basic Operations

Create Account and Get Balance

Initialize a new account and retrieve balance information

POST GET 
import { FinAegis } from '@finaegis/sdk';

const client = new FinAegis({
  apiKey: process.env.FINAEGIS_API_KEY,
  baseURL: 'https://api.finaegis.org/v2'
});

async function createAccountAndCheckBalance() {
  try {
    // Create a new account
    const account = await client.accounts.create({
      name: 'My Main Account',
      type: 'personal',
      metadata: {
        customer_id: 'cust_123',
        purpose: 'savings'
      }
    });
    
    console.log('Account created:', account.uuid);
    
    // Get account balances
    const balances = await client.accounts.getBalances(account.uuid);
    
    console.log('Current balances:');
    balances.data.balances.forEach(balance => {
      console.log(`${balance.asset_code}: ${balance.available_balance}`);
    });
    
    return account;
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

createAccountAndCheckBalance();
from finaegis import FinAegis
import os

client = FinAegis(
    api_key=os.environ['FINAEGIS_API_KEY'],
    base_url='https://api.finaegis.org/v2'
)

def create_account_and_check_balance():
    try:
        # Create a new account
        account = client.accounts.create(
            name='My Main Account',
            type='personal',
            metadata={
                'customer_id': 'cust_123',
                'purpose': 'savings'
            }
        )
        
        print(f'Account created: {account.uuid}')
        
        # Get account balances
        balances = client.accounts.get_balances(account.uuid)
        
        print('Current balances:')
        for balance in balances.data.balances:
            print(f'{balance.asset_code}: {balance.available_balance}')
        
        return account
    except Exception as error:
        print(f'Error: {error}')
        raise

create_account_and_check_balance()
require_once 'vendor/autoload.php';

use FinAegis\Client;

$client = new Client([
    'apiKey' => $_ENV['FINAEGIS_API_KEY'],
    'baseURL' => 'https://api.finaegis.org/v2'
]);

function createAccountAndCheckBalance($client) {
    try {
        // Create a new account
        $account = $client->accounts->create([
            'name' => 'My Main Account',
            'type' => 'personal',
            'metadata' => [
                'customer_id' => 'cust_123',
                'purpose' => 'savings'
            ]
        ]);
        
        echo "Account created: {$account->uuid}\n";
        
        // Get account balances
        $balances = $client->accounts->getBalances($account->uuid);
        
        echo "Current balances:\n";
        foreach ($balances->data->balances as $balance) {
            echo "{$balance->asset_code}: {$balance->available_balance}\n";
        }
        
        return $account;
    } catch (Exception $e) {
        echo "Error: {$e->getMessage()}\n";
        throw $e;
    }
}

createAccountAndCheckBalance($client);
# Create a new account
curl -X POST https://api.finaegis.org/v2/accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Main Account",
    "type": "personal",
    "metadata": {
      "customer_id": "cust_123",
      "purpose": "savings"
    }
  }'

# Response
{
  "data": {
    "uuid": "acct_1234567890abcdef",
    "name": "My Main Account",
    "type": "personal",
    "status": "active",
    "created_at": "2025-01-01T12:00:00Z"
  }
}

# Get account balances
curl -X GET https://api.finaegis.org/v2/accounts/acct_1234567890abcdef/balances \
  -H "Authorization: Bearer YOUR_API_KEY"

Simple Money Transfer

Transfer funds between accounts with automatic workflow processing

POST Workflow 
async function transferFunds(fromAccount, toAccount, amount) {
  try {
    const transfer = await client.transfers.create({
      from_account: fromAccount,
      to_account: toAccount,
      amount: amount,
      asset_code: 'USD',
      reference: 'Payment for services',
      workflow_enabled: true,
      metadata: {
        invoice_id: 'INV-2025-001',
        payment_type: 'service'
      }
    });
    
    console.log('Transfer initiated:', transfer.uuid);
    console.log('Status:', transfer.status);
    console.log('Workflow ID:', transfer.workflow_id);
    
    // Poll for completion
    const completed = await client.transfers.waitForCompletion(
      transfer.uuid, 
      { timeout: 30000 }
    );
    
    console.log('Transfer completed:', completed.status);
    return completed;
  } catch (error) {
    console.error('Transfer failed:', error.message);
    throw error;
  }
}

// Usage
transferFunds(
  'acct_1234567890',
  'acct_0987654321', 
  '100.00'
);
def transfer_funds(from_account, to_account, amount):
    try:
        transfer = client.transfers.create(
            from_account=from_account,
            to_account=to_account,
            amount=amount,
            asset_code='USD',
            reference='Payment for services',
            workflow_enabled=True,
            metadata={
                'invoice_id': 'INV-2025-001',
                'payment_type': 'service'
            }
        )
        
        print(f'Transfer initiated: {transfer.uuid}')
        print(f'Status: {transfer.status}')
        print(f'Workflow ID: {transfer.workflow_id}')
        
        # Poll for completion
        completed = client.transfers.wait_for_completion(
            transfer.uuid,
            timeout=30000
        )
        
        print(f'Transfer completed: {completed.status}')
        return completed
    except Exception as error:
        print(f'Transfer failed: {error}')
        raise

# Usage
transfer_funds(
    'acct_1234567890',
    'acct_0987654321',
    '100.00'
)
{
  "data": {
    "uuid": "txfr_abc123def456",
    "from_account": "acct_1234567890",
    "to_account": "acct_0987654321",
    "amount": "100.00",
    "asset_code": "USD",
    "status": "pending",
    "reference": "Payment for services",
    "workflow_id": "wf_789xyz012",
    "created_at": "2025-01-01T12:00:00Z",
    "estimated_completion": "2025-01-01T12:05:00Z",
    "metadata": {
      "invoice_id": "INV-2025-001",
      "payment_type": "service"
    },
    "fees": {
      "transfer_fee": "0.50",
      "currency": "USD"
    }
  }
}

List Account Transactions

Retrieve transaction history with pagination and filtering

GET Paginated 
async function getAccountTransactions(accountId, options = {}) {
  try {
    const transactions = await client.accounts.getTransactions(accountId, {
      limit: options.limit || 20,
      page: options.page || 1,
      type: options.type, // 'deposit', 'withdrawal', 'transfer'
      status: options.status, // 'pending', 'completed', 'failed'
      start_date: options.startDate,
      end_date: options.endDate,
      sort: options.sort || '-created_at' // - for descending
    });
    
    console.log(`Found ${transactions.meta.total} transactions`);
    console.log(`Showing page ${transactions.meta.current_page} of ${transactions.meta.last_page}`);
    
    transactions.data.forEach(tx => {
      console.log(`${tx.created_at}: ${tx.type} ${tx.amount} ${tx.asset_code} - ${tx.status}`);
    });
    
    return transactions;
  } catch (error) {
    console.error('Failed to fetch transactions:', error.message);
    throw error;
  }
}

// Usage examples
// Get all transactions
getAccountTransactions('acct_1234567890');

// Get withdrawals from last 30 days
getAccountTransactions('acct_1234567890', {
  type: 'withdrawal',
  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()
});
# Get all transactions for an account
curl -X GET "https://api.finaegis.org/v2/accounts/acct_1234567890/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get transactions with filters
curl -X GET "https://api.finaegis.org/v2/accounts/acct_1234567890/transactions?\
limit=20&\
page=1&\
type=withdrawal&\
status=completed&\
start_date=2025-01-01T00:00:00Z&\
end_date=2025-01-31T23:59:59Z&\
sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": [
    {
      "uuid": "tx_789xyz123abc",
      "account_uuid": "acct_1234567890",
      "type": "deposit",
      "amount": "500.00",
      "asset_code": "USD",
      "status": "completed",
      "reference": "Salary deposit",
      "created_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:30:05Z",
      "balance_after": "1500.00"
    },
    {
      "uuid": "tx_456def789ghi",
      "account_uuid": "acct_1234567890",
      "type": "withdrawal",
      "amount": "100.00",
      "asset_code": "USD",
      "status": "completed",
      "reference": "ATM withdrawal",
      "created_at": "2025-01-14T15:45:00Z",
      "completed_at": "2025-01-14T15:45:10Z",
      "balance_after": "1000.00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 95,
    "from": 1,
    "to": 20
  },
  "links": {
    "first": "https://api.finaegis.org/v2/accounts/acct_1234567890/transactions?page=1",
    "last": "https://api.finaegis.org/v2/accounts/acct_1234567890/transactions?page=5",
    "prev": null,
    "next": "https://api.finaegis.org/v2/accounts/acct_1234567890/transactions?page=2"
  }
}

Advanced Workflows

Multi-Currency Conversion with Transfer

Convert currency and transfer in one workflow

JavaScript Implementation 
async function convertAndTransfer(fromAccount, toAccount, amount, fromCurrency, toCurrency) {
  try {
    // Get current exchange rate
    const rate = await client.exchangeRates.get(fromCurrency, toCurrency);
    const convertedAmount = (parseFloat(amount) * rate.rate).toFixed(2);
    
    console.log(`Exchange rate: 1 ${fromCurrency} = ${rate.rate} ${toCurrency}`);
    console.log(`Converting ${amount} ${fromCurrency} to ${convertedAmount} ${toCurrency}`);
    
    // Create workflow for conversion + transfer
    const workflow = await client.workflows.create({
      type: 'currency_conversion_transfer',
      steps: [
        {
          type: 'currency_conversion',
          from_account: fromAccount,
          amount: amount,
          from_currency: fromCurrency,
          to_currency: toCurrency,
          max_slippage: 0.01 // 1% max slippage
        },
        {
          type: 'transfer',
          from_account: fromAccount,
          to_account: toAccount,
          amount: convertedAmount,
          asset_code: toCurrency,
          reference: 'Converted payment'
        }
      ],
      compensation_enabled: true
    });
    
    console.log('Workflow started:', workflow.uuid);
    
    // Monitor workflow progress
    const result = await client.workflows.monitor(workflow.uuid, {
      onProgress: (step) => console.log(`Step ${step.name}: ${step.status}`),
      timeout: 60000
    });
    
    return result;
  } catch (error) {
    console.error('Workflow failed:', error.message);
    
    // Check if compensation was executed
    if (error.compensation_executed) {
      console.log('Automatic rollback completed');
    }
    
    throw error;
  }
}

convertAndTransfer(
  'acct_source123', 
  'acct_dest456', 
  '1000.00', 
  'USD', 
  'EUR'
);

Webhooks

Setting Up Webhook Endpoints

Handle real-time events from FinAegis

Express.js Handler

const express = require('express');
const crypto = require('crypto');
const app = express();

// Middleware to verify webhook signatures
function verifyWebhookSignature(req, res, next) {
  const signature = req.headers['x-finaegis-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  next();
}

// Webhook endpoint
app.post('/webhooks/finaegis', 
  express.json(),
  verifyWebhookSignature,
  (req, res) => {
    const { event_type, data } = req.body;
    
    console.log(`Received webhook: ${event_type}`);
    
    switch (event_type) {
      case 'transfer.completed':
        handleTransferCompleted(data);
        break;
      case 'transfer.failed':
        handleTransferFailed(data);
        break;
      case 'account.balance_updated':
        handleBalanceUpdated(data);
        break;
      case 'workflow.completed':
        handleWorkflowCompleted(data);
        break;
      case 'workflow.compensation_executed':
        handleCompensationExecuted(data);
        break;
      default:
        console.log(`Unhandled event type: ${event_type}`);
    }
    
    res.status(200).send('OK');
  }
);

async function handleTransferCompleted(transfer) {
  console.log(`Transfer ${transfer.uuid} completed`);
  
  // Update your database
  await updateTransferStatus(transfer.uuid, 'completed');
  
  // Send notification to user
  await notifyUser(transfer.from_account, {
    type: 'transfer_completed',
    amount: transfer.amount,
    currency: transfer.asset_code,
    reference: transfer.reference
  });
}

async function handleWorkflowCompleted(workflow) {
  console.log(`Workflow ${workflow.uuid} completed successfully`);
  
  // Process completion logic
  await processWorkflowCompletion(workflow);
}

Webhook Configuration

// Configure webhook endpoints
async function setupWebhooks() {
  const webhook = await client.webhooks.create({
    url: 'https://yourapp.com/webhooks/finaegis',
    events: [
      'transfer.completed',
      'transfer.failed',
      'account.balance_updated',
      'workflow.completed',
      'workflow.failed',
      'workflow.compensation_executed'
    ],
    secret: process.env.WEBHOOK_SECRET,
    active: true
  });
  
  console.log('Webhook configured:', webhook.id);
  return webhook;
}

// Test webhook delivery
async function testWebhook(webhookId) {
  const result = await client.webhooks.test(webhookId, {
    event_type: 'test.webhook',
    data: { message: 'Test webhook delivery' }
  });
  
  console.log('Test result:', result.status);
}

AI Agent Integration

AI Banking Assistant Chat

Integrate intelligent banking conversations with context awareness

AI MCP 
import { FinAegisAI } from '@finaegis/ai-sdk';

const aiClient = new FinAegisAI({
  apiKey: process.env.FINAEGIS_API_KEY,
  conversationId: 'conv_' + Math.random().toString(36).substr(2, 9)
});

async function bankingConversation() {
  try {
    // Send a message to the AI agent
    const response = await aiClient.chat({
      message: "I need to transfer $500 to John Smith and check my balance",
      context: {
        user_id: 'user_123',
        account_id: 'acct_primary',
        session_type: 'web',
        authentication_level: 'mfa_verified'
      },
      options: {
        enable_tools: true,
        confidence_threshold: 0.8,
        human_approval_required: true
      }
    });
    
    console.log('AI Response:', response.content);
    console.log('Confidence:', response.confidence);
    console.log('Tools Used:', response.tools_used);
    
    // Handle tool actions
    if (response.requires_action) {
      for (const action of response.actions) {
        console.log(`Action Required: ${action.type}`);
        
        switch(action.type) {
          case 'transfer':
            // Execute transfer with human approval
            await executeTransferWithApproval(action.parameters);
            break;
          case 'balance_check':
            // Get and display balance
            const balance = await getAccountBalance(action.parameters.account_id);
            console.log(`Current balance: ${balance}`);
            break;
        }
      }
    }
    
    // Provide feedback
    await aiClient.feedback({
      message_id: response.message_id,
      rating: 5,
      feedback: "Helpful and accurate"
    });
    
    return response;
  } catch (error) {
    console.error('AI conversation failed:', error);
    throw error;
  }
}

// Handle streaming responses for real-time interaction
async function streamingChat() {
  const stream = await aiClient.chatStream({
    message: "Explain my recent transactions and spending patterns",
    enable_analysis: true
  });
  
  for await (const chunk of stream) {
    if (chunk.type === 'content') {
      process.stdout.write(chunk.text);
    } else if (chunk.type === 'tool_call') {
      console.log('\n[Analyzing with:', chunk.tool_name, ']');
    } else if (chunk.type === 'complete') {
      console.log('\n\nAnalysis complete');
      console.log('Insights:', chunk.insights);
    }
  }
}
from finaegis_ai import FinAegisAI
import asyncio
import uuid

ai_client = FinAegisAI(
    api_key=os.environ['FINAEGIS_API_KEY'],
    conversation_id=f'conv_{uuid.uuid4().hex[:9]}'
)

async def banking_conversation():
    try:
        # Send a message to the AI agent
        response = await ai_client.chat(
            message="I need to transfer $500 to John Smith and check my balance",
            context={
                'user_id': 'user_123',
                'account_id': 'acct_primary',
                'session_type': 'web',
                'authentication_level': 'mfa_verified'
            },
            options={
                'enable_tools': True,
                'confidence_threshold': 0.8,
                'human_approval_required': True
            }
        )
        
        print(f'AI Response: {response.content}')
        print(f'Confidence: {response.confidence}')
        print(f'Tools Used: {response.tools_used}')
        
        # Handle tool actions
        if response.requires_action:
            for action in response.actions:
                print(f'Action Required: {action.type}')
                
                if action.type == 'transfer':
                    # Execute transfer with human approval
                    await execute_transfer_with_approval(action.parameters)
                elif action.type == 'balance_check':
                    # Get and display balance
                    balance = await get_account_balance(action.parameters['account_id'])
                    print(f'Current balance: {balance}')
        
        # Provide feedback
        await ai_client.feedback(
            message_id=response.message_id,
            rating=5,
            feedback="Helpful and accurate"
        )
        
        return response
    except Exception as error:
        print(f'AI conversation failed: {error}')
        raise

# Handle streaming responses
async def streaming_chat():
    stream = await ai_client.chat_stream(
        message="Explain my recent transactions and spending patterns",
        enable_analysis=True
    )
    
    async for chunk in stream:
        if chunk.type == 'content':
            print(chunk.text, end='', flush=True)
        elif chunk.type == 'tool_call':
            print(f'\n[Analyzing with: {chunk.tool_name}]')
        elif chunk.type == 'complete':
            print('\n\nAnalysis complete')
            print(f'Insights: {chunk.insights}')

# Run the conversation
asyncio.run(banking_conversation())
{
  "message_id": "msg_abc123xyz",
  "conversation_id": "conv_def456",
  "content": "I'll help you transfer $500 to John Smith and check your balance. Let me process this for you.",
  "confidence": 0.92,
  "requires_action": true,
  "actions": [
    {
      "type": "transfer",
      "description": "Transfer $500 to John Smith",
      "parameters": {
        "amount": "500.00",
        "currency": "USD",
        "recipient": "John Smith",
        "recipient_account": "acct_john_smith_789",
        "reference": "Transfer to John Smith",
        "requires_approval": true
      },
      "confidence": 0.89
    },
    {
      "type": "balance_check",
      "description": "Check account balance",
      "parameters": {
        "account_id": "acct_primary",
        "include_pending": true
      },
      "confidence": 0.95
    }
  ],
  "tools_used": [
    "RecipientLookupTool",
    "TransferValidationTool",
    "AccountBalanceTool",
    "FraudDetectionTool"
  ],
  "context_retained": {
    "user_intent": "transfer_and_balance",
    "entities": ["John Smith", "$500", "balance"],
    "sentiment": "neutral",
    "urgency": "normal"
  },
  "metadata": {
    "processing_time_ms": 342,
    "model_version": "finaegis-ai-v2.5",
    "mcp_tools_available": 12,
    "workflow_id": "wf_banking_assist_789"
  }
}

AI-Driven Workflow Orchestration

Complex multi-step operations with AI decision making

Workflow AI
AI Customer Service Workflow 
// AI-powered customer service workflow
async function handleCustomerRequest(customerId, request) {
  const workflow = await aiClient.createWorkflow({
    type: 'customer_service',
    customer_id: customerId,
    initial_request: request,
    
    // AI configuration
    ai_config: {
      enable_sentiment_analysis: true,
      enable_intent_detection: true,
      enable_fraud_detection: true,
      confidence_threshold: 0.85
    },
    
    // Workflow steps with AI integration
    steps: [
      {
        name: 'analyze_request',
        type: 'ai_analysis',
        config: {
          detect_urgency: true,
          extract_entities: true,
          classify_intent: true
        }
      },
      {
        name: 'route_request',
        type: 'ai_routing',
        config: {
          routing_rules: 'dynamic',
          consider_agent_availability: true,
          skill_matching: true
        }
      },
      {
        name: 'process_request',
        type: 'ai_processing',
        config: {
          enable_tools: true,
          max_iterations: 5,
          human_in_loop: 'conditional'
        }
      },
      {
        name: 'quality_check',
        type: 'ai_validation',
        config: {
          check_compliance: true,
          verify_accuracy: true,
          sentiment_threshold: 0.7
        }
      }
    ],
    
    // Human-in-the-loop configuration
    human_intervention: {
      triggers: [
        { condition: 'confidence < 0.7', action: 'escalate_to_human' },
        { condition: 'fraud_score > 0.8', action: 'security_review' },
        { condition: 'amount > 10000', action: 'manual_approval' }
      ]
    }
  });
  
  // Monitor workflow progress
  workflow.on('step_complete', (step) => {
    console.log(`Step ${step.name} completed:`, step.result);
    
    if (step.ai_insights) {
      console.log('AI Insights:', step.ai_insights);
    }
  });
  
  workflow.on('human_intervention_required', async (intervention) => {
    console.log('Human intervention needed:', intervention.reason);
    
    // Get human decision
    const decision = await requestHumanDecision(intervention);
    workflow.resume(decision);
  });
  
  // Wait for completion
  const result = await workflow.execute();
  
  return {
    workflow_id: workflow.id,
    status: result.status,
    resolution: result.resolution,
    ai_summary: result.ai_summary,
    customer_satisfaction_prediction: result.satisfaction_score
  };
}

// Example usage
handleCustomerRequest('cust_123', 
  "I noticed unusual charges on my account and need help understanding them"
);

Try the AI Agent Live

Experience our banking AI assistant in action with a live demo

Launch Live Demo

MCP Tools Integration

MCP Tool Registration and Usage

Register custom banking tools for AI agents to use

MCP Tools 
// Register custom MCP tools for banking operations
import { MCPServer } from '@finaegis/mcp-sdk';

const mcpServer = new MCPServer({
  name: 'banking-tools',
  version: '1.0.0',
  description: 'Custom banking tools for AI agents'
});

// Register Account Balance Tool
mcpServer.registerTool({
  name: 'get_account_balance',
  description: 'Retrieve the current balance for a customer account',
  parameters: {
    type: 'object',
    properties: {
      account_id: {
        type: 'string',
        description: 'The account identifier'
      },
      include_pending: {
        type: 'boolean',
        description: 'Include pending transactions in balance',
        default: false
      },
      currency: {
        type: 'string',
        description: 'Currency code for balance display',
        default: 'USD'
      }
    },
    required: ['account_id']
  },
  handler: async (params) => {
    // Tool implementation
    const balance = await getAccountBalance(params.account_id);
    
    if (params.include_pending) {
      const pending = await getPendingTransactions(params.account_id);
      balance.pending = pending.reduce((sum, tx) => sum + tx.amount, 0);
    }
    
    return {
      account_id: params.account_id,
      available_balance: balance.available,
      current_balance: balance.current,
      pending_balance: balance.pending || 0,
      currency: params.currency,
      as_of: new Date().toISOString()
    };
  }
});

// Register Transfer Authorization Tool
mcpServer.registerTool({
  name: 'authorize_transfer',
  description: 'Authorize and initiate a money transfer between accounts',
  parameters: {
    type: 'object',
    properties: {
      from_account: { type: 'string', description: 'Source account ID' },
      to_account: { type: 'string', description: 'Destination account ID' },
      amount: { type: 'number', description: 'Transfer amount' },
      currency: { type: 'string', description: 'Currency code' },
      reference: { type: 'string', description: 'Transfer reference' },
      require_2fa: { type: 'boolean', default: true }
    },
    required: ['from_account', 'to_account', 'amount', 'currency']
  },
  handler: async (params) => {
    // Validate transfer
    const validation = await validateTransfer(params);
    
    if (!validation.is_valid) {
      return {
        success: false,
        error: validation.error,
        error_code: validation.error_code
      };
    }
    
    // Check 2FA if required
    if (params.require_2fa) {
      const twoFaStatus = await check2FA(params.from_account);
      if (!twoFaStatus.verified) {
        return {
          success: false,
          error: '2FA verification required',
          action_required: 'verify_2fa',
          verification_url: twoFaStatus.verification_url
        };
      }
    }
    
    // Execute transfer
    const transfer = await executeTransfer(params);
    
    return {
      success: true,
      transfer_id: transfer.id,
      status: transfer.status,
      estimated_completion: transfer.estimated_completion,
      fee: transfer.fee,
      exchange_rate: transfer.exchange_rate
    };
  }
});

// Register Fraud Detection Tool
mcpServer.registerTool({
  name: 'check_fraud_risk',
  description: 'Analyze transaction or activity for fraud risk',
  parameters: {
    type: 'object',
    properties: {
      transaction_data: {
        type: 'object',
        description: 'Transaction details to analyze'
      },
      customer_id: {
        type: 'string',
        description: 'Customer identifier'
      },
      check_type: {
        type: 'string',
        enum: ['transaction', 'login', 'account_change'],
        description: 'Type of fraud check'
      }
    },
    required: ['transaction_data', 'customer_id', 'check_type']
  },
  handler: async (params) => {
    const riskAnalysis = await analyzeFraudRisk(params);
    
    return {
      risk_score: riskAnalysis.score,
      risk_level: riskAnalysis.level, // low, medium, high, critical
      flags: riskAnalysis.flags,
      recommended_action: riskAnalysis.recommended_action,
      similar_patterns: riskAnalysis.similar_patterns,
      ml_confidence: riskAnalysis.confidence
    };
  }
});

// Start MCP server
mcpServer.start({
  port: 3001,
  enableLogging: true,
  rateLimiting: {
    enabled: true,
    maxRequests: 100,
    windowMs: 60000
  }
});

console.log('MCP Banking Tools Server started on port 3001');
// Using MCP tools in AI conversations
const aiClient = new FinAegisAI({
  apiKey: process.env.FINAEGIS_API_KEY,
  mcp_servers: [
    {
      url: 'http://localhost:3001',
      name: 'banking-tools',
      api_key: process.env.MCP_TOOLS_KEY
    }
  ]
});

// AI agent automatically discovers and uses available tools
async function intelligentBankingAssistant() {
  // List available tools
  const tools = await aiClient.getAvailableTools();
  console.log('Available MCP Tools:', tools.map(t => t.name));
  
  // Send a message that requires tool usage
  const response = await aiClient.chat({
    message: "Check my savings account balance and transfer $200 to checking",
    enable_tools: true,
    tool_preferences: {
      preferred_tools: ['get_account_balance', 'authorize_transfer'],
      auto_execute: false, // Require confirmation
      parallel_execution: true
    }
  });
  
  // AI automatically selects and uses appropriate tools
  console.log('AI Plan:', response.execution_plan);
  
  // Example execution plan:
  // 1. Use 'get_account_balance' for savings account
  // 2. Use 'get_account_balance' for checking account
  // 3. Validate sufficient funds
  // 4. Use 'authorize_transfer' to move money
  
  // Review tool calls before execution
  for (const toolCall of response.tool_calls) {
    console.log(`Tool: ${toolCall.tool_name}`);
    console.log(`Parameters:`, toolCall.parameters);
    console.log(`Reason: ${toolCall.reasoning}`);
    
    // Approve or modify tool call
    const approved = await confirmToolExecution(toolCall);
    
    if (approved) {
      const result = await aiClient.executeTool(toolCall);
      console.log(`Result:`, result);
    }
  }
  
  return response;
}

// Advanced: Custom tool selection logic
async function customToolStrategy() {
  const response = await aiClient.chat({
    message: "Analyze my spending and suggest budget improvements",
    tool_strategy: {
      // Custom tool selection function
      selector: async (availableTools, context) => {
        const relevantTools = [];
        
        // Select tools based on context
        if (context.intent.includes('spending')) {
          relevantTools.push('get_transaction_history');
          relevantTools.push('analyze_spending_patterns');
        }
        
        if (context.intent.includes('budget')) {
          relevantTools.push('create_budget_plan');
          relevantTools.push('spending_insights');
        }
        
        return relevantTools;
      },
      
      // Tool execution order
      execution_order: 'dependency_based', // or 'parallel', 'sequential'
      
      // Result aggregation
      aggregation: 'smart_summary' // or 'raw', 'structured'
    }
  });
  
  return response;
}

// Monitor tool performance
aiClient.on('tool_executed', (event) => {
  console.log(`Tool ${event.tool_name} executed in ${event.duration_ms}ms`);
  console.log(`Success: ${event.success}`);
  
  // Track tool usage metrics
  trackToolMetrics({
    tool: event.tool_name,
    duration: event.duration_ms,
    success: event.success,
    timestamp: event.timestamp
  });
});
{
  "name": "finaegis-banking-tools",
  "version": "1.0.0",
  "description": "MCP tools for FinAegis banking operations",
  "author": "FinAegis",
  "license": "MIT",
  "server": {
    "command": "node",
    "args": ["./mcp-server.js"],
    "env": {
      "NODE_ENV": "production",
      "MCP_PORT": "3001"
    }
  },
  "tools": [
    {
      "name": "get_account_balance",
      "description": "Retrieve account balance with pending transactions",
      "category": "account_management",
      "rate_limit": 100,
      "cache_ttl": 60
    },
    {
      "name": "authorize_transfer",
      "description": "Authorize money transfers between accounts",
      "category": "transactions",
      "requires_auth": true,
      "requires_2fa": true,
      "rate_limit": 20
    },
    {
      "name": "check_fraud_risk",
      "description": "Analyze activities for fraud risk",
      "category": "security",
      "ml_enabled": true,
      "real_time": true
    },
    {
      "name": "get_transaction_history",
      "description": "Retrieve transaction history with filtering",
      "category": "account_management",
      "pagination": true,
      "max_results": 1000
    },
    {
      "name": "analyze_spending_patterns",
      "description": "AI-powered spending analysis",
      "category": "insights",
      "ml_model": "spending-analyzer-v2"
    },
    {
      "name": "create_budget_plan",
      "description": "Generate personalized budget recommendations",
      "category": "financial_planning",
      "personalization": true
    }
  ],
  "capabilities": {
    "parallel_execution": true,
    "batch_operations": true,
    "streaming": true,
    "webhooks": true,
    "rate_limiting": {
      "enabled": true,
      "default_limit": 100,
      "window": "1m"
    }
  },
  "security": {
    "authentication": "api_key",
    "encryption": "tls_1_3",
    "audit_logging": true,
    "pii_masking": true
  },
  "monitoring": {
    "metrics_endpoint": "/metrics",
    "health_endpoint": "/health",
    "logging_level": "info"
  }
}

Complex MCP Workflow Integration

Multi-tool orchestration for complex banking operations

Advanced
Loan Application Workflow with MCP 
// Complex loan application workflow using multiple MCP tools
async function processLoanApplication(customerId, loanDetails) {
  const workflow = await aiClient.createWorkflow({
    type: 'loan_application',
    mcp_enabled: true,
    
    stages: [
      {
        name: 'eligibility_check',
        tools: [
          'get_credit_score',
          'verify_income',
          'check_debt_ratio',
          'analyze_bank_statements'
        ],
        parallel: true,
        timeout: 30000
      },
      {
        name: 'risk_assessment',
        tools: [
          'calculate_risk_score',
          'check_fraud_history',
          'analyze_collateral',
          'market_analysis'
        ],
        ai_decision: {
          model: 'risk-assessment-v3',
          confidence_required: 0.85
        }
      },
      {
        name: 'offer_generation',
        tools: [
          'calculate_interest_rate',
          'generate_loan_terms',
          'prepare_documentation'
        ],
        human_review: {
          required_if: 'loan_amount > 100000',
          department: 'credit_risk'
        }
      },
      {
        name: 'approval_process',
        tools: [
          'final_verification',
          'compliance_check',
          'generate_contract',
          'setup_disbursement'
        ],
        sequential: true
      }
    ],
    
    compensation_strategy: {
      enabled: true,
      checkpoints: ['eligibility_check', 'risk_assessment'],
      rollback_actions: {
        'approval_process': ['cancel_contract', 'release_funds_hold']
      }
    }
  });
  
  // Execute workflow with progress monitoring
  workflow.on('stage_start', (stage) => {
    console.log(`Starting stage: ${stage.name}`);
  });
  
  workflow.on('tool_execution', (tool) => {
    console.log(`Executing MCP tool: ${tool.name}`);
    console.log(`Input parameters:`, tool.parameters);
  });
  
  workflow.on('ai_decision', (decision) => {
    console.log(`AI Decision: ${decision.outcome}`);
    console.log(`Confidence: ${decision.confidence}`);
    console.log(`Reasoning:`, decision.explanation);
  });
  
  workflow.on('human_review_required', async (review) => {
    console.log(`Human review needed: ${review.reason}`);
    const decision = await requestHumanReview(review);
    workflow.continueWithDecision(decision);
  });
  
  try {
    const result = await workflow.execute({
      customer_id: customerId,
      loan_details: loanDetails
    });
    
    console.log('Loan application processed successfully');
    console.log('Decision:', result.decision);
    console.log('Offer:', result.offer);
    
    // Send notification to customer
    await notifyCustomer(customerId, result);
    
    return result;
  } catch (error) {
    console.error('Workflow failed:', error);
    
    // Check if compensation was executed
    if (error.compensation_executed) {
      console.log('Rollback completed successfully');
    }
    
    throw error;
  }
}

// Usage
processLoanApplication('cust_456', {
  loan_type: 'personal',
  amount: 50000,
  term_months: 36,
  purpose: 'debt_consolidation'
});

Error Handling

Robust Error Handling with Retries

Handle failures gracefully with automatic retries

Complete Error Handling Implementation 
class FinAegisWrapper {
  constructor(apiKey, options = {}) {
    this.client = new FinAegis({
      apiKey,
      baseURL: options.baseURL || 'https://api.finaegis.org/v2'
    });
    
    this.retryOptions = {
      maxRetries: options.maxRetries || 3,
      backoffMultiplier: options.backoffMultiplier || 2,
      initialDelay: options.initialDelay || 1000
    };
  }
  
  async withRetry(operation, context = '') {
    let lastError;
    let delay = this.retryOptions.initialDelay;
    
    for (let attempt = 1; attempt <= this.retryOptions.maxRetries + 1; attempt++) {
      try {
        return await operation();
      } catch (error) {
        lastError = error;
        
        console.log(`Attempt ${attempt} failed for ${context}:`, error.message);
        
        // Don't retry on client errors (4xx)
        if (error.status >= 400 && error.status < 500) {
          throw error;
        }
        
        // Don't retry on the last attempt
        if (attempt > this.retryOptions.maxRetries) {
          break;
        }
        
        // Wait before retrying
        console.log(`Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= this.retryOptions.backoffMultiplier;
      }
    }
    
    throw lastError;
  }
  
  async createTransfer(transferData) {
    return this.withRetry(
      () => this.client.transfers.create(transferData),
      `transfer creation`
    );
  }
  
  async getAccountBalance(accountId) {
    return this.withRetry(
      () => this.client.accounts.getBalances(accountId),
      `balance query for ${accountId}`
    );
  }
  
  async executeWithFallback(primaryOperation, fallbackOperation, context) {
    try {
      return await this.withRetry(primaryOperation, context);
    } catch (primaryError) {
      console.log(`Primary operation failed, trying fallback:`, primaryError.message);
      
      try {
        return await this.withRetry(fallbackOperation, `${context} (fallback)`);
      } catch (fallbackError) {
        console.error('Both primary and fallback operations failed');
        throw new Error(`All operations failed. Primary: ${primaryError.message}, Fallback: ${fallbackError.message}`);
      }
    }
  }
}

// Usage example
const finAegis = new FinAegisWrapper(process.env.FINAEGIS_API_KEY, {
  environment: 'production',
  maxRetries: 3,
  backoffMultiplier: 2,
  initialDelay: 1000
});

async function robustTransfer(fromAccount, toAccount, amount) {
  try {
    // Primary: Direct transfer
    const primaryTransfer = () => finAegis.createTransfer({
      from_account: fromAccount,
      to_account: toAccount,
      amount: amount,
      asset_code: 'USD',
      workflow_enabled: true
    });
    
    // Fallback: Transfer via intermediate account
    const fallbackTransfer = () => finAegis.createTransfer({
      from_account: fromAccount,
      to_account: toAccount,
      amount: amount,
      asset_code: 'USD',
      workflow_enabled: true,
      routing: 'alternative'
    });
    
    const result = await finAegis.executeWithFallback(
      primaryTransfer,
      fallbackTransfer,
      'USD transfer'
    );
    
    console.log('Transfer successful:', result.uuid);
    return result;
    
  } catch (error) {
    console.error('Transfer completely failed:', error.message);
    
    // Log for monitoring
    await logTransferFailure({
      fromAccount,
      toAccount,
      amount,
      error: error.message,
      timestamp: new Date().toISOString()
    });
    
    throw error;
  }
}

Start Building Today

Use these examples as a starting point for your FinAegis integration.

Get API Keys API Documentation