更新日志

API 契约（openapi.yaml）的历史演进记录，最新变更排在最前。除特别说明外，所有改动均为向前兼容的增量变更，既有错误码与字段永不重新编号。

2026-09-26 — 充值前即可创建 API 密钥

• POST /v1/api-keys 支持在 unfunded（未充值）状态的账户上直接创建密钥：注册后创建密钥，调用 GET /v1/deposit-addresses 查询专属充值地址，从而实现全自动程序化入账。下单仍需余额充足以防拒单 (4001 insufficient_funds)。
• 废弃 3016 account_unfunded 错误码，任何接口不再返回该错误。编号保持保留。

2026-09-25 — 地址资源查询接口完全公开

• GET /v1/resources/{address} 不再需要凭证。匿名请求基于单 IP 预算运行，返回 our_active_orders: []；签名请求完整验证身份并列出该账户对应的活跃订单。
• 权限范围 prices.read 现在仅用于保护 POST /v1/estimate/transfer。

2026-09-25 — GET /v1/prices 提供全天时段完整排期表

• PriceTable 新增 schedule[] 数组：包含每天各个时段的 id, label, start_utc_minute, end_utc_minute, factor_bps 以及 1 小时能量单价 price_sun_per_unit，客户端仅需单次调用即可绘制全天价格走势图。
• period 统一由排期表驱动。更新了时段标识与范围：drop, off_peak, ramp_9, ramp_11, ramp_12, peak, peak_late。请遍历排期数组，切勿硬编码。

2026-09-19 — 价格表与费用估算公开免签访问

• GET /v1/prices 与 GET /v1/estimate 支持公开免凭据调用。匿名请求基于 IP 频控限制；签名请求完整校验签名并走账户独立的频控额度。
• 签名的 GET /v1/estimate 根据调用方账户所属合约阶梯进行计价（大客户可看到专属优惠协议价）；匿名请求返回标准零售价。

2026-09-19 — 密钥前缀规范、活跃密钥上限与控制台会话

• API 密钥格式规范： ID 采用 ak_live_ + 24 字节随机串 (base64url)，Secret 采用 sk_live_ + 256 位随机串；Nile 测试网前缀为 ak_test_ / sk_test_。前缀显式声明环境归属，跨环境发送在查库前直接返回 1012 key_environment_mismatch。历史密钥保持有效。
• label 在 POST /v1/api-keys 中变为选填，默认为 Key N。scopes 规则不变：必填且无预选。
• 活跃密钥数量上限： GET /v1/api-keys 返回 limit 与 used；超出上限时返回新错误码 3017 api_key_limit_reached。
• ApiKey 增加 last_used_ip 与 last_used_at 字段。
• 控制台 Web 会话： 新增 POST, GET, DELETE /v1/session 与 POST /v1/session/refresh，采用 httpOnly Cookie 配合写操作的 X-CSRF-Token 头防范 CSRF。仅限浏览器环境。
• PATCH /v1/account 支持修改 display_name 账户别名。

2026-09-11 — 统一状态机与地址挑战注册模型

• 订单状态机流转： created → paid → allocating → delegated → confirmed → active → expired | reclaimed，异常时进入 failed 或 refunded 终态分支。
• Order 增加 partial 与 delivered_amount 字段：部分交付为正常订单上的属性，而非独立的状态。
• 新增 Webhook 事件 order.refunded。order.confirmed 包含 partial, delivered_amount 与 refunded_amount_sun。
• v1 版本不支持单个订单的主动撤销；3002 order_not_cancellable 归属于 POST /v1/batches/{id}/cancel。
• 基于地址签名的挑战注册： POST /v1/accounts/challenge 与 POST /v1/accounts/challenge/verify（返回 15 分钟临时 Token），POST /v1/accounts 与 GET /v1/accounts/deposit-address。新增错误码 1010 challenge_invalid, 1011 bootstrap_token_expired。
• 权限规范： 统一采用 area.action 词汇表 (ApiKeyScope)。创建密钥时必填，无默认值。
• Nile 测试网与主网差异： 完整收录在 网络与环境 文档中。