ccxt / Architecture

ccxt 架构：统一接口如何收口 100+ 交易所

ccxt 的核心是「统一接口」：你在代码里只面对一套方法名，ccxt 内部把每个方法翻译成对应交易所的私有 REST API。理解这三层，就能看懂为什么换交易所几乎不用改业务代码。

看三层结构去安装

分层：exchange 实例 / 统一方法 / 适配器接口：公开 + 私有基于官方 README

exchange 实例ccxt.binance() / ccxt.okx() 等

统一方法fetchTicker / fetchOHLCV / createOrder

交易所适配器翻译成各交易所 REST API

ccxt 架构分层示意（exchange 实例 → 统一方法 → 交易所适配器），基于官方 README，非官方架构图。

Layers

三层结构

ccxt 把「统一接口」落实到三层，每一层解决一个不同的问题。

层	作用	示例
exchange 实例	代表一个具体交易所，承载配置（API key / 代理）	`exchange = ccxt.binance()`
统一方法	跨交易所一致的方法名与参数约定	`exchange.fetchOHLCV('BTC/USDT','1h')`
交易所适配器	把统一方法翻译成该交易所的 REST 调用并解析响应	各交易所专属实现文件

说明：ccxt 的「统一」指方法名和数据结构尽量一致，但不同交易所支持的交易对、精度、限频仍有差异，实际使用需查阅该交易所的接口覆盖情况。

Public vs Private

公开接口与私有接口

按是否需要账号授权，ccxt 的接口分两类，这决定了你要不要先申请 API key。

类型	典型方法	是否需 API key
公开接口	fetchTicker / fetchOHLCV / fetchOrderBook / fetchTrades / fetchTickers	否
私有接口	fetchBalance / createOrder / cancelOrder / fetchOrders / deposit / withdraw	是（交易所账号 + API key）

看公开行情数据接口看私有接口与下单

Error handling

异常类型层级与限频处理

ccxt 的异常都继承自 ccxt.BaseError，统一捕获 ccxt.NetworkError 与 ccxt.ExchangeError 两个大类即可兜底。下面是真实层级与触发场景。

BaseError
├── NetworkError                网络层失败（重试 + 退避）
│   ├── DDoSProtection          Cloudflare / 反爬拦截
│   ├── RateLimitExceeded       触发交易所限频（降频 / 开 enableRateLimit）
│   ├── ExchangeNotAvailable    交易所维护 / 不可用
│   └── RequestTimeout          请求超时
└── ExchangeError               业务层错误（检查参数与账号）
    ├── AuthenticationError     API key 无效 / 签名错误
    ├── PermissionDenied        API key 权限不足
    ├── InsufficientFunds       余额不足
    ├── InvalidAddress          充提地址非法
    ├── BadSymbol               交易对不存在
    ├── InvalidOrder            订单参数非法
    │   ├── OrderNotFound       撤单/查询时订单不存在
    │   └── DuplicateOrderId    重复的客户端订单 id
    └── NotSupported            该交易所不支持此方法

异常类型	含义	处理建议
NetworkError	网络/连接失败	重试并指数退避
ExchangeError	交易所返回的业务错误	检查参数与交易对
AuthenticationError	API key 无效或签名错误	核对 apiKey/secret 与时间同步
RateLimitExceeded	触发交易所限频	降频或开启 enableRateLimit
InsufficientFunds	余额不足	降低下单量或补充资金
BadSymbol / InvalidOrder	交易对或订单参数错误	核对符号与参数格式

说明：ccxt 提供 enableRateLimit 开关与 rateLimit 属性用于内置限频。跨交易所的稳健写法是：try: ... except ccxt.NetworkError: 重试 + except ccxt.ExchangeError as e: 按 e 类型处理。具体异常类名以官方文档为准。

Config

版本、代理与全局配置

生产使用时常需配置代理、限频与超时，这些通常在初始化 exchange 实例时传入。

import ccxt

exchange = ccxt.binance({
    'enableRateLimit': True,     # 开启内置限频
    'proxies': {                 # 可选：HTTP/HTTPS/SOCKS5 代理
        'http': 'http://127.0.0.1:7890',
        'https': 'http://127.0.0.1:7890',
    },
    'timeout': 30000,            # 毫秒
})

说明：代理（proxy/socks5）与限频是常见配置项，参数名以官方文档为准。

看行情数据接口

FAQ

常见问题

为什么换交易所几乎不用改代码？

因为业务代码调用的是统一方法（如 fetchOHLCV），只有实例化那一行（如 ccxt.binance() 换成 ccxt.okx()）需要改，其余逻辑保持一致。

所有交易所的接口都一样吗？

不完全一样。ccxt 尽量统一方法名与返回结构，但不同交易所支持的交易对、精度、限频和部分参数仍不同，需要查文档确认。

ccxt 是托管平台吗？

不是。ccxt 是非托管（non-custodian）库，不持有用户资金，只负责调用交易所接口。