Currency Exchange

Name: Currency Exchange
Rating: 3.5 (1 reviews)
Author: aoyasong

By aoyasong 👁 1 views ▲ 0 votes

OpenClaw MCP Plugin for multi-currency exchange and conversion for e-commerce

GitHub

Install

npm install
```

Configuration Example

{
  "base": "USD",
  "target": "CNY",
  "use_cache": true
}

README

# Currency Exchange Plugin for OpenClaw

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![OpenClaw MCP Compatible](https://img.shields.io/badge/OpenClaw-MCP-blue.svg)](https://openclaw.ai)

A production-ready OpenClaw MCP plugin for real-time currency exchange rates, historical data, and e-commerce optimization. Part of the e-commerce plugin suite for cross-border operations.

## 🚀 Features

- **Real-time Exchange Rates**: Multi-provider support with automatic failover
- **Historical Data**: Exchange rates for past year with fluctuation analysis
- **Batch Processing**: Convert multiple currencies in a single request
- **E-commerce Optimization**: Pre-loaded rates for common trade pairs (USD/CNY, EUR/CNY, etc.)
- **Production Ready**: Two-level caching, rate limiting, error handling, and monitoring
- **MCP Protocol**: Fully compatible with OpenClaw's Model Context Protocol

## 🛠️ Tools Provided

### Core Tools (8 Required)

1. **currency_get_exchange_rate** - Get real-time exchange rate between currencies
2. **currency_convert_amount** - Convert amount from one currency to another
3. **currency_get_historical_rate** - Get historical exchange rate for specific date
4. **currency_batch_conversion** - Convert multiple amounts in batch
5. **currency_monitor_rate_changes** - Monitor rate changes and alert on thresholds
6. **currency_get_supported_currencies** - Get list of supported currencies
7. **currency_calculate_profit_difference** - Calculate profit from exchange rate changes
8. **currency_get_provider_status** - Get health status of exchange rate providers

### Tool Details

#### currency_get_exchange_rate
Get real-time exchange rate between two currencies with caching support.

**Input Parameters:**
- `base` (required): Base currency code (3 letters, e.g., USD)
- `target` (required): Target currency code (3 letters, e.g., CNY)
- `use_cache` (optional): Use cached rate if available (default: true)
- `source` (optional): API source: "xe", "exchangerate", or "auto" (default)

**Example:**
```json
{
  "base": "USD",
  "target": "CNY",
  "use_cache": true
}
```

#### currency_convert_amount
Convert an amount from one currency to another with rounding control.

**Input Parameters:**
- `amount` (required): Amount to convert
- `from` (required): Source currency code
- `to` (required): Target currency code
- `rounding` (optional): Decimal places to round (0-8, default: 2)
- `use_cache` (optional): Use cached rate (default: true)

#### currency_get_historical_rate
Get historical exchange rate for a specific date (within past year).

**Input Parameters:**
- `base` (required): Base currency code
- `target` (required): Target currency code
- `date` (required): Date in YYYY-MM-DD format
- `include_fluctuation` (optional): Include fluctuation analysis (default: false)

#### currency_batch_conversion
Convert multiple amounts between currencies in a single request.

**Input Parameters:**
- `conversions` (required): Array of conversion objects (1-100 items)
- `use_cache` (optional): Use cached rates (default: true)

**Example Conversion Object:**
```json
{
  "amount": 1000,
  "from": "USD",
  "to": "CNY"
}
```

#### currency_monitor_rate_changes
Monitor exchange rate changes and alert when thresholds are exceeded.

**Input Parameters:**
- `currencies` (required): Array of currency pairs to monitor (e.g., ["USD/CNY", "EUR/CNY"])
- `threshold_percent` (optional): Percentage change to trigger alert (default: 1.0)
- `period_hours` (optional): Time period to analyze in hours (default: 24)
- `alert_on_exceed` (optional): Return alerts when threshold exceeded (default: true)

#### currency_get_supported_currencies
Get list of all supported currencies with metadata.

**Input Parameters:**
- `filter` (optional): Filter by currency code or name
- `include_inactive` (optional): Include inactive currencies (default: false)
- `provider` (optional): Filter by provider: "xe", "exchangerate", or "all" (default)

#### currency_calculate_profit_difference
Calculate profit/loss from exchange rate changes for e-commerce.

**Input Parameters:**
- `amount` (required): Base amount
- `buy_rate` (required): Exchange rate at purchase time
- `sell_rate` (required): Exchange rate at sale time
- `currency_pair` (optional): Currency pair context (e.g., "CNY/USD")
- `include_percentage` (optional): Include percentage change (default: true)

#### currency_get_provider_status
Get health status, latency, and availability of exchange rate providers.

**Input Parameters:**
- `detailed` (optional): Include detailed statistics (default: false)

## 📦 Installation

### Prerequisites
- Node.js v18+ and npm
- OpenClaw v0.5.0+
- At least one API key for exchange rate providers (recommended: XE API)

### Step 1: Clone the Repository
```bash
git clone https://github.com/aoyasong/currency-exchange-plugin.git
cd currency-exchange-plugin
```

### Step 2: Install Dependencies
```bash
npm install
```

### Step 3: Configure Environment Variables
```bash
cp .env.example .env
```

Edit the `.env` file with your API credentials:

```bash
# XE API (Primary - recommended)
XE_API_KEY=your_xe_api_key_here

# ExchangeRate-API (Secondary/Backup)
EXCHANGE_RATE_API_KEY=your_exchange_rate_api_key_here

# Cache settings
CACHE_TTL_REALTIME=300
REDIS_ENABLED=false

# Rate limiting
REQUEST_LIMIT_PER_MINUTE=60
```

### Step 4: Test the Plugin
```bash
npm test
```

## 🔌 OpenClaw Integration

### Method 1: Direct Integration via openclaw.json

Add to your OpenClaw configuration file:

```json
{
  "plugins": {
    "currency-exchange": {
      "command": "node",
      "args": ["/path/to/currency-exchange-plugin/src/index.js"],
      "env": {
        "XE_API_KEY": "your-xe-api-key",
        "EXCHANGE_RATE_API_KEY": "your-exchangerate-api-key"
      }
    }
  }
}
```

### Method 2: Environment-Based Configuration

Set environment variables and run:

```bash
export XE_API_KEY=your-xe-key
export EXCHANGE_RATE_API_KEY=your-exchange-rate-key

# Start OpenClaw with the plugin
openclaw agent --plugin currency-exchange
```

### Method 3: Docker Integration

```bash
docker run -d \
  --name currency-exchange-plugin \
  -e XE_API_KEY=your-xe-key \
  -e EXCHANGE_RATE_API_KEY=your-exchange-rate-key \
  aoyasong/currency-exchange-plugin:latest
```

## 🏗️ Architecture

### Multi-Provider Strategy
- **Primary**: XE API (accurate, reliable, 180+ currencies)
- **Secondary**: ExchangeRate-API (free tier available)
- **Fallback**: Static rates if providers unavailable
- **Automatic Failover**: Seamless switching on provider failure

### Two-Level Caching
1. **Memory Cache** (Required): LRU cache with configurable TTL
   - Real-time rates: 5-10 minutes
   - Historical rates: 24 hours
   - Currency list: 7 days
2. **Redis Cache** (Optional): Distributed cache for multi-instance deployments

### Performance Optimizations
- **Batch Processing**: Up to 100 conversions per request
- **Preloading**: Common e-commerce pairs cached on startup
- **Connection Pooling**: Reusable HTTP connections
- **Parallel Requests**: Concurrent API calls with limits

## 🛒 E-commerce Integration

### Common Use Cases

#### 1. Supplier Price Conversion
Convert supplier quotes (e.g., from 1688.com) to your local currency:
```json
{
  "amount": 5000,
  "from": "CNY",
  "to": "USD"
}
```

#### 2. Multi-Market Pricing
Calculate optimal prices for different Amazon marketplaces:
- Convert product cost from USD to EUR, GBP, JPY, etc.
- Apply market-specific markups
- Round to psychological price points (.99, .95)

#### 3. Profit Margin Analysis
Compare purchase vs sale exchange rates:
```json
{
  "amount": 10000,
  "buy_rate": 7.15,
  "sell_rate": 7.25,
  "currency_pair": "CNY/USD"
}
```

#### 4. Risk Management
Monitor USD/CNY fluctuations for import/export businesses:
- Set 1% threshold for daily changes
- Receive alerts when rates move significantly
- Plan purchases around favorable rates

### Integration with Other Plugins

#### amazon-sp-api-plugin
- Convert Amazon revenue from multiple markets to base currency
- Calculate profit margins considering exchange rate differences
- Set prices based on competitor rates in local currencies

#### ecommerce-db-plugin
- Store historical exchange rates for financial reporting
- Track currency fluctuations impact on profitability
- Generate multi-currency financial statements

#### 1688-data-plugin
- Convert supplier quotes from CNY to USD/EUR
- Compare supplier prices across currencies
- Calculate landed costs with exchange rate factors

#### tax-calculator-plugin
- Calculate taxes in local currencies
- Convert tax liabilities to reporting currency
- Handle multi-currency tax reporting

## 🧪 Testing

Run the test suite:

```bash
npm test
```

Run specific test categories:

```bash
# Unit tests (no API keys required)
npm test -- --testPathPattern=unit

# Integration tests (requires valid API keys)
npm test -- --testPathPattern=integration

# Performance tests
npm test -- --testPathPattern=performance

# All tests with coverage report
npm test -- --coverage
```

## 🐳 Docker Deployment

### Build Docker Image
```bash
docker build -t currency-exchange-plugin:latest .
```

### Run Container
```bash
docker run -d \
  --name currency-exchange-plugin \
  -p 3000:3000 \
  -e XE_API_KEY=your-xe-api-key \
  -e EXCHANGE_RATE_API_KEY=your-exchange-rate-key \
  -e REDIS_URL=redis://redis:6379 \
  currency-exchange-plugin:latest
```

### Docker Compose
```yaml
version: '3.8'
services:
  currency-exchange:
    build: .
    environment:
      - XE_API_KEY=${XE_API_KEY}
      - EXCHANGE_RATE_API_KEY=${EXCHANGE_RATE_API_KEY}
      - REDIS_URL=redis://redis:6379
      - REQUEST_LIMIT_PER_MINUTE=60
    volumes:
      - ./cache:/app/cache
    ports:
      - "3000:3000"
    depends_on:
      - redis
    
  redis:
    image: redis:7-alpine
    ports:
      - "6

... (truncated)

tools