deepbook-sdk

DeepBook V3 SDK

MCP 工具： 如果你的环境中可以使用 Sui 文档 MCP 服务，也请查询该服务（https://sui.mcp.kapa.ai），以获取最新答案。请将其用于验证，以及查找这些参考文件未涵盖的详细信息。

来源限制： 本技能中的所有信息仅来自 docs.sui.io、deepbook-sandbox 示例 和 deepbookv3 仓库。扩展或更新本技能时，只能使用这些来源。请勿使用第三方博客、教程或非官方文档。

@mysten/deepbook-v3 SDK 提供了一个 TypeScript 客户端，用于与 Sui 上的 DeepBook V3 池交互。本技能介绍如何设置客户端、管理余额、下单、执行兑换以及处理手续费。常见的 AI 编码错误包括：硬编码链上 ID，而不使用 SDK 的池和币种键；每笔交易都创建新的 BalanceManager，而不复用已有实例；以及使用非数字类型的 clientOrderId 值。

本技能会引导你查阅针对具体任务的参考文件。只加载与当前任务相关的文件。

本技能中的所有模式均源自： https://docs.sui.io/onchain-finance/deepbook/deepbookv3/spot-workflow https://docs.sui.io/onchain-finance/deepbook/deepbookv3-sdk https://github.com/MystenLabs/deepbook-sandbox/tree/main/examples/sandbox

如果不确定某个 API，请先获取相关页面。 请勿猜测，也不要根据其他 SDK 或库进行推断。

---

参考文件

client-setup — 客户端初始化与 BalanceManager 生命周期

路径： client-setup.md 适用场景： 设置 DeepBook 客户端、创建或复用 BalanceManager、为 testnet 或 mainnet 配置 SDK，或了解三层设置模式（只读、基础、高级）。 涵盖内容： SDK 安装、使用 $extend(deepbook({...})) 构造 SuiGrpcClient、密钥对设置、BalanceManager 的创建与复用、存款与取款、sandbox 设置模式。

trading — 订单、兑换与订单生命周期

适用场景： 下限价单或市价单、执行兑换、查询订单簿、检查订单状态、取消订单，或了解订单生命周期。 涵盖内容： 限价单（POST_ONLY、NO_RESTRICTION）、带重试模式的市价单、兑换函数（使用和不使用 BalanceManager）、订单簿查询、未完成订单查询、取消订单、自成交行为，以及从下单到取款的完整订单生命周期。

fees — 手续费结构与 DEEP 质押

适用场景： 用户询问交易手续费、DEEP 代币质押、手续费折扣、如何为 BalanceManager 存入 DEEP，或手续费的计算方式。 涵盖内容： 使用 DEEP 或输入代币支付手续费、通过 DeepPrice 计算手续费、治理手续费参数、质押以获得手续费折扣、获取 testnet DEEP、推荐系统。

---

路由指南

任务	加载
设置 DeepBook 客户端	client-setup
创建或复用 BalanceManager	client-setup
存入或取出资金	client-setup
下限价单	trading
下市价单	trading
执行兑换	trading
查询订单簿	trading
检查或取消订单	trading
了解手续费或质押	fees
为 BalanceManager 存入 DEEP	fees
构建完整的交易机器人	所有参考文件
完整的现货交易工作流	所有参考文件

---

技能内容

核心概念

• 通过 $extend 使用 DeepBook 客户端。 SDK 使用 deepbook 函数（从 @mysten/deepbook-v3 导入），并通过 SuiGrpcClient.$extend(deepbook({...})) 添加 DeepBook 专用的交易构建器。方法采用柯里化模式，分属两个命名空间：交易操作使用 client.deepbook.deepBook.method({ params })(tx)，余额管理使用 client.deepbook.balanceManager.method({ params })(tx)，其中 tx 是一个 Transaction 对象。

• 池和币种键。 SDK 使用字符串键引用池和币种（例如 "DEEP_SUI"、"SUI"），而不是原始链上地址。SDK 会将这些键映射到对应网络的正确地址。

• BalanceManager 生命周期。 BalanceManager 是一个链上共享对象。创建一次后，保存其 ID，并在后续交易中重复使用。每笔交易都创建一个新的对象会浪费 gas，并产生孤立对象。

• 兑换与订单。 兑换直接操作钱包中的 Coin 对象，无需 BalanceManager。下单则需要一个已存入资金的 BalanceManager。

规则

1. 始终使用 SDK 键指定池和币种。 切勿硬编码链上 ID——SDK 会按网络处理地址解析。
2. clientOrderId 必须是数字字符串（编码为 u64）。像 "order-1" 这样的标签会导致失败。
3. 重复使用 BalanceManager。 保存创建时返回的 ID，并在构造客户端时传入。
4. 存款金额不得超过钱包余额。 SDK 会在构建时进行验证——存入超过钱包持有金额的资金，会在提交交易前触发 Insufficient balance 错误。
5. 处理 localnet/sandbox 上做市商的重新平衡时段。 sandbox 做市商的重新平衡周期约为 15 秒，此时流动性会暂时消失。请使用重试辅助工具。

常见错误

• 每次运行都创建新的 BalanceManager。 这会产生孤立的共享对象。请通过索引器查找已有的管理器，或保存其 ID。
• 对吃单使用 POST_ONLY。 POST_ONLY 可确保订单留在订单簿上。如果订单会与现有订单交叉并成交，就会被静默拒绝——不会返回订单，也不会抛出错误。
• 交易前忘记存款。 订单使用 BalanceManager 余额，而不是钱包余额。必须先存入资金。
• 未存入用于支付费用的 DEEP。 对于非白名单池，BalanceManager 中必须有 DEEP 才能支付费用。否则交易会失败。
• 忽略自成交。 未指定 selfMatchingOption 时，SDK 默认使用 SelfMatchingOptions.SELF_MATCHING_ALLOWED，这意味着你的吃单可能会与自己的挂单成交。这通常并非预期行为。请明确设置 SelfMatchingOptions.CANCEL_TAKER 或 SelfMatchingOptions.CANCEL_MAKER，以防止自成交。