Canton Venues

Canton Venues SDK

Canton 算法交易工具包：一个开源 Python SDK，用于交易和读取 Canton Network 上的所有交易场所。它为 cantonvenues.com 提供支持。 安装并将其导入为 cantonvenues。

核心模块（cantonvenues.core）与交易场所无关：包含一个小型的类型化领域模型和四个适配器接口，并共用一套 VenueError 异常层级。

• PoolDataAdapter — 读取 AMM 并为其定价：Instrument、Pool、Quote。
• VenueAdapter — 可用于交易的 PoolDataAdapter：Balance、SwapResult。
• MarketDataAdapter — 只读市场状态，适用于以交易品种和订单簿为核心，而非资金池和兑换的交易场所：Market、OrderBook、Trade、Ticker、FundingRate。
• OrderTradingAdapter — 可用于交易的 MarketDataAdapter：限价订单（仅挂单，带到期时间）、撤单、未结订单、余额。除非构建适配器时设置 trading=True，否则交易功能处于关闭状态，因此持有相同密钥的市场数据读取器永远无法下单。

八个交易场所、四种市场结构、一个客户端：

Adapter	交易场所	类型	功能范围
TempleAdapter	Temple	现货订单簿	无需密钥即可读取已结算交易量；使用账户密钥可读取行情、订单簿和交易记录；限价订单和撤单需选择启用（订单路径尚未进行首次实盘运行）
CantexAdapter	Cantex	现货 AMM	读取 + 兑换，主网
CantexPublicData	Cantex	现货 AMM	无需密钥即可读取储备量、交易量、K 线和行情，主网
RockyAdapter	Rocky	现货和永续合约订单簿	市场数据，主网，无需密钥
TradecraftAdapter	Tradecraft	现货 AMM	读取 + 定价，主网
OneSwapPublicData	OneSwap	现货 AMM	无需密钥即可读取储备量，主网
PoolPartyPublicData	Pool Party	现货 AMM	无需密钥即可读取储备量和交易量，主网
EkidenAdapter	Ekiden	永续期货	市场数据，主网（也提供测试网）
CanborsaPublicData	Canborsa	永续期货	无需密钥即可读取市场、资金费率、价格和执行深度，主网（网页应用路由，未公开文档）
DexRefAdapter	Canton DEX 参考实现	现货订单簿 + RFQ	读取 + 兑换，其托管的测试网

CantexAdapter 封装了官方的 cantex_sdk 异步客户端，因此认证、 签名和传输都由 SDK 负责，适配器只负责转换其模型 和异常。其他交易场所没有提供 Python SDK（或者像 Temple 一样，只提供 JavaScript SDK），因此直接通过 HTTP 调用。每个集成点都在 SOURCES.md 中标明了对应的源代码或实时响应。

安装

cantex_sdk 未发布到 PyPI，因此将其声明为 Git 依赖项， 并直接从 GitHub 获取：

pip install "cantonvenues @ git+https://github.com/olevasyliev/canton-venues-sdk"
# or, from a checkout:
pip install -e ".[dev]"

环境变量

凭据仅从环境变量读取（绝不硬编码）。变量名 使用 SDK 自身定义的名称：

变量	必填	说明
CANTEX_OPERATOR_KEY	是	操作员 Ed25519 私钥（十六进制）。用于质询-响应认证和账本签名。
CANTEX_TRADING_KEY	兑换时必填	意向交易 secp256k1 私钥（十六进制）。调用 swap() 时必需。
CANTEX_BASE_URL	否	API 基础 URL。默认为 https://api.testnet.cantex.io。
TRADECRAFT_BASE_URL	否	Tradecraft API 基础 URL。默认为主网地址 https://api.tradecraft.fi/v1。读取数据无需凭据。
TEMPLE_API_KEY	读取 Temple 订单簿时必填	从 Temple 应用获取的账户密钥（Settings > API Keys）。读取已结算交易量无需密钥。
EKIDEN_BASE_URL	否	Ekiden 网关。默认为主网地址 https://api.ekiden.fi。

用法

import asyncio
from decimal import Decimal
from cantonvenues import CantexAdapter, Instrument

async def main():
    async with CantexAdapter() as venue:  # reads keys from the environment
        pools = await venue.pools()
        quote = await venue.quote(
            Decimal("1"),
            pools[0].token_a,
            pools[0].token_b,
        )
        print(quote.returned_amount, quote.trade_price)

asyncio.run(main())

来自订单簿交易场所的市场数据，无需密钥：

from cantonvenues import RockyAdapter

async def top_of_book():
    async with RockyAdapter() as rocky:          # RockyAdapter("perp") for perpetuals
        book = await rocky.order_book("CBTC-USDCX", 20)
        print(book.best_bid, book.best_ask, book.mid_price)

实时展示

Canton Venues 基于此工具包运行 （examples/canton_venues）：展示上述所有交易场所中每种代币的价格、Canton 相对于外部市场的溢价、跨资金池和订单簿按交易规模计算的最佳执行价格、跨交易场所价差扫描器、每日价差收敛速度分析、开放的 JSON API，以及供 AI Agent 使用的 MCP 服务。

运行测试

pip install -e ".[dev]"
pytest        # fully offline; the SDK client is mocked at its method boundary
ruff check .

实时冒烟测试

scripts/live_smoke.py 是一项针对真实 Cantex API 的只读检查：进行身份验证（connect()）、列出资金池，并获取一笔小额报价。它绝不会调用 swap() 或 transfer()。

在工具包根目录创建（或填写）.env，并填入真实密钥（名称与上方环境变量表格中的相同）：

CANTEX_OPERATOR_KEY=...
CANTEX_TRADING_KEY=...
CANTEX_BASE_URL=...

然后运行：

python scripts/live_smoke.py

该脚本绝不会打印凭据值，只会显示各步骤的结果；若失败，则会说明是身份验证错误还是请求错误（两种情况的退出代码均为 1）。

状态

已在每个交易场所完成线上验证。测试完全离线运行，使用从各交易场所捕获的真实响应数据结构。

• Temple（主网，2026-10-04）——无需密钥即可查询每个市场的已结算成交量；使用账户密钥可查询行情、订单簿（最多 200 档）和交易。线上数据与 Temple 自己的 JavaScript SDK 中的类型定义不同，适配器遵循线上数据结构；请参阅 SOURCES.md。交易：余额、未结订单和 trading_status（已关联的钱包、授权状态、手续费余额）均已在线验证；下单和撤单根据 SDK 实现，scripts/temple_order_smoke.py（除非指定 --execute，否则为试运行；提交一个价格永远不会成交的只挂单，并立即撤销）将用于完成这部分验证，首先在 Temple 的测试网上进行。

• Rocky（主网，2026-10-03）——通过其公开的 Binance 风格 API 查询现货和永续市场、24 小时行情、深度和交易。行情报告的买价和卖价均为 0，因此最优买卖价取自深度数据。

• OneSwap 和 Pool Party（主网，2026-10-03）——无需密钥即可查询池储备量（以及 Pool Party 的各池成交量），并在本地按恒定乘积模型定价。

• Ekiden 于 2026-10-03 切换为默认使用主网（自 2026-09-08 起已上线）；主网和测试网上的路由返回相同结果。

• Canborsa（主网，2026-10-28）——通过其 Web 应用读取的 socket 获取永续市场、资金费率、30 天成交量，以及价格和执行深度；目前尚无公开文档的 API。

• Cantex（主网，2026-07-17）——已验证质询-响应身份验证、池、报价，以及使用真实资金完成的交换：在 CC-USDC 市场卖出 10 CC，获得 1.2981357151 USDCx。

• Reference DEX（托管测试网，2026-07-29）——通过适配器双向完成交换，余额变化与池储备量完全吻合。支持两种交换路由：文档所述的钱包编写分配路径，以及由部署自行托管交易者所属参与方的路径。scripts/dexref_testnet_report.py 还会端到端测试该交易场所自己的托管路由：由一个参与方提供多档双向报价、包含最佳执行回执的 RFQ 生命周期，以及使用 LP 代币提供流动性。

• Ekiden（Canton 测试网网关，2026-07-27）——涵盖其全部三个永续市场的市场信息、行情、订单簿、近期交易和资金费率历史。交易需要使用 Ed25519 签名的会话，尚未实现。

• Tradecraft（主网，2026-08-11）——已端到端读取并定价 13 种代币的 23 个池。scripts/tradecraft_market_smoke.py 为 45 种方向中的 45 种定价，仅根据池状态即可将交易场所自身的报价复现到约 1e-16 的相对误差；这正是 SOURCES.md 中手续费模型的依据，而非假设：引擎在每一跳均收取池总手续费的一半，因此实际手续费为 0.299775%，而公布的费率为 0.3%。订单通过该交易场所软件包中的 Daml 选项结算，需要验证器节点，因此适配器可以读取和定价，但无法交易。

使用 scripts/live_swap_smoke.py（Cantex，默认试运行）、scripts/dexref_testnet_smoke.py 和 scripts/dexref_testnet_report.py（Reference DEX，除非指定 --execute，否则为只读）、scripts/ekiden_market_smoke.py（Ekiden）和 scripts/tradecraft_market_smoke.py（Tradecraft）运行线上检查——最后两者在设计上仅支持只读。