Yubit Exchange Skill

English | 中文

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
  • 4.1 OpenClaw
  • 4.2 Claude Code
  • 4.3 OpenAI Codex CLI
  • 4.4 Cursor
  • 4.5 LobeChat Desktop
• 5. Natural Language Examples
• 6. Available Tools
  • 6.1 Market
  • 6.2 Wallet
  • 6.3 Spot
  • 6.4 TradFi
  • 6.5 Earn
  • 6.6 Perp Query
  • 6.7 Perp Trade
  • 6.8 Diagnostics
• 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 public yubit skill.
• 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 Key
• API Secret
• API 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 perpCreateOrder again

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/perpClosePosition by settleCoin requires confirmBatch=true
• Separate-position add-to-position protection — perpAddToPosition queries current positions on the server first; in separate-position mode, it auto-targets the unique position or requires explicit pzLinkId, 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 Filled but perpGetPositions(symbol) returns empty, first check perpGetOrderHistory + perpGetExecutions + perpGetClosedPnl to 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:

1. perpGetOrderHistory(symbol, orderId): Confirm open order status is Filled
2. perpGetExecutions(symbol, orderId): Confirm actual fill qty, price, and time
3. perpGetPositions(symbol): Confirm the position is indeed empty
4. perpGetClosedPnl(symbol, limit='10'): Check whether a closed-P&L record with the same size and opposite direction appeared within seconds
5. If needed, use perpGetOrderHistory(symbol, closeOrderId) to check if the close order has reduceOnly=true

Notes:

• Values like M1ETHUSDT in 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()

17. License

MIT