外部做市商API接入流程

本文档介绍外部做市商如何接入 XBlade 交易平台，包括账户申请、API配置、开发集成和上线流程。

概述

XBlade 为专业做市商提供高性能、低延迟的 API 接口，支持程序化交易和流动性提供。做市商可以通过我们的 API 实现自动化交易策略，为平台提供更好的流动性。

做市商权益

手续费优惠

• Maker 手续费返佣或减免
• 根据交易量阶梯制定优惠方案
• VIP 账户专属费率

技术支持

• 专属技术支持团队
• 优先处理 API 请求
• 定制化接口支持

数据服务

• 实时市场数据推送
• 历史数据访问权限
• 深度行情数据

接入流程

1. 申请阶段

1.1 提交申请

填写做市商申请表，提供以下信息：

• 公司/团队基本信息
• 做市经验和策略介绍
• 预计交易规模
• 技术团队情况
• 联系方式

1.2 资质审核

平台将审核以下内容：

• 公司合法性和合规性
• 做市商历史记录和信誉
• 技术能力评估
• 风险控制能力
• 资金实力

1.3 协议签署

审核通过后，签署以下协议：

• 做市商服务协议
• 保密协议（NDA）
• 风险披露协议
• API 使用条款

2. 账户配置阶段

2.1 创建做市商账户

-- 创建做市商账户
INSERT INTO users (
    email,
    role,
    account_type,
    status,
    created_at
) VALUES (
    'mm@example.com',
    'market_maker',
    'institutional',
    'active',
    NOW()
);

-- 配置特殊费率
INSERT INTO fee_tiers (
    user_id,
    maker_fee,
    taker_fee,
    tier_level,
    start_date
) VALUES (
    (SELECT id FROM users WHERE email = 'mm@example.com'),
    -0.0001,  -- Maker 返佣
    0.0002,   -- Taker 费率
    'vip',
    NOW()
);

2.2 生成 API 凭证

为做市商账户生成专用的 API Key：

// API Key 格式
{
  "api_key": "mm_xxxxxxxxxxxxxxxxxxxxxxxx",
  "api_secret": "yyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "permissions": [
    "trade",
    "read_market_data",
    "read_account",
    "withdraw"
  ],
  "rate_limits": {
    "orders_per_second": 100,
    "requests_per_second": 200
  },
  "ip_whitelist": [
    "123.456.789.0/24"
  ]
}

2.3 配置权限和限制

• 设置 API 调用频率限制
• 配置 IP 白名单
• 设置单笔/日累计交易限额
• 配置风控参数

3. 技术集成阶段

3.1 API 认证

所有 API 请求需要使用 HMAC-SHA256 签名：

import hmac
import hashlib
import time
import requests

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "https://api.renance.xyz"

def generate_signature(method, endpoint, params, timestamp):
    """生成请求签名"""
    # 构建签名字符串
    param_str = "&".join([f"{k}={v}" for k, v in sorted(params.items())])
    message = f"{method.upper()}{endpoint}{param_str}{timestamp}"
    
    # 生成签名
    signature = hmac.new(
        API_SECRET.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return signature

def make_request(method, endpoint, params=None):
    """发送 API 请求"""
    if params is None:
        params = {}
    
    timestamp = str(int(time.time() * 1000))
    signature = generate_signature(method, endpoint, params, timestamp)
    
    headers = {
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
        "Content-Type": "application/json"
    }
    
    url = f"{BASE_URL}{endpoint}"
    
    if method.upper() == "GET":
        response = requests.get(url, params=params, headers=headers)
    elif method.upper() == "POST":
        response = requests.post(url, json=params, headers=headers)
    
    return response.json()

3.2 核心 API 接口

下单接口

# 限价单
def place_limit_order(symbol, side, price, quantity):
    """下限价单"""
    endpoint = "/api/v1/orders"
    params = {
        "symbol": symbol,
        "side": side,        # "buy" or "sell"
        "type": "limit",
        "price": price,
        "quantity": quantity,
        "timeInForce": "GTC"  # Good Till Cancel
    }
    return make_request("POST", endpoint, params)

# 市价单
def place_market_order(symbol, side, quantity):
    """下市价单"""
    endpoint = "/api/v1/orders"
    params = {
        "symbol": symbol,
        "side": side,
        "type": "market",
        "quantity": quantity
    }
    return make_request("POST", endpoint, params)

# 批量下单
def place_batch_orders(orders):
    """批量下单（最多 10 个订单）"""
    endpoint = "/api/v1/orders/batch"
    params = {"orders": orders}
    return make_request("POST", endpoint, params)

撤单接口

def cancel_order(order_id):
    """撤销单个订单"""
    endpoint = f"/api/v1/orders/{order_id}"
    return make_request("DELETE", endpoint)

def cancel_all_orders(symbol=None):
    """撤销所有订单（可指定交易对）"""
    endpoint = "/api/v1/orders/all"
    params = {"symbol": symbol} if symbol else {}
    return make_request("DELETE", endpoint, params)

查询接口

def get_order_book(symbol, depth=20):
    """获取订单簿"""
    endpoint = "/api/v1/market/depth"
    params = {"symbol": symbol, "limit": depth}
    return make_request("GET", endpoint, params)

def get_account_balances():
    """获取账户余额"""
    endpoint = "/api/v1/account/balances"
    return make_request("GET", endpoint)

def get_open_orders(symbol=None):
    """获取当前挂单"""
    endpoint = "/api/v1/orders/open"
    params = {"symbol": symbol} if symbol else {}
    return make_request("GET", endpoint, params)

def get_order_history(symbol=None, limit=100):
    """获取历史订单"""
    endpoint = "/api/v1/orders/history"
    params = {"symbol": symbol, "limit": limit} if symbol else {"limit": limit}
    return make_request("GET", endpoint, params)

3.3 WebSocket 实时数据

做市商可通过 WebSocket 接收实时市场数据：

import asyncio
import websockets
import json

WS_URL = "wss://api.renance.xyz/ws"

async def subscribe_orderbook(symbol):
    """订阅订单簿更新"""
    async with websockets.connect(WS_URL) as ws:
        # 认证
        auth_message = {
            "type": "auth",
            "api_key": API_KEY,
            "timestamp": int(time.time() * 1000),
            "signature": generate_ws_signature()
        }
        await ws.send(json.dumps(auth_message))
        
        # 订阅订单簿
        subscribe_message = {
            "type": "subscribe",
            "channel": "orderbook",
            "symbol": symbol,
            "depth": 20
        }
        await ws.send(json.dumps(subscribe_message))
        
        # 接收数据
        while True:
            message = await ws.recv()
            data = json.loads(message)
            print(f"Orderbook update: {data}")

# 运行
asyncio.run(subscribe_orderbook("BTC-USDT"))

可订阅的频道：

• orderbook - 订单簿更新
• trades - 最新成交
• ticker - 行情数据
• account - 账户更新（需认证）

3.4 做市策略示例

简单的网格做市策略：

class GridMarketMaker:
    def __init__(self, symbol, grid_size=0.001, num_levels=5, order_size=1.0):
        self.symbol = symbol
        self.grid_size = grid_size  # 网格间距（百分比）
        self.num_levels = num_levels  # 每侧订单层数
        self.order_size = order_size  # 每层订单大小
        self.active_orders = {}
    
    def calculate_grid_levels(self, mid_price):
        """计算网格挂单价格"""
        buy_levels = []
        sell_levels = []
        
        for i in range(1, self.num_levels + 1):
            # 买单价格（低于中间价）
            buy_price = mid_price * (1 - self.grid_size * i)
            buy_levels.append(buy_price)
            
            # 卖单价格（高于中间价）
            sell_price = mid_price * (1 + self.grid_size * i)
            sell_levels.append(sell_price)
        
        return buy_levels, sell_levels
    
    def place_grid_orders(self, mid_price):
        """下网格订单"""
        buy_levels, sell_levels = self.calculate_grid_levels(mid_price)
        
        orders = []
        
        # 买单
        for price in buy_levels:
            orders.append({
                "symbol": self.symbol,
                "side": "buy",
                "type": "limit",
                "price": round(price, 8),
                "quantity": self.order_size,
                "timeInForce": "GTC"
            })
        
        # 卖单
        for price in sell_levels:
            orders.append({
                "symbol": self.symbol,
                "side": "sell",
                "type": "limit",
                "price": round(price, 8),
                "quantity": self.order_size,
                "timeInForce": "GTC"
            })
        
        # 批量下单
        result = place_batch_orders(orders)
        return result
    
    def manage_orders(self):
        """订单管理主循环"""
        while True:
            try:
                # 获取当前订单簿
                orderbook = get_order_book(self.symbol)
                mid_price = (orderbook['bids'][0][0] + orderbook['asks'][0][0]) / 2
                
                # 取消所有现有订单
                cancel_all_orders(self.symbol)
                
                # 下新的网格订单
                self.place_grid_orders(mid_price)
                
                # 等待一段时间
                time.sleep(1)
                
            except Exception as e:
                print(f"Error: {e}")
                time.sleep(5)

# 使用示例
mm = GridMarketMaker("BTC-USDT", grid_size=0.001, num_levels=5, order_size=0.01)
mm.manage_orders()

4. 测试阶段

4.1 模拟环境测试

• 使用测试环境 API：https://testnet.renance.xyz
• 获取测试用 API Key
• 验证所有接口功能
• 测试异常情况处理

4.2 性能测试

import time
import statistics

def test_latency(num_requests=100):
    """测试 API 延迟"""
    latencies = []
    
    for i in range(num_requests):
        start = time.time()
        get_order_book("BTC-USDT")
        latency = (time.time() - start) * 1000  # ms
        latencies.append(latency)
    
    print(f"平均延迟: {statistics.mean(latencies):.2f}ms")
    print(f"P50 延迟: {statistics.median(latencies):.2f}ms")
    print(f"P99 延迟: {sorted(latencies)[int(len(latencies)*0.99)]:.2f}ms")

test_latency()

4.3 风控测试

• 测试 API 频率限制
• 测试订单大小限制
• 测试余额不足情况
• 测试异常价格拒单

5. 上线准备

5.1 准备工作

• 完成所有测试
• 准备生产环境服务器
• 配置监控和告警
• 准备应急预案
• 设置 IP 白名单

5.2 获取生产环境凭证

{
  "environment": "production",
  "api_endpoint": "https://api.renance.xyz",
  "ws_endpoint": "wss://api.renance.xyz/ws",
  "api_key": "prod_mm_xxxxxxxx",
  "api_secret": "yyyyyyyyyyyyyyyy",
  "rate_limits": {
    "orders_per_second": 100,
    "requests_per_second": 200
  }
}

5.3 启动做市服务

• 从小规模开始（小订单量、少交易对）
• 逐步增加交易规模
• 持续监控系统表现
• 根据市场情况调整策略

6. 运维监控

6.1 关键指标监控

class MMMonitor:
    """做市商监控"""
    
    def check_health(self):
        """健康检查"""
        metrics = {
            "api_latency": self.check_api_latency(),
            "order_fill_rate": self.check_fill_rate(),
            "inventory_balance": self.check_inventory(),
            "pnl_today": self.check_pnl(),
            "active_orders": len(get_open_orders()),
        }
        
        # 发送到监控系统
        self.send_metrics(metrics)
        
        # 检查告警条件
        if metrics["api_latency"] > 100:  # ms
            self.alert("API延迟过高")
        
        if abs(metrics["inventory_balance"]) > 0.2:  # 20%
            self.alert("库存失衡")
        
        return metrics

6.2 日常运维

• 监控 API 调用状态
• 跟踪订单成交情况
• 分析盈亏情况
• 优化做市参数
• 定期审查策略表现

API 限制和限流

频率限制

接口类型	限制	说明
市场数据	200 req/s	公开市场数据
下单接口	100 order/s	单个交易对
查询接口	50 req/s	账户查询
撤单接口	200 req/s	撤单请求

订单限制

• 单笔订单：最小 10 USDT，最大 500,000 USDT
• 批量下单：一次最多 10 个订单
• 挂单数量：每个交易对最多 200 个活跃订单

错误处理

常见错误码

ERROR_CODES = {
    1000: "无效的签名",
    1001: "API Key 不存在",
    1002: "权限不足",
    1003: "频率超限",
    2000: "余额不足",
    2001: "订单大小无效",
    2002: "价格超出限制",
    2003: "交易对不存在",
    3000: "系统错误",
}

def handle_error(error_code, message):
    """错误处理"""
    if error_code == 1003:  # 频率超限
        time.sleep(1)  # 等待后重试
    elif error_code in [2000, 2001, 2002]:  # 订单相关错误
        # 调整订单参数
        pass
    else:
        # 记录错误日志
        logging.error(f"Error {error_code}: {message}")

最佳实践

1. 连接管理

• 使用连接池复用 HTTP 连接
• WebSocket 断线自动重连
• 设置合理的超时时间

2. 风险控制

• 设置最大持仓限制
• 监控库存失衡
• 设置止损点
• 定期检查盈亏

3. 性能优化

• 本地维护订单簿缓存
• 批量操作（批量下单/撤单）
• 使用 WebSocket 获取实时数据
• 优化算法减少 API 调用

费用结算

手续费计算

def calculate_fees(trade_volume_30d):
    """根据 30 天交易量计算费率"""
    if trade_volume_30d >= 100_000_000:  # 1 亿
        return {"maker": -0.0002, "taker": 0.0001}  # Maker 返佣
    elif trade_volume_30d >= 50_000_000:  # 5000 万
        return {"maker": 0.0000, "taker": 0.0002}
    elif trade_volume_30d >= 10_000_000:  # 1000 万
        return {"maker": 0.0001, "taker": 0.0003}
    else:
        return {"maker": 0.0002, "taker": 0.0005}

返佣结算

• 每日结算手续费返佣
• 月度绩效奖励（根据提供的流动性）
• 特殊活动奖励

技术支持

支持渠道

• 技术支持邮箱：mm-support@xbladestudio.com
• 紧急热线：+86-xxx-xxxx-xxxx
• Telegram 群组：@xblade_mm
• 工单系统：https://support.renance.xyz

SLA 承诺

• API 可用性：99.9%
• P99 延迟：< 50ms
• WebSocket 消息延迟：< 10ms
• 故障响应时间：< 15分钟

相关文档

• 新币上架流程
• API 认证文档
• WebSocket 文档
• 错误码说明

附录

A. 测试环境信息

API 端点：https://testnet.renance.xyz
WebSocket：wss://testnet.renance.xyz/ws
测试币申请：testnet@xbladestudio.com

B. SDK 和工具

• Python SDK：pip install xblade-api
• JavaScript SDK：npm install @xblade/api
• API 测试工具：Postman Collection

C. 更新日志

• 2026-01-07：初始版本发布