名词解释
HashNut 的文档里会反复出现一批专有名词。这一页把它们集中解释清楚，后面各页不再重复定义。
第一次接入建议先通读一遍，之后当字典查用即可。
角色
商户（merchant）
在 HashNut 接收用户付款的一方，也就是你。
一条链 + 一个钱包地址 = 一个商户。 同一个钱包地址在 ETH 上和在 BSC 上属于两个独立的商户，各自有自己的分账合约、api key 和订单。接入多条链时要按链分别开户。
商户渠道（merchantChannel）
同一个商户下的业务分组，默认值是 default。
如果你有多个网站或 App 共用同一个分账合约，可以用渠道区分订单来源。订单的唯一键是 链 + 商户地址 + 渠道 + 商户订单号，所以不同渠道之间的商户订单号可以重复。
平台（platform）
HashNut 支付网关自身。平台的收益来自提现时按分账比例分走的手续费，不托管商户资金。
代理人（agent）
把 HashNut 推荐给商户的第三方。若商户经代理人开户，代理人会作为一个分账人参与分账， 分走平台手续费中的一部分。不经代理人开户时不存在这个角色。
用户（customer）
在商户的网站或 App 下单、并向收款地址转账的付款人。
合约与地址
分账合约（split wallet / splitter）
商户在链上部署的一个智能合约，是整套体系的核心。它负责两件事：
- 归集 —— 把散落在各个收款地址上的资金集中到自己名下
- 分账 —— 提现时按预设比例把资金分给商户、平台（以及代理人）
部署分账合约相当于传统支付里的"开户"。一条链一个分账合约就够了，收款地址挂在它下面。
Split Wallet Manager（manager）
分账合约的管理员地址，由商户的 MPC Client 和 HashNut 通过 MPC 协议共同生成， 双方各持一半私钥分片。
分账合约激活时，合约的 owner 权限会从商户钱包转交给 manager。此后"注册收款地址"、 "升级逻辑合约"这类管理操作都必须双方共同签名，商户单方或 HashNut 单方都无法执行。 这是 HashNut 无托管模型的技术基础。
收款地址（receipt address）
用户实际付款的目标地址，一个普通的链上地址（EOA）。同样由 MPC 生成，私钥分成两半： 一半在商户本机的 keys.db 里，一半在 HashNut。
一个订单只绑定一个收款地址；订单结束后地址会释放回地址池，被后续订单复用。
收款地址池
已激活、可供订单使用的收款地址集合。创建订单时从池中取一个空闲地址绑定，订单结束（成功、 过期、取消）后释放。
地址数量决定并发下单能力 —— 池里没有空闲地址时无法创建新订单。建议低频大额场景准备 50 个，高频场景 200 个。
提现地址（withdrawAddress）
提现时资金最终到账的地址，在部署分账合约时登记，一键开户界面里填的就是它。
WARNING
提现的到账地址是部署时登记的提现地址，不是发起提现交易的那个钱包地址。这两者可以不同， 换钱包发交易不会改变钱的去向。
分账人（payee）与分账比例（share）
参与分账的地址叫分账人，通常是「商户 + 平台」，经代理人开户时还包括代理人。
分账比例的总和固定为 10000。按默认 0.8% 费率，商户的 share 是 9920，平台合计 80。
授权（approve）
收款地址把某个 token 的转出权限授予分账合约的链上操作。没有授权，分账合约就无法归集该 地址上的这种 token。
授权额度固定为 uint256 最大值（无限授权），原因是归集是长期反复发生的操作，有限额度会很快耗尽。 授权范围是按 (收款地址, token) 计的 —— 同一个地址要收 USDT 又要收 USDC，需要分别授权。
链（chain）与 token
当前支持的链：ETH、BSC、POLYGON、TRON。
token 指链上的 ERC20 / TRC20 代币，默认使用 USDT。用户用 token 支付订单。
订单
订单（order）
一次收款请求。商户创建订单 → HashNut 分配收款地址 → 用户付款 → HashNut 确认并通知商户。
平台订单号（payOrderId）
HashNut 生成的订单号，全局唯一，后续查询、确认、通知都用它。
商户订单号（merchantOrderId）
商户自己生成并在创建订单时传给 HashNut 的订单号。在「链 + 商户地址 + 渠道」范围内不可重复。
订单状态（state）
从 INIT(0) 到 FINISH(4) 的整数状态码。完整取值与流转关系见 订单状态。
对商户最重要的是 SUCCESS(3) —— 到这个状态就可以发货了。
过期时长（expireDuration）
订单从创建到过期的秒数，创建订单时可指定。默认 172800 秒（48 小时），最长 259200 秒（72 小时）。
过期订单不可恢复，收款地址会被释放回池，需要重新创建订单。
补款单（supplement）
用户付款金额不足时，HashNut 为差额自动生成的补款记录。补款单与原订单共享同一个 payOrderId， 可通过查询补款记录接口获取。
多次少付会生成多张补款单，直到累计金额覆盖订单金额。
凭证与回调
api key
商户服务端调用 HashNut 接口的凭证，由一对值组成：
| 名称 | 作用 |
|---|---|
accessKeyId | 公开的身份标识，随请求发送 |
secretKey | 私密的签名密钥，只用于本地计算签名，绝不能出现在请求里，也不能放到前端 |
一键开户时会自动创建一个 api key。api key 上还挂着 notifyUrl、callbackUrl、 长款/短款策略、IP 白名单等一批商户级配置。
签名（sign）
服务端调用接口时的身份证明，算法为 Base64(HMAC-SHA256(secretKey, uuid + timestamp + 请求体))，随请求头发送。 HashNut 发通知时用同样的算法反向签名，供商户验签。详见认证签名。
accessSign
创建订单时返回的一个签名串，与该订单绑定。查询订单、确认支付等订单级操作用它做凭证， 不需要重新算 HMAC。
bindIp（IP 白名单）
允许使用该 api key 的服务器公网 IP。填 * 表示不限制。调试阶段建议先用 *， 上线前再收紧到实际服务器 IP。
notifyUrl（后端通知）
HashNut 主动请求商户的地址。订单状态变化时，HashNut 向这个地址 POST 通知报文。
因为是 HashNut 来找你，所以这个地址必须公网可达。
callbackUrl（前端跳转）
用户在支付页面完成支付后，浏览器跳转回商户站点的地址。
因为只是浏览器跳转，不需要公网可达，本地开发填 localhost 也能用。
DANGER
notifyUrl 和 callbackUrl 方向相反，是接入时最容易搞反的两个参数。 一句话记法：notify 是后端到后端，callback 是浏览器跳转。 对照表见通知。
金额与费用
订单金额相关字段
| 字段 | 含义 |
|---|---|
amount | 订单应付金额 |
paidAmount | 用户实际已付金额（含补款） |
obtainAmount | 扣除平台手续费后商户实际可得的金额 |
platformFee | 平台手续费 |
费率（rate）
平台手续费比例，以万分比表示。默认 80，即 0.8%。
手续费不在下单时收取，而是在提现时按分账比例自动分走。1000 USDT 的收入， 商户提现得到 992 USDT，8 USDT 留在分账合约里归平台。
长款（overpay）
用户支付金额超过订单金额。处理方式由 api key 上的长款策略决定：
| 策略 | 行为 |
|---|---|
AUTO_CONFIRM（默认） | 订单直接进入确认流程，视为支付成功 |
MANUAL | 订单保持原状态，等待人工介入 |
WARNING
多付的部分会随资金一起归集进分账合约并参与分账，HashNut 不会自动退还差额。 如需退款请自行与用户结算。
短款（underpay）
用户支付金额不足订单金额。此时订单停留在 PAID(1)，HashNut 为差额生成补款单。
是否就此通知商户由 api key 上的短款策略决定：
| 策略 | 行为 |
|---|---|
NOTIFY（默认） | 通知商户，商户可提示用户补款 |
SILENT | 不通知，静默等待补款 |
归集（claim）
把资金从各个收款地址转移到分账合约的操作，由商户主动发起，用商户钱包私钥直接签名。
前提是收款地址已经对该 token 完成授权（approve）。
提现（release）
把资金从分账合约转出到提现地址的操作，同样由商户主动发起。分账在这一步发生 —— 商户只能提走属于自己 share 的部分。
手续费（gas）与回收手续费（sweep）
链上交易都要付原生币（ETH / BNB / MATIC / TRX）作为 gas，全部由商户的钱包承担， HashNut 不代付。
收款地址要自己发授权交易，所以事先要往它转一点原生币。这笔钱用完后可以通过 「回收手续费」（sweep）转回商户钱包。
确认数（confirmations）
一笔链上交易被后续区块确认的次数。HashNut 按链配置所需确认数，达到后订单才从 CONFIRMING(2) 进入 SUCCESS(3)。确认数越高越难被回滚，代价是等待时间更长。
工具
HashNut 控制台
浏览器访问的商户后台（defi.hashnut.io），用于创建和管理订单、 维护 api key、配置告警邮箱等。用钱包插件（MetaMask / TronLink）签名登录。
HashNut MPC Client
商户在自己 PC 上运行的桌面客户端，负责所有涉及私钥的操作：部署与激活分账合约、 创建收款地址、授权、归集、提现、回收手续费。
私钥和密码只留在本机，HashNut 不保存。客户端产生的 keys.db 保存了商户钱包与 MPC 密钥分片，丢失后无法再新增收款地址，务必备份。
一键开户
MPC Client 提供的功能，把「部署分账合约 → 激活 → 创建收款地址 → 创建 api key」 四个步骤合成一次操作。详见一键开户。