Skip to main content
Glama
BitPin MCP Server

BitPin MCP Server

by mh-zeynal

BitPin MCP Server (bitpin-mcp)

npm version License: MIT

An official Model Context Protocol (MCP) server for the BitPin Iranian Cryptocurrency Exchange API (docs.bitpin.ir), built with the official @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.


Related MCP server: BitOasis MCP Server

Quick Start (with npx)

You can run the server directly using npx:

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

{
  "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:

{
  "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

{
  "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:

// 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

npm install
npm run build

Run Locally

npm start
# or development with live reload:
npm run dev

Publish to npm

npm login
npm publish --access public

Once published to npm, anyone can run it immediately with:

npx -y bitpin-mcp

License

MIT

Available Tools

26 tools
bitpin_authenticateA

Authenticate with BitPin API using API Key and Secret Key to obtain JWT access and refresh tokens. IMPORTANT: BitPin API tokens are restricted to predefined IPs registered in their Token Manager; calling from any non-whitelisted IP will cause HTTP 403 Forbidden. Rate limit: 200/day. Resulting tokens are cached automatically for subsequent requests.

Inputs: api_key, secret_key.

bitpin_cancel_bulk_ordersA

Cancel multiple active orders at once by providing a list or comma-separated string of BitPin order IDs. Requires authentication.

Inputs: ids (required).

bitpin_cancel_orderA

Cancel an active open order on BitPin by its order ID. Rate limit: 5400/hour. Requires authentication.

Inputs: order_id (required).

bitpin_create_crypto_withdrawalB

Submit a cryptocurrency withdrawal request from BitPin to an external blockchain wallet. Requires subsequent OTP confirmation. Requires authentication.

Inputs: amount (required), address (required), network (required), currency (required), +1 more.

bitpin_create_internal_withdrawalA

Perform an instant, zero-fee cryptocurrency transfer to another BitPin user using their registered mobile phone number or email address. Requires authentication.

Inputs: amount (required), currency (required), alternative_address (required).

bitpin_create_irt_withdrawalA

Submit an Iranian Toman (IRT) withdrawal to a registered bank account on BitPin. Requires subsequent OTP confirmation. Requires authentication.

Inputs: amount (required), account_number (required).

bitpin_get_account_numbersA

Get user registered bank accounts (IBAN/card numbers) for Toman (IRT) withdrawals on BitPin. Rate limit: 60/min. Requires authentication.

Inputs: limit, offset.

bitpin_get_commissionsA

Get maker and taker commission rates for all markets on BitPin. Requires authentication. Rate limit: 1000/day.

Inputs: no named parameters.

bitpin_get_currenciesA

Get a list of all supported cryptocurrencies and fiat currencies on BitPin, including symbol, title, precision, and trading status. Rate limit: 10,000/day (public) or 200/min (authenticated).

Inputs: currency.

bitpin_get_deposit_addressA

Get or generate a deposit address for a specific cryptocurrency on a blockchain network in BitPin. Requires KYC level 1+. Rate limit: 60/min. Requires authentication.

Inputs: network (required), currency (required).

bitpin_get_deposit_historyA

Get deposit history on BitPin. Filters: currency, network, state, is_crypto, wallet_transfer. Rate limit: 60/min. Requires authentication.

Inputs: limit, state, offset, network, +2 more.

bitpin_get_fillsA

Get personal executed trade history (fills) on BitPin. Filters: symbol, side ("buy"/"sell" or Persian "خرید"/"فروش"), offset, limit. Rate limit: 80/min. Requires authentication.

Inputs: side, limit, offset, symbol.

bitpin_get_marketsA

Get a list of all trading markets/pairs on BitPin with base/quote currencies, minimum order sizes, and price precisions. Rate limit: 10,000/day (public) or 200/min (authenticated).

Inputs: symbol, quote_currency.

bitpin_get_networksA

Get all supported blockchain networks on BitPin with deposit and withdrawal statuses, regex address validation patterns, and confirmation requirements.

Inputs: code, can_deposit, can_withdraw.

bitpin_get_orderbookA

Get orderbook (bids and asks) for a specified market pair on BitPin. Maximum 20 rows returned per side. Rate limit: 60/min.

Inputs: symbol (required).

bitpin_get_order_by_idA

Get details and status of a single order by its BitPin order ID. Rate limit: 80/min. Requires authentication.

Inputs: order_id (required).

bitpin_get_ordersA

Get active orders and closed orders from the last 7 days on BitPin. Filter by symbol, state ("active", "closed", "initial" or Persian "فعال", "بسته"), side, and date range. Rate limit: 80/min. Requires authentication.

Inputs: end, side, type, limit, +5 more.

bitpin_get_recent_tradesA

Get the latest executed public trades/matches for a specified market pair on BitPin. Rate limit: 60/min.

Inputs: symbol (required).

bitpin_get_tickersA

Get real-time market prices, 24h percentage changes, high, low, and volumes for all trading pairs on BitPin. Rate limit: 80/min.

Inputs: symbol.

bitpin_get_wallet_balancesA

Get user wallet balances per asset on BitPin. Filters: assets (e.g. "BTC,IRT,USDT" or Persian "بیت کوین،تتر،تومان"), service (e.g. "main"), offset, limit (max 200). Rate limit: 60/min. Requires authentication.

Inputs: limit, assets, offset, service.

bitpin_get_withdrawal_historyA

Get withdrawal history on BitPin. Filters: currency, address, state, start/end dates. Rate limit: 10,000/day. Requires authentication.

Inputs: end, limit, start, state, +3 more.

bitpin_place_bulk_ordersB

Place up to 10 orders simultaneously on a single market in BitPin. Requires authentication.

Inputs: orders (required).

bitpin_place_orderA

Place a new cryptocurrency order on BitPin. Supports "limit", "market", "stop_limit", and "oco" orders. Accepts English or Persian inputs (e.g. "خرید" for buy, "فروش" for sell, Persian numerals). Requires authentication.

Inputs: side (required), type (required), symbol (required), price, +5 more.

bitpin_refresh_tokenA

Refreshes an expired BitPin JWT access token using a refresh token. Rate limit: 200/day.

Inputs: refresh_token.

bitpin_set_access_tokenA

Manually set or update the active BitPin Bearer access token for the current session.

Inputs: access_token (required).

bitpin_verify_withdrawal_otpB

Verify and confirm a pending withdrawal using a 6-digit Authenticator code (OTP) and/or SMS OTP. Success confirms the withdrawal.

Inputs: otp (required), withdraw_id (required), is_second_otp.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions (markets, tickers, orderbook, orders, deposits, withdrawals). A few clusters need care—three withdrawal-creation tools (internal/crypto/irt) and three auth-related tools—but their descriptions make the boundaries clear. No true duplicates.

    Naming Consistency4/5

    Strong, consistent snake_case with a bitpin_ prefix and verb_noun pattern (get_markets, place_order, cancel_bulk_orders, create_crypto_withdrawal). Minor deviation where a couple tools use verb-only names (authenticate, refresh_token) instead of verb_noun, but still uniform in style.

    Tool Count4/5

    26 tools is at the upper edge but justified by the breadth of a full crypto-exchange API spanning auth, market data, wallets, deposits, withdrawals, and order lifecycle. Each tool maps to a distinct endpoint; nothing feels padding.

    Completeness5/5

    Lifecycle coverage is essentially complete: auth (login/refresh/set token), public market data, balances, deposit addresses and history, all withdrawal types plus OTP confirmation, and full order CRUD with bulk variants and fills. No obvious dead ends for trading or wallet workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with Bitget cryptocurrency exchange for spot and futures trading. Supports real-time market data, order management, account balances, leverage control, and position tracking with demo trading capabilities.
      17
      6
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to interact with the BitOasis cryptocurrency exchange, including market data, account management, order placement, and deposit/withdrawal operations through natural language.
      23
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to access BingX cryptocurrency exchange market data and execute trades through the official API, with support for account management, order creation, and technical indicators.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact directly with the Binance cryptocurrency exchange for trading, portfolio management, market analysis, and strategy automation via natural language.
      134 npm
      MIT