trading-platform-mcp-wallet-v2/README.md

MCP Wallet Server

Virtual Wallet MCP Server for the Trading Platform. Manages credits (USD equivalent) for purchases, subscriptions, and agent funding.

Overview

This service provides:

• Virtual Wallet System: Credits-based wallet (1 credit = 1 USD equivalent, not real money)
• Transaction Management: Full audit trail of all wallet operations
• MCP Protocol Support: Tools can be called by AI agents via MCP
• REST API: Traditional API endpoints for frontend integration
• Multi-tenancy: Full RLS support for tenant isolation

Quick Start

# Install dependencies
npm install

# Copy environment config
cp .env.example .env

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

API Endpoints

Health & Info

• GET /health - Health check with database status
• GET /info - Server info and available tools

MCP Protocol

• GET /mcp/tools - List available MCP tools
• POST /mcp/tools/:toolName - Execute a specific tool
• POST /mcp/call - MCP-style call {name, arguments}

REST API

Wallets

• POST /api/v1/wallets - Create wallet
• GET /api/v1/wallets/:walletId - Get wallet
• GET /api/v1/wallets/:walletId/balance - Get balance with limits
• GET /api/v1/wallets/:walletId/summary - Dashboard summary
• POST /api/v1/wallets/:walletId/credits - Add credits (Stripe)
• POST /api/v1/wallets/:walletId/debit - Debit credits
• POST /api/v1/wallets/transfer - Transfer between wallets

Transactions

• GET /api/v1/wallets/:walletId/transactions - Transaction history
• GET /api/v1/transactions/:transactionId - Get transaction
• POST /api/v1/wallets/:walletId/refund - Process refund

MCP Tools

Tool	Description	Risk Level
wallet_create	Create new wallet	MEDIUM
wallet_get	Get wallet by ID/user	LOW
wallet_get_balance	Get balance with limits	LOW
wallet_add_credits	Add credits via Stripe	HIGH
wallet_debit	Debit credits	HIGH
wallet_transfer	Transfer between wallets	HIGH
wallet_add_promo	Add promotional credits	MEDIUM
wallet_update_limits	Update spending limits	MEDIUM
wallet_freeze	Freeze wallet	HIGH
wallet_unfreeze	Unfreeze wallet	HIGH
transaction_get	Get transaction details	LOW
transaction_history	Get transaction history	LOW
wallet_summary	Dashboard summary	LOW
transaction_refund	Process refund	HIGH

Transaction Types

• CREDIT_PURCHASE - Buy credits via Stripe
• AGENT_FUNDING - Fund Money Manager agent
• AGENT_WITHDRAWAL - Withdraw from agent
• AGENT_PROFIT - Profit from agent trading
• AGENT_LOSS - Loss from agent trading
• PRODUCT_PURCHASE - Buy product/service
• SUBSCRIPTION_CHARGE - Subscription payment
• PREDICTION_PURCHASE - Buy ML predictions
• REFUND - Refund to wallet
• PROMO_CREDIT - Promotional credits
• PROMO_EXPIRY - Expired promo credits
• ADJUSTMENT - Manual adjustment
• TRANSFER_IN/OUT - Wallet transfers
• FEE - Platform fees

Environment Variables

# Server
PORT=3090
NODE_ENV=development
LOG_LEVEL=info

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=trading_platform
DB_USER=trading_app
DB_PASSWORD=secret

# Wallet Config
WALLET_DEFAULT_DAILY_LIMIT=1000
WALLET_DEFAULT_MONTHLY_LIMIT=10000
WALLET_DEFAULT_SINGLE_TX_LIMIT=500
WALLET_CURRENCY=USD

# Stripe
STRIPE_SECRET_KEY=sk_test_...

Docker

# Build
docker build -t mcp-wallet:1.0.0 .

# Run
docker run -p 3090:3090 --env-file .env mcp-wallet:1.0.0

Architecture

src/
├── index.ts           # Express server entry point
├── config.ts          # Configuration & DB pool
├── types/
│   └── wallet.types.ts    # TypeScript interfaces
├── services/
│   └── wallet.service.ts  # Business logic
├── tools/
│   ├── index.ts       # Tool registry
│   ├── wallet.ts      # Wallet operations
│   └── transactions.ts    # Transaction operations
└── utils/
    ├── logger.ts      # Winston logging
    └── errors.ts      # Custom error classes

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

License

UNLICENSED - Private repository