# CodeGreeks FX & Currency REST API — AI Agent Integration Guide

> Real-Time Forex & Digital Asset Conversion Engine for Autonomous AI Agents, Cursor, Claude Desktop, and LangChain.
> Tracked assets: 172 world currencies (fiat, crypto, precious metals)
> Average edge latency: <15ms
> MCP Endpoint: `https://codegreeks.com.ng/api/v1/currency/mcp`
> Base URL: `https://codegreeks.com.ng/api/v1/currency`

---

## 1. Quick Start for AI Agents

To fetch live rates or execute currency conversion immediately, make a GET request:

```bash
# Instant Currency Conversion (100 USD to NGN)
curl -X GET "https://codegreeks.com.ng/api/v1/currency/convert?from=USD&to=NGN&amount=100" \
  -H "X-API-KEY: YOUR_API_KEY"

# Fetch all 172 Live Exchange Rates
curl -X GET "https://codegreeks.com.ng/api/v1/currency/rates?base=USD" \
  -H "X-API-KEY: YOUR_API_KEY"

# Live Currency Counter & Telemetry
curl -X GET "https://codegreeks.com.ng/api/v1/currency/count"
```

---

## 2. Model Context Protocol (MCP) Integration

CodeGreeks natively implements the **Model Context Protocol (MCP)** JSON-RPC 2.0 specification (`protocolVersion: 2024-11-05`).

### Claude Desktop Configuration
Add the following block to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "codegreeks-currency": {
      "url": "https://codegreeks.com.ng/api/v1/currency/mcp",
      "headers": {
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Cursor AI / Windsurf Rules (.cursorrules or .cursor/mcp.json)
```json
{
  "mcpServers": {
    "codegreeks-currency": {
      "url": "https://codegreeks.com.ng/api/v1/currency/mcp",
      "headers": {
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

---

## 3. Available MCP Tools & Function Calling Schemas

### Tool 1: `convert_currency`
Converts any numerical amount between any two supported world currencies.
* **Arguments:**
  - `from` (string, required): 3-letter origin ISO code (e.g. `USD`, `EUR`, `NGN`, `GBP`, `BTC`).
  - `to` (string, required): 3-letter target ISO code (e.g. `NGN`, `CAD`, `KES`, `EUR`).
  - `amount` (number, optional, default: 1): Positive numerical value.
* **Output:**
  ```json
  {
    "status": "success",
    "from": "USD",
    "from_name": "United States Dollar",
    "to": "NGN",
    "to_name": "Nigerian Naira",
    "amount": 100,
    "converted_amount": 134621.0,
    "unit_rate": 1346.21,
    "inverse_rate": 0.000743,
    "formula": "1 USD = 1346.21 NGN",
    "currency_count": 172,
    "last_updated": "2026-10-30T18:22:30Z"
  }
  ```

### Tool 2: `get_exchange_rates`
Retrieves the complete dictionary of all 172 rates rebased to any desired asset.
* **Arguments:**
  - `base` (string, optional, default: `USD`): Desired base asset.

### Tool 3: `get_historical_rates`
Returns timestamped rate shift audit logs recorded when currency prices moved.
* **Arguments:**
  - `currency` (string, required): Currency ISO code (e.g. `NGN`).
  - `limit` (integer, optional, default: 10): Number of records.

### Tool 4: `get_supported_currencies`
Lists all 172 assets with human-readable titles and symbols.

---

## 4. OpenAI Function Calling / Tool Definition Schema

Pass this schema to `openai.chat.completions.create(tools=[...])`:

```json
[
  {
    "type": "function",
    "function": {
      "name": "convert_currency",
      "description": "Convert an amount between two world currencies using CodeGreeks real-time institutional exchange rates.",
      "parameters": {
        "type": "object",
        "properties": {
          "from": { "type": "string", "description": "3-letter origin currency (e.g. USD)" },
          "to": { "type": "string", "description": "3-letter target currency (e.g. NGN)" },
          "amount": { "type": "number", "description": "Amount to convert" }
        },
        "required": ["from", "to"]
      }
    }
  }
]
```

---

## 5. LangChain / Python Agent Integration

```python
import requests

def convert_currency(from_curr: str, to_curr: str, amount: float = 1.0) -> dict:
    url = "https://codegreeks.com.ng/api/v1/currency/convert"
    headers = {"X-API-KEY": "YOUR_API_KEY"}
    params = {"from": from_curr, "to": to_curr, "amount": amount}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Example Agent Tool Call
data = convert_currency("USD", "NGN", 250)
print(f"Result: {data['amount']} {data['from']} = {data['converted_amount']} {data['to']}")
```

---

## 6. Rate Limits & Quotas
- Authenticated calls return:
  - `X-RateLimit-Tier`: Free / Starter / Pro / Enterprise
  - `X-RateLimit-Limit`: Monthly quota allowance
  - `X-RateLimit-Remaining`: Remaining calls available this billing cycle
  - `X-RateLimit-Reset`: Unix timestamp of the next monthly reset
- When limits are reached, the API returns `HTTP 429 Too Many Requests`.
- To generate or upgrade your API key, visit: `https://codegreeks.com.ng/user/api-keys`.