HashNut 为企业提供安全、高效的数字资产支付基础设施。企业仅需接入 HashNut API，即可在网站及 App 中接受数字资产支付。
资金直接进入商户自托管钱包，商户拥有资金 100% 控制权，资金安全级别高于传统银行及数字银行。
隐私保护能力远高于传统支付体系及其他数字资产支付方案。
HashNut 支付引擎是一套完整的分布式 Web3 支付基础设施，帮助企业在网站及移动 App 中无缝接受数字资产支付。
只有交易上链，本质仍是 Web 2.5。
全球首个、目前唯一真正面向企业的 Web3 解决方案。
支付由可信智能合约代码执行。
Claim 与 Withdraw 均由商户主动发起，结算控制权始终掌握在企业手中。
HashNut 无法访问或管理商户资金，这是实现 100% 资金安全的架构基础。
可对商户及支付用户提供全面隐私保护，保护能力远高于传统支付体系及其他数字资产支付方案。
查看完整行业覆盖及支付场景。
查看应用场景
用户只需点击支付，即可完成交易
可通过扫描二维码，或向专属收款地址转账。
全球唯一在 DeFi 支付中同时整合批发商、代理及合作伙伴功能的解决方案。
企业最快 5 分钟即可自主完成设置，效率业内领先。
全球首个、目前唯一完整的企业级 DeFi 解决方案，实现 100% 资金安全与即时结算。
兼容主流钱包、公链及代币类型。
一键式支付体验，可媲美微信支付，显著优于其他数字资产支付方案。
支持几乎所有主流钱包、公链、数字资产及央行数字货币（CBDC）生态。
支付流程可与商户后台系统无缝对接，同步订单、发票、物流及财务数据，形成完整连贯的业务流程。
同步订单、发票、物流及财务数据。
资金直接进入商户自托管钱包，商户拥有资产 100% 控制权。
客户从自己的钱包发送订单指定的数字资产。
HashNut 检测链上转账，并返回已确认的支付状态。
零账期。
选择一种支付场景，查看客户结账、链上验证及支付确认后的商户业务流程。
HashNut 支付引擎可作为金融行为的核心入口，进一步拓展业务边界及商业空间。
客户向订单指定的收款地址付款。
支付由智能合约管理，并进入由商户控制的地址。
商户发起 Claim，将已确认的收款地址余额归集至分账合约。
商户发起提现，将资金转至指定地址。
数字资产支付正在快速增长。
年度最具创新区块链项目，总冠军。
总决赛入围奖。
金融科技应用方案金奖，由香港特区政府及香港银行学会相关机构评选。
年度初创企业大奖；商业解决方案优异奖。
杰出企业支付解决方案奖。
与香港城市大学数据科学学院开展联合实习合作。
技术团队成员包括来自微信支付、Monero 及 Visa 的前首席架构师、技术负责人和资深开发人员。
商务团队成员包括 VISA Direct 前全球负责人、Cisco 前总经理，以及联想联合创始人。
NutPersonal 将支付、资产转移与钱包管理整合到同一个个人体验中，同时兼容现有钱包及数字资产。
用户可自由选择法币或数字资产支付，支持 Visa、Mastercard、Google Pay、Apple Pay 等方式。
通过 HashNut 兑换及跨链基础设施，可使用不同链上的不同代币完成支付。
无需输入复杂的区块链地址，直接向昵称付款，让日常数字资产转账更简单。
根据钱包活动生成资金流报告，更清晰地了解个人数字资产流动。
将个人钱包导入并整合至 NutPersonal，在一个入口统一管理资产与付款。
NutPersonal 可整合多个钱包，用于统一资产管理及支付。
可将钱包分组，并在付款时组合使用不同钱包中的资产。
NutPersonal 同时支持代理体系、品牌定制钱包体验，并可与 HashNut 支付引擎连接。
可直接通过 NutPersonal 建立多级代理体系，并在一个界面统一管理。
可按企业品牌主题、Logo 及所需功能定制 NutPersonal 钱包。
NutPersonal 可与 HashNut 支付引擎协同，用于支付及财务数据管理。
HashNut 企业及个人钱包产品均可为合作伙伴提供白标方案。
前往 App Store 或 Google Play 下载 HashNut App。
NutCard 可在任何国家使用，并支持您选择的任何加密资产。
NutCard 为持卡用户提供更简洁的 KYC 开通流程。
NutCard 支持区域代理合作模式，协助合作伙伴拓展当地业务。
专属管理后台，帮助合作伙伴高效管理业务运营及收益。
针对运营及商务需求，为合作伙伴提供一对一支持。
通过合作伙伴激励及奖励机制，支持区域业务持续拓展。
为在当地市场发展 NutCard 的合作伙伴提供区域网络支持。
进入当前 NutCard 申请流程。
完成商户账户设置，验证完整资金路径，接入支付 API，并为 HashNut 正式上线做好准备。
HashNut 是面向企业的数字资产支付基础设施。客户在链上向订单指定的收款地址付款，HashNut 检测支付状态并同步至商户业务流程，结算控制权始终由商户掌握。
HashNut V4 采用 EOA 架构，并使用 2-of-2 MPC 收款地址。实施当前系统时，请确保 V4 账户、SDK 与 API 资料使用同一版本体系。
V4 商户工具、SDK 与 API 行为应配套使用，不要在 V4 集成中混用 V3 接口示例。
go get github.com/nuttybounty/hashnut-sdk-go/v4HashNut 账户设置、支付处理、结算及 API 集成中使用的核心术语。
同一条链上的一个商户钱包对应一个独立 HashNut 商户账户。每条链均拥有独立的分账合约、API 凭证及收款地址池。
分账合约是 Claim 与 Withdraw 结算流程的核心智能合约。客户付款先进入收款地址，再由商户发起 Claim，将已确认余额归集到分账合约。
由 MPC 控制、临时分配给支付订单的地址。客户将订单要求的数字资产发送到该订单显示的收款地址。
由商户运行的桌面客户端，用于处理设置及结算所需的钱包与 MPC 操作，包括部署、创建收款地址、代币授权、Claim、Withdraw 与 Sweep。商户私钥及客户端密码始终保留在商户本地电脑。
| 名称 | 用途 |
|---|---|
accessKeyId | 商户级服务器请求使用的公开 API Key 标识。 |
secretKey | 私有 HMAC 签名密钥。必须保存在服务器端，绝不能暴露在前端代码中。 |
accessSign | 创建订单时返回、与该订单绑定的凭证，用于文档所列的订单级操作。 |
整数状态值，从 INIT(0) 依次经过已支付 / 已确认状态，直至 FINISH(4)；失败、过期和取消使用负数终态。 SUCCESS(3) 是首个可安全履约的状态。
Claim 将收款地址中已确认的余额归集到分账合约。 Withdraw 将商户可提现份额释放到预设的提现地址。 Sweep 将 MPC 控制的收款地址中剩余的原生 Gas 代币归集回商户钱包。
请将资金位置与订单状态分开理解。支付成功并不代表商户已经将资金提现。
客户将订单要求的数字资产发送到该订单指定的收款地址。
资金进入订单指定、由 MPC 控制的收款地址。HashNut 会自动检测付款，结算操作则独立进行。
商户发起 Claim，将已确认的收款地址余额归集到分账合约。
商户发起 Withdraw，将分账合约中的可提现份额转至预设提现地址。
PAID 或 SUCCESS 反映的是订单支付状态；Claim 与 Withdraw 反映的是资金在结算路径中的位置。两者是有意分离的不同流程。
了解订单如何从创建逐步进入可安全履约的状态，以及通知在这一过程中扮演的角色。
文档中会触发 Webhook 的状态包括 PAID, SUCCESS, FAILED，以及 EXPIRED。不要假设每次状态变化都会触发 Webhook。先验证通知，再通过 Query Order 获取权威的当前状态。
当 Query Order 返回的权威状态为 SUCCESS(3) 或更后的已支付终态，例如 FINISH(4)。履约操作必须具备幂等性，避免重复通知造成重复交付。
先准备好商户侧工具，并明确哪些配置可以后续再补。建议从小规模开始，完整验证流程后再扩展到生产环境。
| 项目 | 用途 |
|---|---|
| HashNut MPC Client | 部署并管理结算基础设施、收款地址、Claim、Withdraw 及相关私钥操作。 |
| HashNut Dashboard | 创建和管理订单、维护 API Key，并管理商户配置。 |
| 项目 | 用途 |
|---|---|
| Windows 或 macOS 电脑 | 用于运行 HashNut MPC Client。 |
| 商户钱包 | 支付 Gas，并作为一条链上一个独立商户账户的钱包。 |
| MetaMask or TronLink | 支持的 EVM 链使用 MetaMask；TRON 商户后台登录使用 TronLink。 |
| 网络原生代币 | 准备足够的链上原生代币，用于支付后续操作所需 Gas。 |
| 提现地址 | Withdraw 后商户份额最终到达的地址。 |
| 应用 URL | notifyUrl 用于服务器通知， callbackUrl 用于浏览器返回。这两个地址后续均可更新。 |
| notifyUrl | callbackUrl | |
|---|---|---|
| 方向 | HashNut → 商户服务器 | 客户浏览器 → 商户前端 |
| 是否需要公网访问？ | 是 | 不需要。本地开发时可使用 localhost。 |
| 用途 | 支付状态通知 | 用户体验 / 浏览器返回 |
| 能否作为付款凭证？ | 先验证通知，再 Query Order | 否 |
notifyUrl 用于服务器到服务器通信，callbackUrl 用于浏览器跳转，两者方向相反。
创建首个账户，并生成 5 个收款地址。
创建小额订单并完成支付、Claim 与 Withdraw。
使用 Demo Shop 及 API 集成流程进行验证。
验证完成后再扩充收款地址池。
配置生产环境 URL、IP 限制、监控及运营责任。
在本地初始化商户钱包，并为一条链上的一个商户账户创建核心支付基础设施。
在 Windows 或 macOS 上运行客户端。商户侧私钥操作均在客户端本地完成，商户钱包私钥和 MPC Client 密码必须保留在商户电脑中。
根据电脑选择当前 V4 MPC Client 的 Windows、macOS Intel 或 macOS Apple Silicon 版本。操作账户时，请将客户端与本地 keys.db 工作区保存在一起。
导入钱包后会创建本地 MPC 工作区，其中包括 keys.db。请在完成设置前做好备份。
一条链 + 一个商户钱包 = 一个独立 HashNut 账户。
Withdraw 后，商户份额将发送到这个地址。
先使用小规模收款地址池完成验证，再扩充容量。
notifyUrl 与 callbackUrl 后续可以更新，因此测试阶段可先使用临时开发地址。
设置流程会创建分账合约、MPC 基础设施、收款地址及 API 凭证。
| 保存 | 原因 |
|---|---|
keys.db | 客户端使用的本地 MPC 密钥材料，请安全备份。 |
| 商户钱包私钥 | 需要独立于 keys.db 保存，请单独备份。 |
| 账户信息导出文件 | 用于记录已创建账户及基础设施的运营信息。 |
accessKeyId | 商户级 API 请求使用的公开标识。 |
secretKey | 服务器端 HMAC 签名密钥，生成后请立即安全保存。 |
开发者需要的是 API 凭证及账户标识。涉及商户钱包私钥的操作应始终由账户负责人通过商户侧 MPC Client 完成。
正式上线前，请端到端验证账户、支付检测、结算路径及 API Key 均可正常工作。
确认已部署的账户结构及结算配置。
通过 Dashboard 或 Demo Shop 完成一笔小额真实付款。
将已支付收款地址中的余额归集到分账合约。
将商户份额转至预设提现地址。
使用 Demo Shop 与服务器集成，验证订单创建、查询及通知流程。
支付检测、Claim 与 Withdraw 是不同阶段。进行小额真实验证时，请按此顺序逐步检查。
在账户承载真实业务量之前，先确认一键设置创建的基础设施配置无误。
对照设置时保存的 Account Info，核对分账合约、网络、提现地址、收款地址池及 API Key 记录。
首次验证时，请确认预期的小规模收款地址池已经创建，并归属于正确的商户账户和链。
商户发起 Withdraw 后，资金会进入预设的提现地址。之后更换用于操作账户的钱包，并不会自动改变这个提现目的地。
提现地址属于生产级关键配置。首次端到端测试前要确认一次，正式上线前再确认一次。
创建一笔小额支付订单，完成客户付款，并确认 HashNut 能正确检测到这笔支付。
测试金额保持小额即可。这里要验证的是完整路径，而不是交易金额。
打开支付信息，将指定资产发送到订单分配的收款地址，然后等待 HashNut 检测并确认交易，直至订单状态正常推进。
0xA4...19C通过 Dashboard 和 Query Order 确认权威订单状态。不要把浏览器跳转结果当作付款凭证。
将已获授权的收款地址余额归集到分账合约。Claim 由商户主动发起。
确认已付款的收款地址中有预期的代币余额，并已完成归集所需的代币授权。
Claim 不会把商户份额直接发送到最终提现地址，而是先将已授权余额从收款地址归集到分账合约。下一步才是 Withdraw。
将分账合约中商户可提现的份额释放到预设提现地址。
发起交易前，请再次核对预设提现地址。
确认目标钱包收到预期的商户份额。到这里，从客户付款到商户结算的核心资金路径就已经完整验证。
使用 API 凭证和 Demo Shop，确认订单创建、订单查询及通知处理已经正确连通。
Demo Shop 是商户设置与应用集成之间的验证工具。用它确认 API Key 能够跑通完整支付流程。
将 accessKeyId 和 secretKey 保存在服务器端配置中。 secretKey 绝不能暴露在前端代码中。
Create Order 调用成功并不代表集成已经完成。还要确认 Query Order 正常、通知签名得到验证、应用会向 HashNut 查询权威状态，并且履约操作具备幂等性。
只有在首个账户和集成流程都完成验证后，再提高并发支付能力。
每个收款地址会临时分配给一个未结束的支付订单，因此收款地址池的容量决定了该商户账户可以同时保持多少个未结束订单。
当前公开指引建议先用 5 个收款地址完成验证，确认流程无误后再扩容。生产环境可根据支付频率，将地址池扩展到 50、100、200 等便于管理的规模。
通过 MPC Client，在同一个分账合约和商户账户下创建更多收款地址。同时确保所选链上有足够的原生代币，用于地址管理操作所需的 Gas。
从已验证的测试流程进入生产配置、监控、容量规划及运营责任管理。
正式上线后，日常工作会从“设置”转向“监控”：未结束订单、支付异常、Claim、Withdraw、收款地址容量、原生代币 Gas 及异常升级处理。
集成阶段让本地通知处理接口可从公网访问，同时明确区分服务器通知与浏览器返回。
notifyUrl 是服务器到服务器的接口。当订单进入文档规定的可通知状态时，HashNut 必须能够通过公网访问该地址。
确认该路由正在监听，并以安全方式记录收到的请求。
使用你习惯的开发隧道或反向代理服务，生成一个临时的公网 HTTPS 地址。
例如：隧道域名加上你的通知路径。
完成付款，并确认服务器收到预期通知。
验证通知后，再通过 Query Order 获取权威的当前状态。
进入生产环境时，将临时隧道替换为稳定的生产 HTTPS 接口。保持 notifyUrl 并与以下内容区分 callbackUrl：notify 的方向是 HashNut → 服务器，callback 的方向是客户浏览器 → 前端。
浏览器返回只是客户体验的一部分，不能作为付款凭证。
先完整跑通一次支付，再把同样的客户流程和服务器流程集成进自己的产品。
通过 Demo Shop 体验客户支付流程，同时验证商户账户及 API 行为。
打开 demo.hashnut.io ↗通过一笔 58 美元的简单购买流程，了解哪些环节属于客户体验，哪些环节由 HashNut 支付系统处理。
客户照常使用你的产品体验，只有进入支付环节时才需要出现 HashNut。
使用当前正在验证的商户账户 / API Key。
确认金额、资产、网络及收款地址均正确。
从客户钱包发送指定资产。
观察支付检测及确认过程。不要根据 callbackUrl 执行履约。
确认商户服务器可以查询 HashNut 订单，并正确识别 SUCCESS / FINISH。
如果要完成完整账户验证，再从商户侧执行 Claim 和 Withdraw。
客户支付体验可以使用商户自己的品牌并嵌入产品，但服务器仍负责创建订单、验证通知、查询权威状态，以及确保只履约一次。
完成账户及资金路径验证后，再将商户服务器接入 HashNut。
商户服务器负责业务订单及 HashNut API 调用。客户资金则直接从客户钱包进入链上指定收款地址。
此时商户账户及资金路径应已完成验证。开发者接收的是服务器配置，而不是商户钱包私钥或 MPC 密钥。
BSC0x91...2AFaccessKeyId
secretKey
notifyUrl
callbackUrl
使用设置阶段生成的账户标识与 API 凭证，不要接收商户钱包私钥。
将 accessKeyId 与 secretKey 保存在服务器端密钥存储中。
使用 secretKey 对 UUID + timestamp + 请求体执行 HMAC-SHA256 计算，并将结果进行 Base64 编码。
将商户订单与返回的 payOrderId 与 accessSign.
向客户展示金额、资产、网络及指定收款地址。
先验证通知，再通过 Query Order 获取权威的当前订单状态。
仅在确认状态为 SUCCESS / FINISH 后履约，并确保操作具备幂等性。
go get github.com/nuttybounty/hashnut-sdk-go/v4callbackUrl 只是浏览器返回机制，不能作为付款凭证。支付结果应以已验证的服务器通知和权威 Query Order 结果为准。
将测试与生产环境严格分开，并确保凭证、账户上下文及 URL 与当前环境一致。
在进入生产环境并承载真实业务量之前，先在 Sandbox / 测试环境验证订单创建、支付状态处理及完整资金路径。
用于集成开发、小额验证订单及端到端测试。
仅在商户账户、回调、收款地址容量及运营流程均完成验证后使用。
使用当前 V4 账户或 SDK 版本提供的 Base URL 及环境参数。V3 接口地址不能用于 V4 集成。
API 请求成功还不够。进入生产环境前，要完整验证 Create Order → 客户付款 → 通知 → Query Order → Claim → Withdraw，并确认收款地址容量和 Gas 的责任归属。
商户级 API 请求必须在服务器端签名，并确保 secretKey 不进入前端代码或客户端包。
| 凭证 | 用途 |
|---|---|
accessKeyId | 商户级请求使用的公开标识。 |
secretKey | 商户服务器本地使用的 HMAC 密钥。绝不要发送 secretKey 本身。 |
accessSign | 创建订单时返回、与订单绑定的凭证，用于文档规定的订单级操作。 |
sign = Base64(
HMAC-SHA256(secretKey, uuid + timestamp + requestBody)
)const crypto = require('node:crypto');
function signRequest(secretKey, uuid, timestamp, requestBody) {
const input = uuid + timestamp + requestBody;
return crypto
.createHmac('sha256', secretKey)
.update(input)
.digest('base64');
}本示例按照文档中的签名公式实现。请求 Header 名称及接口结构应始终与当前 V4 API 参考保持一致。
bindIp 用于限制哪些服务器 IP 可以使用该 API Key。 * 表示不限制 IP。集成阶段可以临时使用，但生产环境应尽可能限制为实际服务器 IP。
创建与自身业务订单对应的 HashNut 支付订单，并将返回的标识与业务记录一并持久化。
merchantOrderId = A1042payOrderId + accessSign| 字段 | 说明 |
|---|---|
merchantOrderId | 你的订单标识。在对应的商户 / 链 / channel 范围内必须保持唯一。 |
merchantChannel | 同一商户上下文中的分组。文档规定的默认值为： default. |
expireDuration | 订单有效期，单位为秒。文档默认值： 172800 （48 小时）；最大值： 259200 （72 小时）。 |
payOrderId | HashNut 创建订单后返回的全局唯一支付订单标识。 |
accessSign | 创建支付订单时返回、与订单绑定的凭证。 |
商城 payOrderId 与 accessSign 应在创建后立即与商户订单建立映射。订单级操作以及通知延迟或重复时的恢复流程都会用到这些信息。
始终将 Query Order 作为 HashNut 支付订单当前状态的权威查询。
文档规定的订单级操作使用 payOrderId + accessSign ，无需为每次查询重新计算商户 HMAC。
最重要的状态是 SUCCESS(3)。后续查询也可能返回 FINISH(4)，这仍属于已支付状态。当权威查询达到安全的已支付状态后，只履约一次。
将 Confirm Payment 纳入服务器端订单生命周期，并在履约前确认当前订单状态。
Confirm Payment 是 V4 API 中的订单级操作，应将它视为支付订单生命周期的一部分，而不是客户履约的事实来源。
Create Order 会返回一个 accessSign 与订单绑定。文档规定的订单级操作使用返回的订单标识及订单凭证，而不是暴露商户 secretKey 。
执行任何确认相关操作后，Query Order 仍然是当前状态的权威查询。只有当查询到的订单进入 SUCCESS (3) 或 FINISH (4).
如果你的 V4 集成需要 Confirm Payment，请只在商户服务器端执行。不要把浏览器返回 URL、按钮点击，甚至交易哈希的存在本身当作履约凭证。
使用当前 V4 API 规范提供的接口路径和请求字段，不要把旧版 HashNut API 混入 V4 实现。
只有在订单当前状态允许时才能取消未付款订单，并将最终状态记录到业务系统。
文档规定的订单生命周期允许订单从 INIT (0) 到 CANCELED (-3) ，当商户取消订单时进入该状态。 CANCELED 为终态。
请将你的 merchantOrderId、HashNut payOrderId 和返回的订单凭证一起保存。
不要因为结账页面还开着，就假设客户尚未付款。
文档规定的状态转换是 INIT → CANCELED。
在业务流程中将 CANCELED 视为终态。
如果客户仍需付款，应创建新的支付订单，不要尝试恢复已经进入 CANCELED 终态的旧订单。
使用当前 V4 API 规范提供的接口路径、请求字段及认证方式。
在结账、通知处理、履约、对账及运营环节中，统一解释支付订单状态。
| 值 | 名称 | 说明 |
|---|---|---|
0 | INIT | 订单已创建，等待客户付款。 |
1 | 已支付 | 已检测到链上支付交易，正在等待确认。 |
2 | CONFIRMING | 交易正在等待达到所需区块确认数。 |
3 | SUCCESS | 付款已确认，是首个可安全履约的状态。 |
4 | FINISH | 支付后处理已经完成，仍属于已支付状态。 |
-1 | FAILED | 付款验证失败。 |
-2 | EXPIRED | 付款完成前订单已过期。 |
-3 | CANCELED | 订单已由商户取消。 |
少付会为剩余金额创建补款记录。客户可以多次补款，直至累计支付金额覆盖订单总额。
通过服务器到服务器的方式接收支付状态变化，完成验证后，再查询权威订单状态并决定是否履约。
| notifyUrl | callbackUrl | |
|---|---|---|
| 方向 | HashNut → 商户服务器 | 客户浏览器 → 商户前端 |
| 可访问性 | HashNut 必须能够访问 | 本地开发时可使用 localhost |
| 用途 | 支付状态信号 | 将客户返回商户体验 |
| 付款凭证 | 先验证通知，再 Query Order | 绝不能作为付款凭证 |
在 notifyUrl 接收服务器到服务器的通知。
按照文档中的签名算法验证 HashNut 签名。
通过 HashNut / 商户订单标识定位对应业务订单。
调用 Query Order 获取权威的当前状态。
仅在确认进入安全的已支付状态后履约，并确保操作具备幂等性。
按照当前 V4 通知规范返回预期响应。
当前本地参考资料中记录的可通知状态包括 PAID, SUCCESS, FAILED，以及 EXPIRED。不要假设每一次状态变化都会产生通知。
集成设计必须能够处理通知延迟、重复事件、部分付款、订单过期及临时 API 故障，避免重复履约或订单丢失。
| 情况 | 响应 |
|---|---|
| 重复通知 | 通知处理及履约都必须具备幂等性。 |
| 通知缺失 / 延迟 | 通过以下信息 Query Order payOrderId + accessSign. |
| 浏览器先于通知返回 | 不要信任 callbackUrl，应查询服务器端订单状态。 |
| 少付 | 按照已配置策略处理补款记录 / 剩余金额。 |
| 订单过期 | 创建新订单，不要尝试恢复已过期订单。 |
| 临时 API 故障 | 采用有上限的退避重试，并保持商户订单为待处理状态，不要乐观履约。 |
记录 merchantOrderId、payOrderId、订单状态、通知接收时间、Query Order 结果及履约结果。不要记录 secretKey 或商户私钥。
正式流量进入商户账户前，将应用流程与资金路径一起完整验证。
商户服务器创建 HashNut 支付订单，并保存返回的标识。
客户看到应付金额、资产、网络及收款地址。
客户完成链上交易。
商户服务器验证通知消息。
服务器确认状态为 SUCCESS / FINISH。
商户应用只交付一次商品或服务。
确认预期的已支付余额。
将已授权余额归集到分账合约。
将商户份额转至预设提现地址。
确认商户订单、链上付款、HashNut 订单状态及结算记录相互一致。
只有应用流程和资金路径都完成端到端验证后才能上线，同时应验证通知延迟或重复等情况下的恢复行为。
上线后持续监控订单状态、结算、容量、原生代币 Gas 及异常，确保支付流程保持健康。
运营人员无需查看应用代码，只需持续回答四个关键问题，就能判断线上支付是否运行正常。
支付目前处于什么状态？
INIT · PAID · CONFIRMING · SUCCESS · FINISH哪些资金可以归集？
收款地址余额 · Claim · Withdraw是否还有空闲收款地址？
未结束订单 · 可用地址 · Gas哪些问题需要人工处理？
状态不一致 · Gas · 容量 · 对账| 领域 | 主要负责人 |
|---|---|
| 客户 / 订单状态问题 | 运营 + 开发者 |
| Claim / Withdraw | 账户负责人 / 已授权运营人员 |
| 收款地址容量 | 运营 |
| 原生代币 Gas | 运营 / 账户负责人 |
| API 认证 / 通知失败 | 开发者 |
| keys.db / 商户钱包备份 | 账户负责人 |
按状态监控未结束订单和近期已付款订单，排查异常记录。当商户系统与 HashNut 状态看起来不同步时，使用 Query Order 核实。
| 状态 | 运营含义 |
|---|---|
| INIT | 订单仍处于打开状态，等待客户付款。 |
| PAID / CONFIRMING | 已检测到付款，但尚未进入首个可安全履约状态。 |
| SUCCESS | 付款已确认。通过权威查询验证后，应用可以履约一次。 |
| FINISH | 后续已支付状态 / 支付后处理完成。 |
| FAILED / EXPIRED / CANCELED | 终态异常，需要商户侧处理，而不是执行履约。 |
将 merchantOrderId, payOrderId、当前状态、已支付金额、时间戳及履约状态都应能在商户系统中查询。
将 Claim 和 Withdraw 作为受控的商户侧操作，并逐笔核对资金变化是否符合收款地址及分账合约的预期余额。
将已授权的代币余额从收款地址归集到分账合约，由商户主动发起。
将分账合约中商户可提现份额释放到预设提现地址。平台份额单独处理。
在当前客户端流程支持的情况下，将 MPC 控制收款地址中剩余的原生 Gas 代币回收到商户钱包。
小团队中同一个人可以承担多项职责，但生产流程仍应明确记录谁有权发起结算操作，以及这些操作如何复核。
为未结束订单保留充足的收款地址容量，同时为商户侧链上操作准备足够的原生代币 Gas。
收款地址可以跨订单复用，但已经分配给活动订单的地址不能同时用于另一笔活动订单。应提前监控剩余容量，避免需求耗尽地址池。
当前公开指引建议首次验证使用 5 个地址，进入生产后按实际并发需求扩展到 50、100、200 等便于管理的规模。容量应依据同时未结束的订单量，而不是历史累计交易量。
| 链类型 | 商户侧 Gas |
|---|---|
| Ethereum / EVM | 相关部署及商户侧链上操作所需的网络原生代币。 |
| BSC | BNB |
| Polygon | POL / 当前网络原生代币 |
| TRON | TRX |
不要等到运营操作因 Gas 不足失败后才充值。应把原生代币余额纳入日常运营检查。
尽早发现问题，区分支付状态问题与结算问题，并带上足够上下文，将异常交给正确负责人处理。
| 现象 | 可能负责人 / 首要检查项 |
|---|---|
| 客户表示已付款，但订单仍停留在 INIT | 先检查链上交易、网络 / 资产及收款地址，再由开发者 / HashNut 排查支付检测。 |
| 订单长时间停留在 PAID / CONFIRMING | 检查链上确认数及网络状态。 |
| 通知缺失 | 开发者直接查询订单，并检查 notifyUrl 是否可访问及相关日志。 |
| Claim 无法归集代币 | 检查代币授权及收款地址余额。 |
| Withdraw 目标地址异常 | 停止操作，核对预设提现地址后再重试。 |
| 收款地址池容量不足 | 在未结束订单耗尽地址池前，由运营人员提前扩容。 |
| MPC Client 无法创建新地址 | 检查本地客户端、keys.db、商户钱包、网络及 Gas。 |
排查时请提供商户账户 / 链、merchantOrderId、payOrderId、当前订单状态、适用时的交易哈希、时间戳、尝试执行的操作及完整报错。绝不要发送 secretKey 或私钥。
如果后端使用 Go，请采用 V4 Go SDK。
go get github.com/nuttybounty/hashnut-sdk-go/v4SDK 可以减少请求构建工作，但凭证安全、商户订单映射、通知验证、权威订单查询、幂等履约及运营日志仍由商户服务器负责。
V4 package 路径必须与 V4 API 行为配套使用，不要把 V3 接口示例混入集成。
Java 后端请使用 V4 Java SDK，同时确保 API 凭证和付款验证始终留在服务器端。
使用当前 V4 Java SDK 版本提供的 package 坐标及代码示例。
了解一条链上一个商户钱包所创建的各个组成部分，以及它们与支付、结算及 API 访问之间的关系。
每条链都有独立的商户账户、分账合约、API Key 和收款地址池。不要认为一条链上的设置会自动创建或控制另一条链。
备份维持商户账户运营所需的商户侧资产，并将服务器凭证与钱包密钥分开保存。
本地 MPC 材料与账户信息用途不同。两者都需要保存，但钱包密钥与应用凭证必须分开管理。
keys.db商户侧客户端使用的本地 MPC 密钥材料。
用于理解并集成商户账户的配置及标识信息。
0x91...2AF0x72...891AKID••••91••••••••••••| 资产 | 规则 |
|---|---|
keys.db | 请安全备份。MPC Client 本地工作区后续执行 MPC 控制的地址操作时仍需要它。 |
| 商户钱包私钥 | 与 keys.db 分开备份，不要交给开发者。 |
| 账户信息 | 将导出的账户记录与商户运营文档一并保存。 |
accessKeyId | 保存在服务器配置中。 |
secretKey | 保存在服务器端密钥存储中，并在生成时立即安全记录。 |
账户负责人负责保护商户钱包材料及本地 MPC 资产；开发者负责保护应用 API 密钥。小团队中两项职责可以由同一个人承担，但不同密钥仍应分开存储和处理。
确保商户支付行为和应用路由配置清晰、可修改，并符合生产安全要求。
| 设置 | 说明 |
|---|---|
notifyUrl | 用于接收 HashNut 支付状态通知的公网服务器接口。 |
callbackUrl | 客户完成支付体验后返回浏览器的 URL。本地开发时可以使用 localhost。 |
bindIp | API Key 的服务器 IP 白名单。 * 表示不限制。 |
| 设置 | 文档规定行为 |
|---|---|
merchantChannel | 文档规定的默认 channel 值为 default. |
expireDuration | 默认 172800 秒（48 小时），最长 259200 秒（72 小时）。 |
| 收款地址容量 | 先以小规模完成验证，账户和集成流程跑通后再扩容。 |
正式上线前，请确认生产 URL、IP 限制、提现地址、容量、Gas、通知处理及运营责任均已配置完成。任何配置变更都应留有记录并经过测试，再承载有意义的支付量。
Buy one demo item with 0.01 USDT. After the payment is confirmed, take over the same order as the merchant and complete the settlement.
Connect your website or app through HashNut’s payment infrastructure.
告诉我们您的支付场景、渠道合作机会或战略合作方向。
了解您使用 HashNut 服务时，我们如何收集、使用、共享及管理相关信息。
适用于访问及使用 HashNut 网站、应用、产品与服务的相关条款。
了解 HashNut 如何识别、评估及管理业务中的洗钱及恐怖主义融资风险。