应用接Binance Connect：准入、报价与交付

币安Binance

2026年10月21日

接入 Binance Connect 之前需要先接受一个前提：这个产品在币安开发者体系里已经经历过重命名和文档迁移，你搜到的"Binance Connect"可能指向两套不同的东西。目前面向普通应用（钱包、dApp）的法币入金通道，文档已归入 Binance Pay Onchain 的 Hosted Ramp 部分；而面向机构嵌入买卖能力的，对应的是 Connect Prime（原 Binance Connect Prime）。本文以普通应用接入 Hosted Ramp 路径为主，涉及机构方案时单独说明。

Binance币安
全球交易量最大的加密货币交易所，安全性与流动性行业领先
新手福利：注册立享20%手续费折扣优惠！

立即注册 APP下载

准入的核心不是技术，而是商务对接。币安没有提供一个公开的、自助注册即可调用的 Connect API 入口。官方文档在 Binance Pay Onchain 页面明确写的是：根据与币安确认的集成范围，大多数客户应从单一产品文档区域开始；访问相关问题联系 该邮件地址已受到反垃圾邮件插件保护。要显示它需要在浏览器中启用 JavaScript。。这意味着你在写第一行代码之前，需要先和币安 Connect 团队确认你的应用类型、目标用户地区和商业模式，拿到对应的接入资格和凭证。

准入：你能拿到什么，拿不到什么

拿到对接资格后，技术准入的核心是认证凭证。Connect Prime 的报价和执单 API 使用基于请求头的签名体系，包括 X-Tesla-ClientId、X-Tesla-SignAccessToken、X-Tesla-Timestamp 和 X-Tesla-Signature。Hosted Ramp 路径的认证细节在公开文档中没有像 Prime 那样逐项列出，但逻辑一致：你需要币安分配的 client 身份和签名密钥，才能调用任何实质性接口。

另一个容易被忽略的准入门槛是用户资格。Binance Connect 只对来自合格国家/地区的用户开放，币安官网有一份动态更新的合格国家列表，且明确注明列表可能随时变化。你的应用如果面向全球用户，需要在调用 Connect 之前自行处理地域判断，而不是假设所有用户都能走通。合格地区的用户还需要拥有已完成 KYC 的币安账户才能使用完整功能。如果你的用户群体中大量是未注册币安的新用户，Hosted Ramp 流程会引导他们完成注册和 KYC，但这部分转化损耗需要纳入产品预期。

报价：你拿到的不是一个"价格"，而是一个有有效期的合约

Get Quote 接口返回的字段里，最需要关注的是 expiredAt（毫秒时间戳）和 quoteId。报价是有有效期的，过期后 quoteId 作废，你需要重新请求报价。这意味着你的前端不能把用户看到的报价当成一个可以无限期展示的静态数字。如果用户在确认页停留过久，提交时拿一个过期的 quoteId 去执行，会失败。

customSpread 是接入方需要理解的一个参数。它由你（商户侧）设定，例如 0.01 代表 1% 的价差，这部分价差产生的收入以法币计价，体现在返回的 spreadAmount 字段中。换句话说，你的应用可以在币安的基础报价之上叠加自己的利润空间。这个参数是必填的，不能省略。如果你不想加价，传 0，但需要确认币安是否允许零价差——文档没有明确禁止，但实际是否接受取决于你与 Connect 团队的约定。

Hosted Ramp 路径的报价接口是另一个端点（/papi/v1/ramp/connect/buy/estimated-quote），参数和响应结构略有不同，包含 feeAmount 和 networkFee 的拆分。networkFee 是链上提币费用，从最终到账金额中扣除；feeAmount 是法币支付通道的费用。两者分开列出，方便你向用户解释"为什么到账金额比预期少"。

交付：链上到账不等于交易完成

一个典型的 Hosted Ramp 买入流程是：前端获取报价 → 创建 PreOrder → 将用户重定向到币安页面完成支付 → 通过 webhook 接收状态更新 → 查询订单确认最终结果。这里的交付不是"币安说订单完成了"就结束，而是加密货币实际到达用户指定的钱包地址。

Webhook 回调里包含 withdrawTxHash、withdrawWalletAddress、withdrawNetwork 等字段。这些字段是你做交付核验的依据。订单状态变为完成，但 withdrawTxHash 为空或对应的链上交易尚未确认，说明提币还在处理中。用户钱包里看到余额，才是交付的终点。

对于 Prime 路径，Execute Quote 返回的 status 可能是 PROCESSING、FILLED 或 FAILED。FILLED 表示币安侧处理完成，但同样需要区分"币安已买入"和"用户已收到"——如果涉及提币到外部地址，链上确认是独立的一步。

退款是交付环节中容易被低估的部分。Prime 文档明确要求商户侧提供一个幂等的退款端点：币安会以 clientOrderId 作为唯一标识调用你的退款接口，同一 clientOrderId 多次调用不应产生重复退款。这个设计的原因是买入流程中法币资金在币安执行报价之前就已经转出，如果币安无法处理报价，需要把法币退回用户。你的应用如果没有实现这个端点，或者没有保证幂等性，在报价失败或部分失败时会出现资金卡住或重复退款的问题。

如果你的用户是机构而非个人

Connect Prime 面向的是银行、金融科技公司、券商和大型平台，希望在自己的金融产品里嵌入买卖能力。它的报价接口需要传入 userId（币安子账户 ID），这意味着机构接入方需要在币安侧有对应的子账户结构。普通钱包或 dApp 不需要走这条路径，Hosted Ramp 的跳转式流程更合适——牺牲的是用户体验的连贯性（用户离开你的应用去币安页面完成支付），换来的是接入成本低、不需要处理法币资金流。

完成的标准

接入完成的标志不是接口返回 200，而是：一笔真实的买入流程中，用户在你的应用发起 → 跳转币安完成支付 → webhook 收到订单完成通知 → withdrawTxHash 对应的链上交易确认 → 用户钱包余额增加。四个环节缺任何一个，交付都没有闭环。对于卖出流程，还需要验证法币是否实际到达用户指定的银行账户或支付渠道，而不是仅仅看到订单状态变更。

如果在测试中发现报价频繁过期或 webhook 延迟，优先检查你的 PreOrder 创建到用户完成支付之间的时间窗口是否过长，以及 webhook 回调地址是否可达且验签正确。Connect 团队在开通权限时会提供沙箱环境和测试凭证，正式上线前用沙箱跑通完整流程是必要的步骤。