认证与签名

Invoice、Transfer 和 Query 使用账户级 API Key + Ed25519 请求签名。API Key 用于定位凭证，Ed25519 用于证明请求来自持有私钥的商户系统。

Header	必填	说明
`X-API-ID`	是	账户级 API ID
`X-API-Key`	是	账户级 API Key
`X-Timestamp`	是	Unix 秒级时间戳，默认允许 ±60 秒偏差
`X-Signature`	是	Ed25519 签名的标准 Base64 编码
`X-Idempotency-Key` 或 `Idempotency-Key`	写请求二选一	两者同时发送时必须相等，否则返回 `400 INVALID_REQUEST`

签名 Payload

text

v1
{api_id}
{merchant_account_id}
{METHOD}
{escaped_path}
{canonical_query}
{timestamp}
{idempotency_key}
{sha256(body)}

字段之间使用单个 \n，末尾不额外追加换行。METHOD 使用大写；body hash 使用原始发送字节计算，不要先解析再序列化。

escaped_path 必须与 HTTP 请求实际发送的 path 完全一致。
canonical_query 应按参数名和值进行稳定排序和转义；没有 query 时使用空字符串。
空 body 也要计算 SHA-256，不要省略最后一行。
{idempotency_key} 使用 X-Idempotency-Key 的值；未发送该 Header 时才使用 Idempotency-Key。两者都没有的只读请求使用空字符串。Header 值两端空白会被忽略。
每次重试可刷新 timestamp 和签名，但必须沿用原幂等键与完全相同的业务 payload。