# BitPin MCP Server (`bitpin-mcp`)

[![npm version](https://img.shields.io/npm/v/bitpin-mcp.svg)](https://www.npmjs.com/package/bitpin-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

An official Model Context Protocol (MCP) server for the **BitPin** Iranian Cryptocurrency Exchange API (`docs.bitpin.ir`), built with the official [@modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk).

This MCP server connects AI assistants (Claude Desktop, Cursor, Antigravity IDE, Cline, Roo Code, etc.) directly to BitPin, allowing users to inspect market prices, monitor orderbooks, place and cancel trading orders, view wallet balances, and manage deposits and withdrawals in real time.

---

## Key Features

- **Standard MCP Protocol**: Runs via `stdio` transport, compatible with all major MCP clients.
- **English AI Descriptions with Persian (فارسی) Input Support**:
  - Detailed, precise tool definitions and parameter descriptions written in English for maximum AI model accuracy.
  - Full support for Persian inputs:
    - Persian cryptocurrency and fiat names: `بیت کوین`, `تتر`, `اتریوم`, `ترون`, `دوج کوین`, `تومان`, `سولانا`, `نات کوین`, etc.
    - Market pairs: `بیت کوین به تومان`, `تتر تومان`, `اتریوم تتر`, etc.
    - Order sides: `خرید` (buy), `فروش` (sell).
    - Order types: `محدود` (limit), `بازار` / `فوری` (market), `استاپ لیمیت` (stop_limit), `دوطرفه` (oco).
    - Persian & Arabic numerals: Automatically normalizes `۰۱۲۳۴۵۶۷۸۹` to standard numbers.
    - Order states: `فعال` (active), `بسته` (closed), `اولیه` (initial).
- **Auto-Authentication & Refresh**: Automatically exchanges API Key & Secret Key for Bearer JWT tokens, handles token caching, and auto-refreshes tokens on 401 expiration.
- **Zero Configuration Required for Public Market Data**: Fetch prices, currencies, orderbooks, and recent trades without any API keys.

---

## Quick Start (with `npx`)

You can run the server directly using `npx`:

```bash
npx -y bitpin-mcp
```

---

## Configuration with MCP Clients

### 1. Claude Desktop

Add the following to your `claude_desktop_config.json`:

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bitpin": {
      "command": "npx",
      "args": ["-y", "bitpin-mcp"],
      "env": {
        "BITPIN_API_KEY": "YOUR_BITPIN_API_KEY",
        "BITPIN_SECRET_KEY": "YOUR_BITPIN_SECRET_KEY"
      }
    }
  }
}
```

> **Note:** If you only need public market data (prices, tickers, orderbook), you can omit the `env` block.

---

### 2. Cursor (`.cursor/mcp.json`)

Add the server to `.cursor/mcp.json` in your project or global Cursor settings:

```json
{
  "mcpServers": {
    "bitpin": {
      "command": "npx",
      "args": ["-y", "bitpin-mcp"],
      "env": {
        "BITPIN_API_KEY": "YOUR_BITPIN_API_KEY",
        "BITPIN_SECRET_KEY": "YOUR_BITPIN_SECRET_KEY"
      }
    }
  }
}
```

---

### 3. Antigravity IDE / Cline / Roo Code / VS Code

```json
{
  "bitpin": {
    "command": "npx",
    "args": ["-y", "bitpin-mcp"],
    "env": {
      "BITPIN_API_KEY": "YOUR_BITPIN_API_KEY",
      "BITPIN_SECRET_KEY": "YOUR_BITPIN_SECRET_KEY"
    }
  }
}
```

---

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `BITPIN_BASE_URL` | Base API URL for BitPin | `https://api.bitpin.ir` (fallback: `https://api.bitpin.org`) |
| `BITPIN_API_KEY` | BitPin API Key (created in BitPin web panel under API settings) | *Optional for public market data* |
| `BITPIN_SECRET_KEY` | BitPin Secret Key (created in BitPin web panel under API settings) | *Optional for public market data* |
| `BITPIN_ACCESS_TOKEN` | BitPin JWT Bearer access token (if providing token directly) | *Optional* |
| `BITPIN_REFRESH_TOKEN`| BitPin JWT refresh token (if providing token directly) | *Optional* |

> [!WARNING]
> **IP Whitelisting & HTTP 403 Forbidden Notice**:
> BitPin enforces strict IP whitelisting for all API tokens in their Token Manager. When creating your API key pair on BitPin, you must specify the exact IP addresses authorized to access the API.
> Calling authenticated tools from any IP that is not predefined in BitPin's Token Manager (for instance, when connected to a VPN, a dynamic mobile network, or an unregistered server) will immediately result in an **`HTTP 403 Forbidden`** error.
> If you encounter HTTP 403 errors, check your current public IP (e.g. via `curl ifconfig.me`) and add it to your API Key whitelist in the BitPin panel. Public market data tools do not require IP whitelisting.

---

## Available Tools

### 1. Market Data (Public & Authenticated)

| Tool Name | Description | Accepts Persian Input | Auth Required |
|---|---|---|---|
| `bitpin_get_currencies` | Lists all supported cryptocurrencies and fiat assets with precision, title, and trading status. Filter by currency code or name. | Yes (`بیت کوین`, `تتر`, `تومان`) | No |
| `bitpin_get_markets` | Lists all trading markets with base/quote currencies, minimum order sizes, and price precisions. | Yes (`بیت کوین به تومان`, `تتر`) | No |
| `bitpin_get_networks` | Lists supported blockchain networks with deposit/withdrawal statuses and regex address validation. | Yes (`TRX`, `اتریوم`, `بله`/`خیر`) | No |
| `bitpin_get_tickers` | Real-time prices, 24h change, high, low, and volumes for all or a specific trading pair. | Yes (`قیمت بیت کوین`, `تتر تومان`) | No |
| `bitpin_get_orderbook` | Bids and asks (up to 20 levels per side) for a market pair. | Yes (`BTC_IRT`, `بیت کوین به تومان`) | No |
| `bitpin_get_recent_trades`| Latest executed public trades for a market pair. | Yes (`BTC_IRT`, `تتر به تومان`) | No |
| `bitpin_get_commissions` | Maker and taker commission rates across all markets. | N/A | Yes |

### 2. Orders & Trading

| Tool Name | Description | Accepts Persian Input | Auth Required |
|---|---|---|---|
| `bitpin_place_order` | Places a new order (`limit`, `market`, `stop_limit`, `oco`). | Yes (`خرید`/`فروش`, `محدود`/`بازار`, `۵۰۰۰۰`) | Yes |
| `bitpin_place_bulk_orders`| Places up to 10 orders simultaneously on a single market. | Yes | Yes |
| `bitpin_get_orders` | Retrieves active and closed orders (last 7 days). Supports filtering by symbol, state, side, dates. | Yes (`فعال`, `بسته`, `خرید`, `فروش`) | Yes |
| `bitpin_get_order_by_id` | Fetches details and execution status of a single order by ID. | Yes (`۱۲۳۴۵`) | Yes |
| `bitpin_cancel_order` | Cancels an open active order by its ID. | Yes (`۱۲۳۴۵`) | Yes |
| `bitpin_cancel_bulk_orders`| Cancels multiple active orders at once by IDs. | Yes (`۱۲۳، ۴۵۶`) | Yes |
| `bitpin_get_fills` | Retrieves trade history / execution fills. | Yes | Yes |

### 3. Wallet & Transfers

| Tool Name | Description | Accepts Persian Input | Auth Required |
|---|---|---|---|
| `bitpin_get_wallet_balances` | Returns asset balances across user wallets. | Yes (`بیت کوین، تتر، تومان`) | Yes |
| `bitpin_get_account_numbers`| Lists registered bank accounts (IBAN/card) for Toman withdrawals. | Yes | Yes |
| `bitpin_get_deposit_address`| Generates/retrieves blockchain deposit address for an asset and network. | Yes (`تتر`, `TRX`) | Yes |
| `bitpin_get_deposit_history`| Retrieves deposit transactions history. | Yes | Yes |
| `bitpin_get_withdrawal_history`| Retrieves crypto and fiat withdrawal history. | Yes | Yes |
| `bitpin_create_crypto_withdrawal`| Submits a crypto withdrawal request to an external wallet address. | Yes | Yes |
| `bitpin_create_irt_withdrawal` | Submits an Iranian Toman (IRT) withdrawal to a registered bank account. | Yes (`۵۰۰۰۰۰۰`) | Yes |
| `bitpin_create_internal_withdrawal`| Instant zero-fee transfer to another BitPin user via phone number or email. | Yes (`۰۹۱۲...`) | Yes |
| `bitpin_verify_withdrawal_otp` | Confirms a withdrawal with 6-digit Authenticator code / SMS OTP. | Yes (`۱۲۳۴۵۶`) | Yes |

### 4. Authentication Management

| Tool Name | Description | Auth Required |
|---|---|---|
| `bitpin_authenticate` | Authenticate using API Key and Secret Key to obtain JWT tokens. | No (uses keys) |
| `bitpin_refresh_token` | Refreshes the active JWT access token using the refresh token. | No |
| `bitpin_set_access_token` | Manually sets the Bearer access token for the current session. | No |

---

## Persian Input Examples (نمونه‌های ورودی فارسی)

The server automatically handles Persian names, words, and numbers:

```typescript
// Query price of Bitcoin in Toman:
bitpin_get_tickers({ symbol: "بیت کوین به تومان" }); // Resolves to BTC_IRT

// Query Tether price:
bitpin_get_tickers({ symbol: "تتر" }); // Resolves to USDT_IRT

// Place a limit buy order:
bitpin_place_order({
  symbol: "تتر به تومان", // USDT_IRT
  side: "خرید",           // buy
  type: "محدود",          // limit
  price: "۵۸۵۰۰",         // 58500
  base_amount: "۱۰۰"      // 100
});

// Filter active orders:
bitpin_get_orders({
  symbol: "بیت کوین",
  state: "فعال"           // active
});
```

---

## Local Development & Publishing

### Build Locally
```bash
npm install
npm run build
```

### Run Locally
```bash
npm start
# or development with live reload:
npm run dev
```

### Publish to npm
```bash
npm login
npm publish --access public
```

Once published to npm, anyone can run it immediately with:
```bash
npx -y bitpin-mcp
```

---

## License

[MIT](LICENSE)