Code Examples

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'
});

Cross-Chain & DeFi

Cross-Chain Bridge: Quote and Initiate

Get a bridge quote across chains (Wormhole, LayerZero, Axelar) and initiate the transfer

v3.0 POST

# Step 1: Get a bridge quote
curl -X POST https://api.finaegis.org/api/v1/crosschain/bridge/quote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_chain": "ethereum",
    "destination_chain": "polygon",
    "token": "USDC",
    "amount": "1000.00",
    "preferred_bridge": "wormhole"
  }'

# Step 2: Initiate the bridge transfer using the quote_id
curl -X POST https://api.finaegis.org/api/v1/crosschain/bridge/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "quote_br_abc123def456",
    "sender_address": "0x1234...abcd",
    "recipient_address": "0x5678...efgh",
    "slippage_tolerance": 0.005,
    "deadline_minutes": 30
  }'

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

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

async function bridgeTokens(sourceChain, destChain, token, amount) {
  try {
    // Step 1: Get a bridge quote comparing protocols
    const quote = await client.crosschain.bridge.quote({
      source_chain: sourceChain,
      destination_chain: destChain,
      token: token,
      amount: amount,
      preferred_bridge: 'wormhole' // or 'layerzero', 'axelar'
    });

    console.log('Bridge Quote:');
    console.log(`  Protocol: ${quote.data.bridge_protocol}`);
    console.log(`  Estimated output: ${quote.data.estimated_receive_amount} ${token}`);
    console.log(`  Fee: ${quote.data.fee_amount} ${quote.data.fee_currency}`);
    console.log(`  Estimated time: ${quote.data.estimated_duration_seconds}s`);

    // Step 2: Initiate the bridge transfer
    const transfer = await client.crosschain.bridge.initiate({
      quote_id: quote.data.quote_id,
      sender_address: '0x1234...abcd',
      recipient_address: '0x5678...efgh',
      slippage_tolerance: 0.005,
      deadline_minutes: 30
    });

    console.log('Bridge initiated:', transfer.data.bridge_tx_id);
    console.log('Status:', transfer.data.status);

    return transfer;
  } catch (error) {
    console.error('Bridge failed:', error.message);
    throw error;
  }
}

// Bridge 1000 USDC from Ethereum to Polygon
bridgeTokens('ethereum', 'polygon', 'USDC', '1000.00');

from finaegis import FinAegis
import os

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

def bridge_tokens(source_chain, dest_chain, token, amount):
    try:
        # Step 1: Get a bridge quote
        quote = client.crosschain.bridge.quote(
            source_chain=source_chain,
            destination_chain=dest_chain,
            token=token,
            amount=amount,
            preferred_bridge='wormhole'
        )

        print(f'Bridge Quote:')
        print(f'  Protocol: {quote.data.bridge_protocol}')
        print(f'  Estimated output: {quote.data.estimated_receive_amount} {token}')
        print(f'  Fee: {quote.data.fee_amount} {quote.data.fee_currency}')
        print(f'  Estimated time: {quote.data.estimated_duration_seconds}s')

        # Step 2: Initiate the bridge transfer
        transfer = client.crosschain.bridge.initiate(
            quote_id=quote.data.quote_id,
            sender_address='0x1234...abcd',
            recipient_address='0x5678...efgh',
            slippage_tolerance=0.005,
            deadline_minutes=30
        )

        print(f'Bridge initiated: {transfer.data.bridge_tx_id}')
        print(f'Status: {transfer.data.status}')

        return transfer
    except Exception as error:
        print(f'Bridge failed: {error}')
        raise

# Bridge 1000 USDC from Ethereum to Polygon
bridge_tokens('ethereum', 'polygon', 'USDC', '1000.00')

// POST /api/v1/crosschain/bridge/quote response
{
  "data": {
    "quote_id": "quote_br_abc123def456",
    "bridge_protocol": "wormhole",
    "source_chain": "ethereum",
    "destination_chain": "polygon",
    "token": "USDC",
    "input_amount": "1000.00",
    "estimated_receive_amount": "998.50",
    "fee_amount": "1.50",
    "fee_currency": "USDC",
    "exchange_rate": "1.0000",
    "estimated_duration_seconds": 180,
    "quote_expires_at": "2026-01-15T12:15:00Z",
    "alternative_quotes": [
      {
        "bridge_protocol": "layerzero",
        "estimated_receive_amount": "997.80",
        "fee_amount": "2.20",
        "estimated_duration_seconds": 120
      },
      {
        "bridge_protocol": "axelar",
        "estimated_receive_amount": "998.00",
        "fee_amount": "2.00",
        "estimated_duration_seconds": 240
      }
    ]
  }
}

// POST /api/v1/crosschain/bridge/initiate response
{
  "data": {
    "bridge_tx_id": "btx_xyz789012345",
    "quote_id": "quote_br_abc123def456",
    "status": "pending",
    "source_chain": "ethereum",
    "destination_chain": "polygon",
    "source_tx_hash": null,
    "destination_tx_hash": null,
    "sender_address": "0x1234...abcd",
    "recipient_address": "0x5678...efgh",
    "amount": "1000.00",
    "token": "USDC",
    "bridge_protocol": "wormhole",
    "created_at": "2026-01-15T12:05:30Z",
    "estimated_completion_at": "2026-01-15T12:08:30Z"
  }
}

DeFi Swap: Quote and Execute

Aggregate DEX quotes (Uniswap, Curve, SushiSwap) and execute optimal swaps

v3.0 POST

# Step 1: Get a swap quote with DEX aggregation
curl -X POST https://api.finaegis.org/api/v1/defi/swap/quote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "token_in": "WETH",
    "token_out": "USDC",
    "amount_in": "2.5",
    "slippage_tolerance": 0.005,
    "dex_sources": ["uniswap_v3", "curve", "sushiswap"]
  }'

# Step 2: Execute the swap with the best route
curl -X POST https://api.finaegis.org/api/v1/defi/swap/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "quote_sw_def456ghi789",
    "wallet_address": "0xABCD...1234",
    "max_gas_price_gwei": 50,
    "deadline_minutes": 20
  }'

async function swapTokens(chain, tokenIn, tokenOut, amountIn) {
  try {
    // Step 1: Get aggregated swap quote from multiple DEXes
    const quote = await client.defi.swap.quote({
      chain: chain,
      token_in: tokenIn,
      token_out: tokenOut,
      amount_in: amountIn,
      slippage_tolerance: 0.005,
      dex_sources: ['uniswap_v3', 'curve', 'sushiswap']
    });

    console.log('Swap Quote:');
    console.log(`  Best DEX: ${quote.data.best_route.dex}`);
    console.log(`  Input: ${amountIn} ${tokenIn}`);
    console.log(`  Output: ${quote.data.estimated_output} ${tokenOut}`);
    console.log(`  Price impact: ${quote.data.price_impact_percent}%`);
    console.log(`  Gas estimate: ${quote.data.estimated_gas_usd} USD`);

    // Step 2: Execute the swap
    const execution = await client.defi.swap.execute({
      quote_id: quote.data.quote_id,
      wallet_address: '0xABCD...1234',
      max_gas_price_gwei: 50,
      deadline_minutes: 20
    });

    console.log('Swap executed:', execution.data.tx_hash);
    console.log('Status:', execution.data.status);

    return execution;
  } catch (error) {
    console.error('Swap failed:', error.message);
    throw error;
  }
}

// Swap 2.5 WETH for USDC on Ethereum
swapTokens('ethereum', 'WETH', 'USDC', '2.5');

def swap_tokens(chain, token_in, token_out, amount_in):
    try:
        # Step 1: Get aggregated swap quote
        quote = client.defi.swap.quote(
            chain=chain,
            token_in=token_in,
            token_out=token_out,
            amount_in=amount_in,
            slippage_tolerance=0.005,
            dex_sources=['uniswap_v3', 'curve', 'sushiswap']
        )

        print(f'Swap Quote:')
        print(f'  Best DEX: {quote.data.best_route.dex}')
        print(f'  Input: {amount_in} {token_in}')
        print(f'  Output: {quote.data.estimated_output} {token_out}')
        print(f'  Price impact: {quote.data.price_impact_percent}%')
        print(f'  Gas estimate: {quote.data.estimated_gas_usd} USD')

        # Step 2: Execute the swap
        execution = client.defi.swap.execute(
            quote_id=quote.data.quote_id,
            wallet_address='0xABCD...1234',
            max_gas_price_gwei=50,
            deadline_minutes=20
        )

        print(f'Swap executed: {execution.data.tx_hash}')
        print(f'Status: {execution.data.status}')

        return execution
    except Exception as error:
        print(f'Swap failed: {error}')
        raise

# Swap 2.5 WETH for USDC on Ethereum
swap_tokens('ethereum', 'WETH', 'USDC', '2.5')

// POST /api/v1/defi/swap/quote response
{
  "data": {
    "quote_id": "quote_sw_def456ghi789",
    "chain": "ethereum",
    "token_in": "WETH",
    "token_out": "USDC",
    "amount_in": "2.5",
    "estimated_output": "4875.32",
    "price_impact_percent": "0.12",
    "estimated_gas_usd": "8.45",
    "best_route": {
      "dex": "uniswap_v3",
      "path": ["WETH", "USDC"],
      "pools": ["0x8ad5...pool1"],
      "fee_tier": "0.05%"
    },
    "alternative_routes": [
      {
        "dex": "curve",
        "estimated_output": "4870.18",
        "price_impact_percent": "0.15"
      },
      {
        "dex": "sushiswap",
        "estimated_output": "4865.90",
        "price_impact_percent": "0.18"
      }
    ],
    "quote_expires_at": "2026-01-15T12:10:00Z"
  }
}

// POST /api/v1/defi/swap/execute response
{
  "data": {
    "swap_id": "swap_mno345pqr678",
    "quote_id": "quote_sw_def456ghi789",
    "status": "submitted",
    "tx_hash": "0x9f8e7d6c5b4a3...transaction_hash",
    "chain": "ethereum",
    "token_in": "WETH",
    "token_out": "USDC",
    "amount_in": "2.5",
    "expected_output": "4875.32",
    "dex": "uniswap_v3",
    "gas_price_gwei": "35",
    "created_at": "2026-01-15T12:06:00Z"
  }
}

RegTech & Compliance

Travel Rule Compliance Check

Validate FATF Travel Rule compliance before executing cross-border or virtual asset transfers

v2.8 POST

# Run a Travel Rule compliance check before a transfer
curl -X POST https://api.finaegis.org/api/v1/regtech/travel-rule/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_id": "txfr_abc123def456",
    "originator": {
      "name": "Alice Johnson",
      "account_number": "acct_1234567890",
      "institution_name": "FinAegis",
      "institution_country": "US"
    },
    "beneficiary": {
      "name": "Bob Smith",
      "account_number": "ext_0987654321",
      "institution_name": "Partner Bank",
      "institution_country": "DE"
    },
    "transfer_details": {
      "amount": "15000.00",
      "currency": "USD",
      "asset_type": "fiat",
      "purpose": "business_payment"
    },
    "jurisdiction": "EU"
  }'

async function checkTravelRuleCompliance(transferData) {
  try {
    const result = await client.regtech.travelRule.check({
      transfer_id: transferData.transferId,
      originator: {
        name: 'Alice Johnson',
        account_number: transferData.fromAccount,
        institution_name: 'FinAegis',
        institution_country: 'US'
      },
      beneficiary: {
        name: transferData.recipientName,
        account_number: transferData.toAccount,
        institution_name: transferData.recipientInstitution,
        institution_country: transferData.recipientCountry
      },
      transfer_details: {
        amount: transferData.amount,
        currency: transferData.currency,
        asset_type: transferData.assetType || 'fiat',
        purpose: transferData.purpose || 'business_payment'
      },
      jurisdiction: transferData.jurisdiction || 'EU'
    });

    console.log('Travel Rule Check:');
    console.log(`  Compliant: ${result.data.is_compliant}`);
    console.log(`  Risk level: ${result.data.risk_level}`);
    console.log(`  Jurisdiction: ${result.data.applicable_jurisdiction}`);

    if (!result.data.is_compliant) {
      console.log('  Issues:');
      result.data.compliance_issues.forEach(issue => {
        console.log(`    - ${issue.code}: ${issue.description}`);
      });
    }

    return result;
  } catch (error) {
    console.error('Compliance check failed:', error.message);
    throw error;
  }
}

// Check compliance before a cross-border transfer
checkTravelRuleCompliance({
  transferId: 'txfr_abc123def456',
  fromAccount: 'acct_1234567890',
  recipientName: 'Bob Smith',
  toAccount: 'ext_0987654321',
  recipientInstitution: 'Partner Bank',
  recipientCountry: 'DE',
  amount: '15000.00',
  currency: 'USD',
  jurisdiction: 'EU'
});

def check_travel_rule_compliance(transfer_data):
    try:
        result = client.regtech.travel_rule.check(
            transfer_id=transfer_data['transfer_id'],
            originator={
                'name': 'Alice Johnson',
                'account_number': transfer_data['from_account'],
                'institution_name': 'FinAegis',
                'institution_country': 'US'
            },
            beneficiary={
                'name': transfer_data['recipient_name'],
                'account_number': transfer_data['to_account'],
                'institution_name': transfer_data['recipient_institution'],
                'institution_country': transfer_data['recipient_country']
            },
            transfer_details={
                'amount': transfer_data['amount'],
                'currency': transfer_data['currency'],
                'asset_type': transfer_data.get('asset_type', 'fiat'),
                'purpose': transfer_data.get('purpose', 'business_payment')
            },
            jurisdiction=transfer_data.get('jurisdiction', 'EU')
        )

        print(f'Travel Rule Check:')
        print(f'  Compliant: {result.data.is_compliant}')
        print(f'  Risk level: {result.data.risk_level}')
        print(f'  Jurisdiction: {result.data.applicable_jurisdiction}')

        if not result.data.is_compliant:
            print('  Issues:')
            for issue in result.data.compliance_issues:
                print(f'    - {issue.code}: {issue.description}')

        return result
    except Exception as error:
        print(f'Compliance check failed: {error}')
        raise

# Check compliance before a cross-border transfer
check_travel_rule_compliance({
    'transfer_id': 'txfr_abc123def456',
    'from_account': 'acct_1234567890',
    'recipient_name': 'Bob Smith',
    'to_account': 'ext_0987654321',
    'recipient_institution': 'Partner Bank',
    'recipient_country': 'DE',
    'amount': '15000.00',
    'currency': 'USD',
    'jurisdiction': 'EU'
})

{
  "data": {
    "check_id": "trc_mno345pqr678",
    "transfer_id": "txfr_abc123def456",
    "is_compliant": true,
    "risk_level": "low",
    "applicable_jurisdiction": "EU",
    "applicable_regulations": [
      "FATF_Recommendation_16",
      "EU_Transfer_of_Funds_Regulation",
      "MiCA_Article_76"
    ],
    "originator_verified": true,
    "beneficiary_verified": true,
    "threshold_analysis": {
      "amount_usd": "15000.00",
      "exceeds_threshold": true,
      "threshold_amount": "1000.00",
      "full_identification_required": true
    },
    "sanctions_screening": {
      "originator_cleared": true,
      "beneficiary_cleared": true,
      "screening_provider": "internal",
      "screened_at": "2026-01-15T12:00:05Z"
    },
    "compliance_issues": [],
    "recommendations": [
      "Enhanced due diligence recommended for transfers above 10000 USD"
    ],
    "checked_at": "2026-01-15T12:00:05Z",
    "valid_until": "2026-01-15T12:30:05Z"
  }
}

BaaS & Partner API

BaaS Partner Onboarding

Onboard a new partner organization onto the Banking-as-a-Service platform with API keys and SDK access

v2.9 POST

# Onboard a new BaaS partner
curl -X POST https://api.finaegis.org/api/v1/partner/onboard \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "Acme Fintech",
    "contact_email": "[email protected]",
    "tier": "growth",
    "modules": ["accounts", "transfers", "compliance", "crosschain"],
    "sdk_languages": ["typescript", "python"],
    "webhook_url": "https://acmefintech.com/webhooks/finaegis",
    "ip_whitelist": ["203.0.113.0/24"],
    "rate_limit_override": 5000,
    "metadata": {
      "use_case": "neobank",
      "expected_monthly_volume": "500000"
    }
  }'

async function onboardPartner(partnerDetails) {
  try {
    const partner = await client.partner.onboard({
      organization_name: partnerDetails.name,
      contact_email: partnerDetails.email,
      tier: partnerDetails.tier || 'growth', // starter, growth, enterprise
      modules: partnerDetails.modules,
      sdk_languages: partnerDetails.sdkLanguages || ['typescript', 'python'],
      webhook_url: partnerDetails.webhookUrl,
      ip_whitelist: partnerDetails.ipWhitelist || [],
      rate_limit_override: partnerDetails.rateLimit,
      metadata: partnerDetails.metadata || {}
    });

    console.log('Partner Onboarded:');
    console.log(`  Partner ID: ${partner.data.partner_id}`);
    console.log(`  API Key: ${partner.data.api_credentials.api_key}`);
    console.log(`  Sandbox Key: ${partner.data.api_credentials.sandbox_key}`);
    console.log(`  Tier: ${partner.data.tier}`);
    console.log(`  SDK Download URLs:`);
    partner.data.sdk_packages.forEach(sdk => {
      console.log(`    ${sdk.language}: ${sdk.download_url}`);
    });

    return partner;
  } catch (error) {
    console.error('Partner onboarding failed:', error.message);
    throw error;
  }
}

// Onboard a new fintech partner
onboardPartner({
  name: 'Acme Fintech',
  email: '[email protected]',
  tier: 'growth',
  modules: ['accounts', 'transfers', 'compliance', 'crosschain'],
  sdkLanguages: ['typescript', 'python'],
  webhookUrl: 'https://acmefintech.com/webhooks/finaegis',
  ipWhitelist: ['203.0.113.0/24'],
  rateLimit: 5000,
  metadata: {
    use_case: 'neobank',
    expected_monthly_volume: '500000'
  }
});

def onboard_partner(partner_details):
    try:
        partner = client.partner.onboard(
            organization_name=partner_details['name'],
            contact_email=partner_details['email'],
            tier=partner_details.get('tier', 'growth'),
            modules=partner_details['modules'],
            sdk_languages=partner_details.get('sdk_languages', ['typescript', 'python']),
            webhook_url=partner_details['webhook_url'],
            ip_whitelist=partner_details.get('ip_whitelist', []),
            rate_limit_override=partner_details.get('rate_limit'),
            metadata=partner_details.get('metadata', {})
        )

        print(f'Partner Onboarded:')
        print(f'  Partner ID: {partner.data.partner_id}')
        print(f'  API Key: {partner.data.api_credentials.api_key}')
        print(f'  Sandbox Key: {partner.data.api_credentials.sandbox_key}')
        print(f'  Tier: {partner.data.tier}')
        print(f'  SDK Download URLs:')
        for sdk in partner.data.sdk_packages:
            print(f'    {sdk.language}: {sdk.download_url}')

        return partner
    except Exception as error:
        print(f'Partner onboarding failed: {error}')
        raise

# Onboard a new fintech partner
onboard_partner({
    'name': 'Acme Fintech',
    'email': '[email protected]',
    'tier': 'growth',
    'modules': ['accounts', 'transfers', 'compliance', 'crosschain'],
    'sdk_languages': ['typescript', 'python'],
    'webhook_url': 'https://acmefintech.com/webhooks/finaegis',
    'ip_whitelist': ['203.0.113.0/24'],
    'rate_limit': 5000,
    'metadata': {
        'use_case': 'neobank',
        'expected_monthly_volume': '500000'
    }
})

{
  "data": {
    "partner_id": "partner_acme_abc123",
    "organization_name": "Acme Fintech",
    "status": "active",
    "tier": "growth",
    "modules_enabled": [
      "accounts",
      "transfers",
      "compliance",
      "crosschain"
    ],
    "api_credentials": {
      "api_key": "pk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
      "sandbox_key": "pk_test_xxxxxxxxxxxxxxxxxxxxxxxx",
      "webhook_secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "sdk_packages": [
      {
        "language": "typescript",
        "version": "3.0.0",
        "package_name": "@finaegis/sdk",
        "download_url": "https://sdk.finaegis.org/packages/typescript/finaegis-sdk-3.0.0.tgz",
        "docs_url": "https://docs.finaegis.org/sdk/typescript"
      },
      {
        "language": "python",
        "version": "3.0.0",
        "package_name": "finaegis-sdk",
        "download_url": "https://sdk.finaegis.org/packages/python/finaegis-sdk-3.0.0.tar.gz",
        "docs_url": "https://docs.finaegis.org/sdk/python"
      }
    ],
    "rate_limits": {
      "requests_per_minute": 5000,
      "burst_limit": 500
    },
    "sandbox_url": "https://sandbox.finaegis.org",
    "dashboard_url": "https://partners.finaegis.org/acme-fintech",
    "created_at": "2026-01-15T12:00:00Z",
    "onboarding_checklist": {
      "api_key_generated": true,
      "webhook_configured": true,
      "sdk_generated": true,
      "sandbox_tested": false,
      "compliance_review": "pending"
    }
  }
}

AI Transaction Query

AI-Powered Transaction Search

Query transactions using natural language -- the AI engine translates to structured filters

v2.8 POST AI

# Query transactions with natural language
curl -X POST https://api.finaegis.org/api/v1/ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me all cross-chain transfers over $5000 in the last 7 days that had compliance flags",
    "account_id": "acct_1234567890",
    "options": {
      "include_analytics": true,
      "include_risk_scores": true,
      "max_results": 50,
      "format": "detailed"
    }
  }'

async function queryTransactionsWithAI(naturalLanguageQuery, accountId) {
  try {
    const result = await client.ai.transactions({
      query: naturalLanguageQuery,
      account_id: accountId,
      options: {
        include_analytics: true,
        include_risk_scores: true,
        max_results: 50,
        format: 'detailed'
      }
    });

    console.log('AI Query Interpretation:');
    console.log(`  Parsed filters: ${JSON.stringify(result.data.interpreted_query)}`);
    console.log(`  Confidence: ${result.data.interpretation_confidence}`);
    console.log(`  Results found: ${result.data.total_results}`);

    result.data.transactions.forEach(tx => {
      console.log(`  ${tx.created_at}: ${tx.type} ${tx.amount} ${tx.currency}`);
      console.log(`    Status: ${tx.status} | Risk: ${tx.risk_score}`);
      if (tx.compliance_flags.length > 0) {
        console.log(`    Flags: ${tx.compliance_flags.join(', ')}`);
      }
    });

    if (result.data.analytics) {
      console.log('\nAnalytics Summary:');
      console.log(`  Total volume: ${result.data.analytics.total_volume}`);
      console.log(`  Average amount: ${result.data.analytics.avg_amount}`);
      console.log(`  Flagged count: ${result.data.analytics.flagged_count}`);
    }

    return result;
  } catch (error) {
    console.error('AI query failed:', error.message);
    throw error;
  }
}

// Natural language transaction search
queryTransactionsWithAI(
  'Show me all cross-chain transfers over $5000 in the last 7 days that had compliance flags',
  'acct_1234567890'
);

def query_transactions_with_ai(natural_language_query, account_id):
    try:
        result = client.ai.transactions(
            query=natural_language_query,
            account_id=account_id,
            options={
                'include_analytics': True,
                'include_risk_scores': True,
                'max_results': 50,
                'format': 'detailed'
            }
        )

        print(f'AI Query Interpretation:')
        print(f'  Parsed filters: {result.data.interpreted_query}')
        print(f'  Confidence: {result.data.interpretation_confidence}')
        print(f'  Results found: {result.data.total_results}')

        for tx in result.data.transactions:
            print(f'  {tx.created_at}: {tx.type} {tx.amount} {tx.currency}')
            print(f'    Status: {tx.status} | Risk: {tx.risk_score}')
            if tx.compliance_flags:
                print(f'    Flags: {", ".join(tx.compliance_flags)}')

        if result.data.analytics:
            print(f'\nAnalytics Summary:')
            print(f'  Total volume: {result.data.analytics.total_volume}')
            print(f'  Average amount: {result.data.analytics.avg_amount}')
            print(f'  Flagged count: {result.data.analytics.flagged_count}')

        return result
    except Exception as error:
        print(f'AI query failed: {error}')
        raise

# Natural language transaction search
query_transactions_with_ai(
    'Show me all cross-chain transfers over $5000 in the last 7 days that had compliance flags',
    'acct_1234567890'
)

{
  "data": {
    "query_id": "aiq_stu901vwx234",
    "original_query": "Show me all cross-chain transfers over $5000 in the last 7 days that had compliance flags",
    "interpreted_query": {
      "type": ["cross_chain_transfer"],
      "amount_min": 5000,
      "currency": "USD",
      "date_range": {
        "from": "2026-01-08T00:00:00Z",
        "to": "2026-01-15T23:59:59Z"
      },
      "has_compliance_flags": true
    },
    "interpretation_confidence": 0.96,
    "total_results": 3,
    "transactions": [
      {
        "uuid": "tx_cross_001",
        "type": "cross_chain_transfer",
        "amount": "7500.00",
        "currency": "USDC",
        "status": "completed",
        "source_chain": "ethereum",
        "destination_chain": "arbitrum",
        "bridge_protocol": "wormhole",
        "risk_score": 0.35,
        "compliance_flags": ["high_value_transfer"],
        "created_at": "2026-01-12T14:30:00Z"
      },
      {
        "uuid": "tx_cross_002",
        "type": "cross_chain_transfer",
        "amount": "12000.00",
        "currency": "USDT",
        "status": "completed",
        "source_chain": "polygon",
        "destination_chain": "ethereum",
        "bridge_protocol": "layerzero",
        "risk_score": 0.62,
        "compliance_flags": ["high_value_transfer", "new_destination"],
        "created_at": "2026-01-10T09:15:00Z"
      },
      {
        "uuid": "tx_cross_003",
        "type": "cross_chain_transfer",
        "amount": "25000.00",
        "currency": "USDC",
        "status": "pending_review",
        "source_chain": "ethereum",
        "destination_chain": "bsc",
        "bridge_protocol": "axelar",
        "risk_score": 0.78,
        "compliance_flags": ["high_value_transfer", "jurisdiction_mismatch", "velocity_alert"],
        "created_at": "2026-01-09T16:45:00Z"
      }
    ],
    "analytics": {
      "total_volume": "44500.00",
      "avg_amount": "14833.33",
      "median_amount": "12000.00",
      "flagged_count": 3,
      "avg_risk_score": 0.58,
      "chains_involved": ["ethereum", "polygon", "arbitrum", "bsc"],
      "bridges_used": ["wormhole", "layerzero", "axelar"]
    }
  }
}

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;
  }
}

Demo Environment

Browse by Category

Basic Operations

Advanced Workflows

Webhooks

Error Handling

AI Agent Integration

MCP Tools

Cross-Chain & DeFi

RegTech & Compliance

BaaS & Partner API

AI Transaction Query

Basic Operations

Create Account and Get Balance

Simple Money Transfer

List Account Transactions

Advanced Workflows

Multi-Currency Conversion with Transfer

Webhooks

Setting Up Webhook Endpoints

Express.js Handler

Webhook Configuration

AI Agent Integration

AI Banking Assistant Chat

AI-Driven Workflow Orchestration

Try the AI Agent Live

MCP Tools Integration

MCP Tool Registration and Usage

Complex MCP Workflow Integration

Cross-Chain & DeFi

Cross-Chain Bridge: Quote and Initiate

DeFi Swap: Quote and Execute

RegTech & Compliance

Travel Rule Compliance Check

BaaS & Partner API

BaaS Partner Onboarding

AI Transaction Query

AI-Powered Transaction Search

Error Handling

Robust Error Handling with Retries

Start Building Today