Skip to main content
Glama
dwin-gharibi

ramzinex-mcp

by dwin-gharibi

A self-hostable Model Context Protocol server for the Ramzinex (رمزینکس) cryptocurrency exchange.

CI Docker Python 3.10+ License: MIT


Unofficial integration. This is a community-built MCP server. The "Ramzinex" name and logo belong to their owner. Not affiliated with, endorsed by, or sponsored by Ramzinex. Trading carries risk — use the order tools at your own risk.

What is this?

ramzinex-mcp exposes the Ramzinex exchange API as MCP tools and prompts so an LLM agent (Claude, etc.) can read markets, inspect an account, and — when you explicitly allow it — place and cancel orders. It is a small, stateless, async Python process you run yourself.

It mirrors the structure and quality of the sibling roshan-*-mcp servers: typed httpx client, pydantic-settings configuration, full test suite, Docker / Helm / Kubernetes / Terraform deploy assets, and generated architecture diagrams.

Related MCP server: Nobitex Market Data MCP Server

Public vs. private — and the trading guardrail

Ramzinex has two API bases, and this server routes each call to the right one automatically:

Surface

Base URL

Auth

Tools

Public

https://publicapi.ramzinex.com

none

market data (pairs, orderbooks, prices, currencies, networks)

Private

https://ramzinex.com

Authorization2: Bearer <token> + x-api-key: <api_key>

orders, funds/balances, deposits, withdrawals, addresses, rewards/commissions, API-key access management

🔐 Auth headers (Postman-accurate)

The live Ramzinex private API requires two non-standard headersnot the usual Authorization:

Authorization2: Bearer <token>
x-api-key: <api_key>

The header name carrying the token is configurable via auth_header_name (default Authorization2; set it to Authorization for legacy compatibility), and x-api-key is sent whenever an api_key is configured (send_x_api_key now defaults true). See Authentication.

⚠️ Money-moving & account-control safety

Some actions move real money or change what your API keys can do. They are gated by three separate per-instance flags, all default false:

  • enable_trading gates ramzinex_place_limit_order, ramzinex_place_market_order, ramzinex_cancel_order.

  • enable_withdrawals gates ramzinex_submit_withdraw, ramzinex_confirm_withdraw, and ramzinex_allocate_address (creating a deposit address is a wallet-write).

  • account_control gates ramzinex_edit_general_access and ramzinex_edit_private_access (API-key access management).

A master read_only flag forces all three off regardless of their values. When a gate is off the tool returns a structured refusal and never calls the API:

{"error": "trading_disabled", "message": "Set enable_trading=true (and read_only=false) on this instance to allow order placement/cancellation."}

Read-only tools (market data, viewing balances/orders) are always allowed. Tokens / secrets / api keys are never logged and are redacted from every error message. See Control flags & safety below.

Order lifecycle — placing is gated by enable_trading:

order-lifecycle

Withdrawals are separately gated by enable_withdrawals and require 2FA confirmation:

withdrawal-flow

Install

pip install -e .            # from a checkout
# or, for development:
pip install -e ".[dev]"

Requires Python 3.10+.

Quick start

Public market data needs no configuration at all:

python -m ramzinex_mcp          # stdio transport (default)

To use private (account) tools, authenticate with either a pre-issued bearer token or an api_key + secret pair (the server exchanges it for a token via the getToken login flow and re-issues automatically on a 401):

# Option A: pre-issued bearer token
export RAMZINEX_API_TOKEN=your-personal-api-token

# Option B: api_key + secret login flow (api_token wins if both are set)
export RAMZINEX_API_KEY=your-api-key
export RAMZINEX_SECRET=your-api-secret
# x-api-key is sent by default; the token rides in the Authorization2 header.
# export RAMZINEX_SEND_X_API_KEY=false      # opt out of the x-api-key header
# export RAMZINEX_AUTH_HEADER_NAME=Authorization  # legacy header-name mode

# Opt in to the gated tools (all default false):
export RAMZINEX_ENABLE_TRADING=true        # allow placing/cancelling orders
export RAMZINEX_ENABLE_WITHDRAWALS=true    # allow withdrawals + address allocation
export RAMZINEX_ACCOUNT_CONTROL=true       # allow API-key access management
python -m ramzinex_mcp

Run over HTTP for networked clients:

python -m ramzinex_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Configuration (multi-account / multi-instance)

Configuration is read from environment variables via pydantic-settings. One process can front many Ramzinex accounts — each is a named instance with its own token and trading policy. Every API tool accepts an optional instance argument; omit it to use the default.

Shorthand (single default instance)

Variable

Default

Description

RAMZINEX_API_TOKEN

Pre-issued bearer token for private endpoints (wins over api_key+secret).

RAMZINEX_API_KEY

API key for the getToken login flow (with RAMZINEX_SECRET); also sent as x-api-key.

RAMZINEX_SECRET

API secret paired with RAMZINEX_API_KEY.

RAMZINEX_AUTH_HEADER_NAME

Authorization2

Header that carries the bearer token (set Authorization for legacy mode).

RAMZINEX_SEND_X_API_KEY

true

Also send x-api-key: <api_key> on private calls (the live API needs it).

RAMZINEX_PUBLIC_BASE_URL

https://publicapi.ramzinex.com

Public base URL.

RAMZINEX_PRIVATE_BASE_URL

https://ramzinex.com

Private base URL.

RAMZINEX_API_VERSION

v1.0

API version segment for the exchange paths.

RAMZINEX_ENABLE_TRADING

false

Allow placing/cancelling orders.

RAMZINEX_ENABLE_WITHDRAWALS

false

Allow withdrawals + deposit-address allocation.

RAMZINEX_ACCOUNT_CONTROL

false

Allow API-key access management (edit general/private access).

RAMZINEX_READ_ONLY

false

Master switch: forces all three gates off.

RAMZINEX_VERIFY_SSL

true

Verify TLS certificates.

RAMZINEX_TIMEOUT

30

Per-request timeout (seconds).

RAMZINEX_DEFAULT_INSTANCE

default

Instance used when instance is omitted.

RAMZINEX_LOG_LEVEL

INFO

DEBUG / INFO / WARNING / ...

Nested (named instances)

Variable

Description

RAMZINEX__INSTANCES__<NAME>__API_TOKEN

Pre-issued bearer token for instance <NAME>.

RAMZINEX__INSTANCES__<NAME>__API_KEY

API key for <NAME>'s getToken login flow (also sent as x-api-key).

RAMZINEX__INSTANCES__<NAME>__SECRET

API secret for <NAME>'s getToken login flow.

RAMZINEX__INSTANCES__<NAME>__AUTH_HEADER_NAME

Bearer-token header name for <NAME> (default Authorization2).

RAMZINEX__INSTANCES__<NAME>__SEND_X_API_KEY

Send x-api-key on <NAME>'s private calls (default true).

RAMZINEX__INSTANCES__<NAME>__ENABLE_TRADING

Trading switch for <NAME>.

RAMZINEX__INSTANCES__<NAME>__ENABLE_WITHDRAWALS

Withdrawals + address-allocation switch for <NAME>.

RAMZINEX__INSTANCES__<NAME>__ACCOUNT_CONTROL

API-key access-management switch for <NAME>.

RAMZINEX__INSTANCES__<NAME>__READ_ONLY

Master switch (forces all three gates off) for <NAME>.

RAMZINEX__INSTANCES__<NAME>__API_VERSION

API version for <NAME>.

RAMZINEX__INSTANCES__<NAME>__PUBLIC_BASE_URL

Public base for <NAME>.

RAMZINEX__INSTANCES__<NAME>__PRIVATE_BASE_URL

Private base for <NAME>.

RAMZINEX__INSTANCES__<NAME>__VERIFY_SSL

TLS verification (default true).

RAMZINEX__INSTANCES__<NAME>__TIMEOUT

Per-request timeout seconds (default 30).

RAMZINEX__DEFAULT_INSTANCE

Instance used when instance is omitted.

RAMZINEX__LOG_LEVEL

DEBUG / INFO / WARNING / ...

Example: a read-only personal account, a trading bot using api_key+secret, and a strictly read-only viewer.

RAMZINEX__INSTANCES__PERSONAL__API_TOKEN=personal-token
RAMZINEX__INSTANCES__PERSONAL__ENABLE_TRADING=false
RAMZINEX__INSTANCES__BOT__API_KEY=bot-key
RAMZINEX__INSTANCES__BOT__SECRET=bot-secret
RAMZINEX__INSTANCES__BOT__ENABLE_TRADING=true
RAMZINEX__INSTANCES__READONLY__API_TOKEN=viewer-token
RAMZINEX__INSTANCES__READONLY__READ_ONLY=true
RAMZINEX__DEFAULT_INSTANCE=personal

See .env.example for a complete, annotated file. Use list_instances to see what's configured (names, base URLs, api_version, auth_header_name, has_credentials, auth_method, enable_trading, enable_withdrawals, account_control, read_only) — it never reveals credential values.

Authentication: a pre-issued api_token, or api_key+secret exchanged for a cached Bearer (refreshed on 401):

auth-flow

Control flags & safety

Three independent gates plus a master switch protect the account. Use the effective trading_allowed / withdrawals_allowed / account_control_allowed values from list_instances (they already fold in read_only):

Flag

Default

Gates

Effective when

enable_trading

false

ramzinex_place_limit_order, ramzinex_place_market_order, ramzinex_cancel_order

enable_trading=true and read_only=false

enable_withdrawals

false

ramzinex_submit_withdraw, ramzinex_confirm_withdraw, ramzinex_allocate_address

enable_withdrawals=true and read_only=false

account_control

false

ramzinex_edit_general_access, ramzinex_edit_private_access

account_control=true and read_only=false

read_only

false

forces all three of the above off

When a gate is off, the tool returns {"error": "trading_disabled" / "withdrawals_disabled" / "account_control_disabled", "message": ...} and never contacts the API. ramzinex_refresh_deposits is a non-money-moving refresh and is not gated.

Authentication: api_token vs api_key + secret

Private endpoints require two non-standard headers: Authorization2: Bearer <token> and x-api-key: <api_key> (the live API does not use the standard Authorization). The token-carrying header name is configurable via auth_header_name (default Authorization2; set Authorization for legacy mode), and x-api-key is sent whenever an api_key is configured (send_x_api_key defaults true).

  • api_token — a pre-issued bearer token, sent directly as Authorization2: Bearer <token>. Simplest; takes precedence if both are set.

  • api_key + secret — the server POSTs them to auth/api_key/getToken, caches the returned token in memory per instance, reuses it, and re-authenticates once on a 401. Call ramzinex_authenticate to trigger/verify the login explicitly (it never returns the token). The api_key doubles as the x-api-key header value. Tokens, secrets, and api keys are never logged or echoed (Authorization2 / Authorization / x-api-key / secret / api_key are all redacted from errors).

The read_only master switch overrides the trading / withdrawal / account-control gates:

safety-gates

Use with an MCP client

Add it to your client's MCP server config (stdio):

{
  "mcpServers": {
    "ramzinex": {
      "command": "python",
      "args": ["-m", "ramzinex_mcp"],
      "env": {
        "RAMZINEX_API_TOKEN": "your-personal-api-token",
        "RAMZINEX_ENABLE_TRADING": "false"
      }
    }
  }
}

Tools

All 45 tools (42 service endpoints + 3 meta) accept an optional instance (except the two local meta tools, list_instances and ramzinex_docs). Private tools send Authorization2: Bearer <token> + x-api-key: <api_key>.

Market data — public, no auth

Tool

Endpoint

ramzinex_get_pairs

GET /exchange/api/v1.0/exchange/pairs

ramzinex_get_pair(pair_id)

GET .../pairs/{pair_id}

ramzinex_get_orderbook(pair_id)

GET .../orderbooks/{pair_id}/buys_sells

ramzinex_get_all_orderbooks

GET .../orderbooks/buys_sells

ramzinex_get_orderbook_buys(pair_id)

GET .../orderbooks/{pair_id}/buys

ramzinex_get_orderbook_sells(pair_id)

GET .../orderbooks/{pair_id}/sells

ramzinex_get_market_buy_price(pair_id, amount2)

GET .../orderbooks/{pair_id}/market_buy_price

ramzinex_get_market_sell_price(pair_id, amount)

GET .../orderbooks/{pair_id}/market_sell_price

ramzinex_get_prices

GET /exchange/api/exchange/prices

ramzinex_get_currencies

GET .../currencies

ramzinex_get_networks(currency_id?, withdraw?, deposit?)

GET .../networks

Auth & access management — private

Tool

Endpoint

Notes

ramzinex_authenticate

POST .../auth/api_key/getToken

Runs the api_key+secret login flow; caches the token (never returns it).

ramzinex_edit_general_access(address_free, alert)

POST .../auth/api_key/editGeneralAccess

⚠️ gated by account_control

ramzinex_edit_private_access(api_key_id, withdraw, trade, cancel, excel, ip_free, ips?)

POST .../auth/api_key/editPrivateAccess

⚠️ gated by account_control

Orders — private

Tool

Endpoint

Notes

ramzinex_get_orders(limit, offset, types, pairs, currencies, states, is_buy)

POST .../users/me/orders2

read-only

ramzinex_get_order(order_id)

GET .../users/me/orders2/{order_id}

read-only

ramzinex_place_limit_order(pair_id, amount, price, type)

POST .../users/me/orders/limit

⚠️ gated by enable_trading

ramzinex_place_market_order(pair_id, amount, type)

POST .../users/me/orders/market

⚠️ gated by enable_trading

ramzinex_cancel_order(order_id)

POST .../users/me/orders/{order_id}/cancel

⚠️ gated by enable_trading

ramzinex_get_turnover(days=30)

GET .../users/me/orders/turnover

read-only

Funds — private

Tool

Endpoint

ramzinex_get_funds

GET .../users/me/funds/details

ramzinex_get_currency_fund(currency_id)

GET .../funds/details/currency/{currency_id}

ramzinex_get_balance_summary

GET .../users/me/funds/summaryDesktop

ramzinex_get_total_balance(currency_id)

GET .../funds/total/currency/{currency_id}

ramzinex_get_available_balance(currency_id)

GET .../funds/available/currency/{currency_id}

ramzinex_get_in_orders_balance(currency_id)

GET .../funds/in_orders/currency/{currency_id}

ramzinex_get_rial_equivalent

GET .../users/me/funds/rial_equivalent

ramzinex_get_usdt_equivalent

GET .../users/me/funds/usdt_equivalent

ramzinex_refresh_funds

POST .../users/me/funds/refresh

Wallet (deposits / withdrawals / addresses) — private

Tool

Endpoint

Notes

ramzinex_get_addresses(networks)

POST .../users/me/addresses

read-only

ramzinex_allocate_address(network_id, currency_id?)

POST .../users/me/addresses/generate

⚠️ gated by enable_withdrawals; best-effort path (confirm against panel)

ramzinex_get_deposits(limit, offset)

GET .../funds/deposits

read-only

ramzinex_get_currency_deposits(currency_id, limit, offset)

GET .../funds/deposits/currency/{currency_id}

read-only

ramzinex_get_deposit(deposit_id)

GET .../funds/deposits/{deposit_id}

read-only

ramzinex_refresh_deposits(currency_id)

POST .../funds/deposits/refresh/currency/{currency_id}

refresh (no funds moved)

ramzinex_get_withdraws(limit, offset, currency_id?)

GET .../funds/withdraws

read-only

ramzinex_get_currency_withdraws(currency_id)

GET .../funds/withdraws/currency/{currency_id}

read-only

ramzinex_get_withdraw(withdraw_id)

GET .../funds/withdraws/{withdraw_id}

read-only

ramzinex_submit_withdraw(currency_id, amount, address, network_id, tag?)

POST .../funds/withdraws/currency/{currency_id}

⚠️ gated by enable_withdrawals

ramzinex_confirm_withdraw(withdraw_id, code, ga_code)

POST .../funds/withdraws/{withdraw_id}/verify

⚠️ gated by enable_withdrawals

Rewards & commissions — private

Tool

Endpoint

Notes

ramzinex_get_rewards

GET .../users/me/rewards

read-only; best-effort path (confirm against panel)

ramzinex_get_commissions

GET .../users/me/commissions

read-only; best-effort path (confirm against panel)

Meta

Tool

Description

healthcheck

Pings the public pairs endpoint and reports reachability.

list_instances

Lists configured instances (base URLs, api_version, auth_header_name, has_credentials, auth_method, enable_trading, enable_withdrawals, account_control, read_only) — never credential values.

ramzinex_docs(topic?)

Offline reference + links to https://ramzinex.com/exchange/apidocs.

All endpoints at a glance, grouped by category:

endpoint-map

API coverage

Every section/endpoint of the official Postman collection maps to a tool. The source column is postman for items present in the collection text and best-effort for the three tools whose exact URLs the pasted collection did not include (rewards, commissions, and deposit-address allocation) — confirm those against the Ramzinex panel/Postman.

Postman section / endpoint

Method

Path

Tool

Source

Market — pairs

GET

/.../exchange/pairs

ramzinex_get_pairs

postman

Market — pair

GET

/.../exchange/pairs/{id}

ramzinex_get_pair

postman

Market — orderbook

GET

/.../orderbooks/{id}/buys_sells

ramzinex_get_orderbook

postman

Market — all orderbooks

GET

/.../orderbooks/buys_sells

ramzinex_get_all_orderbooks

postman

Market — orderbook buys

GET

/.../orderbooks/{id}/buys

ramzinex_get_orderbook_buys

postman

Market — orderbook sells

GET

/.../orderbooks/{id}/sells

ramzinex_get_orderbook_sells

postman

Market — market buy price

GET

/.../orderbooks/{id}/market_buy_price

ramzinex_get_market_buy_price

postman

Market — market sell price

GET

/.../orderbooks/{id}/market_sell_price

ramzinex_get_market_sell_price

postman

Market — prices feed

GET

/exchange/api/exchange/prices

ramzinex_get_prices

postman

Market — currencies

GET

/.../exchange/currencies

ramzinex_get_currencies

postman

Market — networks

GET

/.../exchange/networks

ramzinex_get_networks

postman

Auth — getToken

POST

/.../auth/api_key/getToken

ramzinex_authenticate

postman

Auth — editGeneralAccess

POST

/.../auth/api_key/editGeneralAccess

ramzinex_edit_general_access

postman

Auth — editPrivateAccess

POST

/.../auth/api_key/editPrivateAccess

ramzinex_edit_private_access

postman

Orders — list

POST

/.../users/me/orders2

ramzinex_get_orders

postman

Orders — get

GET

/.../users/me/orders2/{id}

ramzinex_get_order

postman

Orders — limit

POST

/.../users/me/orders/limit

ramzinex_place_limit_order

postman

Orders — market

POST

/.../users/me/orders/market

ramzinex_place_market_order

postman

Orders — cancel

POST

/.../users/me/orders/{id}/cancel

ramzinex_cancel_order

postman

Orders — turnover

GET

/.../users/me/orders/turnover

ramzinex_get_turnover

postman

Funds — details

GET

/.../users/me/funds/details

ramzinex_get_funds

postman

Funds — currency detail

GET

/.../funds/details/currency/{id}

ramzinex_get_currency_fund

postman

Funds — summaryDesktop

GET

/.../funds/summaryDesktop

ramzinex_get_balance_summary

postman

Funds — total

GET

/.../funds/total/currency/{id}

ramzinex_get_total_balance

postman

Funds — available

GET

/.../funds/available/currency/{id}

ramzinex_get_available_balance

postman

Funds — in_orders

GET

/.../funds/in_orders/currency/{id}

ramzinex_get_in_orders_balance

postman

Funds — rial equivalent

GET

/.../funds/rial_equivalent

ramzinex_get_rial_equivalent

postman

Funds — usdt equivalent

GET

/.../funds/usdt_equivalent

ramzinex_get_usdt_equivalent

postman

Funds — refresh

POST

/.../funds/refresh

ramzinex_refresh_funds

postman

Wallet — addresses

POST

/.../users/me/addresses

ramzinex_get_addresses

postman

Wallet — allocate address

POST

/.../users/me/addresses/generate

ramzinex_allocate_address

best-effort

Wallet — deposits

GET

/.../funds/deposits

ramzinex_get_deposits

postman

Wallet — currency deposits

GET

/.../funds/deposits/currency/{id}

ramzinex_get_currency_deposits

postman

Wallet — deposit

GET

/.../funds/deposits/{id}

ramzinex_get_deposit

postman

Wallet — refresh deposits

POST

/.../funds/deposits/refresh/currency/{id}

ramzinex_refresh_deposits

postman

Wallet — withdraws

GET

/.../funds/withdraws

ramzinex_get_withdraws

postman

Wallet — currency withdraws

GET

/.../funds/withdraws/currency/{id}

ramzinex_get_currency_withdraws

postman

Wallet — withdraw

GET

/.../funds/withdraws/{id}

ramzinex_get_withdraw

postman

Wallet — submit withdraw

POST

/.../funds/withdraws/currency/{id}

ramzinex_submit_withdraw

postman

Wallet — confirm withdraw

POST

/.../funds/withdraws/{id}/verify

ramzinex_confirm_withdraw

postman

Rewards — rewards

GET

/.../users/me/rewards

ramzinex_get_rewards

best-effort

Rewards — commissions

GET

/.../users/me/commissions

ramzinex_get_commissions

best-effort

Meta — reachability

GET

/.../exchange/pairs

healthcheck

local

Meta — instances

(local)

list_instances

local

Meta — docs

(local)

ramzinex_docs

local

⚠ = money-moving or account-control; gated by enable_trading / enable_withdrawals / account_control (all forced off by read_only).

Prompts

The server also ships MCP prompts — safety-aware workflows your client can list and run (details in prompts/README.md):

  • market_overview — pull pairs + an orderbook and summarize the market.

  • check_balances — walk the funds/balance tools to report holdings.

  • place_trade_safely — a careful checklist that verifies enable_trading and confirms parameters before placing a REAL order.

  • portfolio_report — combine funds + open orders + turnover.

Skill

A ready-to-use Claude/agent skill lives at skills/ramzinex/SKILL.md. It describes when and how to use these tools — market lookup, balance checks, and the safe trading flow — with example tool sequences.

Architecture

The MCP client talks to one ramzinex-mcp process, which routes public calls to publicapi.ramzinex.com and authenticated calls (with the Authorization2 + x-api-key headers) to ramzinex.com.

architecture

One process can serve many accounts; the instance argument selects which token / trading policy to use.

self-hosting

A typical flow: read the market on the public API, check the enable_trading gate, then place and confirm an order on the private API.

request-flow

Regenerate the diagrams with make diagrams (uses the diagrams package + Graphviz dot and cairosvg).

Self-hosting & scaling

ramzinex-mcp is stateless, so you can run as many replicas as you like behind a load balancer. One process fronts multiple accounts via RAMZINEX__INSTANCES__<NAME>__* — no code change. Back off on HTTP 429 if the exchange rate-limits you. See deploy/ for Docker Compose, Kubernetes (raw + Kustomize), a Helm chart, and a Terraform module.

Testing

make smoke          # no-network smoke test (tools + prompts + descriptions)
make test           # full pytest suite (offline; all HTTP mocked with respx)
make lint           # ruff

Live tests against the real API are skipped unless RAMZINEX_LIVE=1 is set (and, for private endpoints, RAMZINEX_API_TOKEN):

RAMZINEX_LIVE=1 pytest tests/live -q

License

MIT. ramzinex-mcp is an unofficial, community-built integration; the Ramzinex name and logo belong to their owner.

Install Server
A
license - permissive license
A
quality
B
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dwin-gharibi/ramzinex-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server