Yubit Exchange Skill
The Yubit Exchange MCP Server lets AI assistants query market data, manage funds, check balances across spot, TradFi, and earn accounts, and execute perpetual trades using natural language.
It works with OpenClaw, Claude Code, OpenAI Codex, Cursor, LobeChat Desktop, and any other AI tool compatible with the MCP protocol.
Table of Contents
- 1. Feature Overview
- 2. Modules
- 3. Quick Start
- 4. Manual Setup
- 5. Natural Language Examples
- 6. Available Tools
- 7. Permission Levels
- 8. Security Mechanisms
- 9. Environment Variables
- 10. Agent Skills
- 11. CLI Commands
- 12. Project Structure
- 13. Testing
- 14. Contributing
- 15. FAQ
- 16. Signing Algorithm
- 17. License
1. Feature Overview
2. Modules
Full usage rules, account semantics, trading constraints, and troubleshooting rules are in
skills/yubit/SKILL.md.
3. Quick Start
Prerequisites: Node.js >= 19
Recommended installation paths:
OpenClaw Hub: For OpenClaw users. Install the runtime first, then install the publicyubitskill.npm / npx: Recommended for most MCP clients, including Claude Code, Codex, Cursor, LobeChat Desktop, and local OpenClaw integration.Source install: Best for local development, debugging, or running directly from the repository.
3.1 OpenClaw Hub Install
npm install -g @yubit/exchange-skill
yubit setup --client openclaw
openclaw skills install yubit
After setup finishes, start a new OpenClaw session for the yubit skill so the MCP server is loaded.
3.2 General Install
# Global npm install
npm install -g @yubit/exchange-skill
yubit setup
# Or npx (no install required)
npx @yubit/exchange-skill setup
The setup wizard automatically detects supported AI tools, configures your API credentials, and registers the MCP server. During first-time setup, you will be prompted for:
API KeyAPI SecretAPI Base URL
Credentials are stored in ~/.exchange-skill/config.json and shared across all clients. To rotate your keys, run yubit config init.
3.3 Source Install
git clone https://github.com/yubit-exchange/exchange-skill.git
cd exchange-skill
./setup/install.sh
Use this path when running from source or doing local development and debugging.
4. Manual Setup (Optional)
If you prefer not to use yubit setup, or want to control the MCP configuration manually, use the following methods.
4.1 OpenClaw
openclaw mcp set yubit '{
"command": "yubit",
"args": ["start"],
"env": { "EXCHANGE_ENABLE_TRADE": "true" }
}'
rm -rf ~/.openclaw/skills/yubit ~/.openclaw/skills/yubit-*
cp -r skills/yubit ~/.openclaw/skills/
openclaw gateway restart
4.2 Claude Code
claude mcp add --transport stdio yubit --env EXCHANGE_ENABLE_TRADE=true -- yubit start
4.3 OpenAI Codex CLI
# ~/.codex/config.toml
[mcp_servers.yubit]
command = "yubit"
args = ["start"]
[mcp_servers.yubit.env]
EXCHANGE_ENABLE_TRADE = "true"
4.4 Cursor
// ~/.cursor/mcp.json
{
"mcpServers": {
"yubit": {
"command": "yubit",
"args": ["start"],
"env": { "EXCHANGE_ENABLE_TRADE": "true" }
}
}
}
4.5 LobeChat Desktop
The web version does not support STDIO MCP. You must use the desktop app.
Open the plugin menu → Add MCP Plugin → Quick Import JSON → paste the same JSON shown for Cursor above → select STDIO as the connection type.
5. Natural Language Examples
Usage recommendations:
- Open new position →
perpCreateOrder- Add to existing position →
perpAddToPosition- Especially in separate-position mode, do not treat "add to existing position" as simply calling
perpCreateOrderagain
6. Available Tools
6.1 Market (Public, no auth required)
6.2 Wallet (API Key required)
6.3 Spot (API Key required)
6.4 TradFi (API Key required)
6.5 Earn (API Key required)
6.6 Perp Query (API Key required)
6.7 Perp Trade (API Key + EXCHANGE_ENABLE_TRADE=true)
6.8 Diagnostics (No auth required)
7. Permission Levels
8. Security Mechanisms
- Pre-validation — symbol, quantity range/step, price range, TP/SL direction, leverage range are validated upfront and rejected if non-compliant
- Batch operation protection —
perpCancelAllOrders/perpClosePositionby settleCoin requiresconfirmBatch=true - Separate-position add-to-position protection —
perpAddToPositionqueries current positions on the server first; in separate-position mode, it auto-targets the unique position or requires explicitpzLinkId, then reads back to verify no accidental new sub-position was opened - Intent routing — documentation and skills route "open new position" and "add to existing position" as two separate paths, reducing the risk of the model misinterpreting "add to position" as "open a new sub-position"
- Filled-order-but-no-position troubleshooting — if a market order to open a position is marked
FilledbutperpGetPositions(symbol)returns empty, first checkperpGetOrderHistory+perpGetExecutions+perpGetClosedPnlto determine whether the position was closed by a later reverse order; do not start by guessing about symbol mapping or position delays - Audit log — all calls are logged to
.data/audit.log(JSON Lines), with sensitive information automatically redacted - Trace records — each call is recorded to
.data/trace-records.jsonl, including raw HTTP request/response, retained for 7 days / max 1000 entries - Centralized credential management —
~/.exchange-skill/config.json; client configs do not contain API Key
8.1 Troubleshooting: Filled Order but No Open Position
If a market order to open a position succeeds and an execution is recorded, but the subsequent position query is empty, follow this sequence:
perpGetOrderHistory(symbol, orderId): Confirm open order status isFilledperpGetExecutions(symbol, orderId): Confirm actual fill qty, price, and timeperpGetPositions(symbol): Confirm the position is indeed emptyperpGetClosedPnl(symbol, limit='10'): Check whether a closed-P&L record with the same size and opposite direction appeared within seconds- If needed, use
perpGetOrderHistory(symbol, closeOrderId)to check if the close order hasreduceOnly=true
Notes:
- Values like
M1ETHUSDTin order history are usually just the exchange's internal symbol format. They do not mean the position is hidden under a different symbol. - The more common real cause is that the position was already closed by a later close order.
9. Environment Variables
10. Agent Skills
11. CLI Commands
12. Project Structure
exchange-skill/
├── mcp-server.js # MCP Server entry point
├── bin/cli.js # CLI
├── lib/
│ ├── signer.js # HMAC-SHA256 signing
│ ├── http.js # HTTP client (with rate limiting)
│ ├── config.js # Config loader
│ ├── validate.js # Parameter validation
│ ├── normalize.js # Response normalization
│ ├── audit.js # Audit logging
│ ├── trace-store.js # Trace storage/retrieval
│ ├── capabilities.js # Capability snapshot builder
│ └── setup/ # Client management
├── tools/
│ ├── market.js # Market (9 tools)
│ ├── spot.js # Spot query (1 tool)
│ ├── tradfi.js # TradFi query (1 tool)
│ ├── earn.js # Earn query (1 tool)
│ ├── perp-query.js # Perp query (9 tools)
│ ├── perp.js # Perp trade (12 tools)
│ ├── wallet.js # Wallet (3 tools)
│ └── diagnostics.js # Diagnostics (3 tools)
├── skills/ # AI Agent behavior specs
└── test/ # Unit tests + smoke tests
13. Testing
npm test # Unit tests (no network required)
npm run test:smoke # Smoke tests (requires API Key, executes real trades)
npm run test:all # All tests
Smoke tests will place real orders, cancel them, and close positions. Use a dedicated test account.
14. Contributing
New tools should follow the existing naming convention: {product}{Action} camelCase. Product-specific tools get a prefix (perp/spot/tradfi/earn/tapTrading); shared tools have no prefix.
npm test && npm run test:smoke # Must pass after any changes
15. FAQ
16. Signing Algorithm
payload = timestamp + apiKey + recvWindow + payload
signature = HMAC-SHA256(apiSecret, payload).hex()
