将项目中的 Nonce API v1 集成迁移到 API v2
success、data 和 error。
示例的 API 地址为 https://api.nonce.app。下表省略 v1 的 /private-api/v1/{workspace_id} 前缀；/me 的完整路径为 /private-api/v1/me。
认证
有效的 workspace API key 继续通过Authorization: Bearer <workspace_api_key> 传入。v2 中，401 表示认证失败，403 表示权限不足，404 表示资源不存在或不在可访问范围内，例如超出密钥授权范围的矿场。这些错误不能作为空列表处理。
分页
列表使用 URL 查询参数分页，搜索使用 JSON 请求体分页。page 和 page_size 均可省略，默认分别为 1 和 20。历史指标改为按时间范围查询，不使用分页。
分页信息位于
pagination，与 success、data、error 同级。
客户端从第 1 页开始读取，在 page < total_pages 时继续请求下一页；total 为 0 时结束。数据在读取期间可能变化，跨页结果不保证属于同一时刻。
旧 GET 接口未定义 limit 和 offset。使用过这两个参数的集成，需要检查原分页逻辑是否生效。
Workspace
已有的workspace_id 可以继续使用。原来通过 /me 获取 workspace 信息的集成，改用 ListWorkspaces：
data 改为无分页数组，按 id 选择目标 workspace。每项中的 workspace_id、workspace_name、workspace_slug 分别改为 id、name、slug。
使用 API key 时，列表包含密钥所属的 workspace（relations 含 member），以及通过有效授权可访问的 workspace（relations 含 grantee）。使用 OAuth 时，列表包含当前用户加入的 workspace。每项的 permissions 表示有效的 API 操作权限。
ListFarms 返回同一认证身份可以访问的矿场。permissions 不包含矿场 ID 列表。v2 目前没有接口提供 /me/grants 中完整的 farm_ids 和授权到期记录；依赖这些数据的集成，需要先确认数据获取方式，才能完成迁移。
矿场
v1：archived: true 后，可保持 v1 的查询范围。排序规则也已调整，相同页码不保证对应相同的记录。
Agent
v1 在整个 workspace 范围内查询 Agent：total 之和。
列表仍包含状态、版本、uptime 和更新时间，嵌套的 farm 对象改为 farm_id。主机信息不在列表摘要中，需要这些字段的集成可查阅兼容性说明。
矿机
ListMiners 返回无筛选列表，SearchMiners 用于筛选，两者返回相同的矿机摘要。
单位不变：
hashrate、expected_hashrate 使用 H/s，power 使用 W，efficiency 使用 J/TH。
v2 摘要不包含旧完整对象的所有字段。依赖 errors、hashboards、pools、psus、hashrate_24h 或重启计数的集成，需要另外确认数据获取方式。兼容性说明列出了这些限制，仅修改字段名不足以完成迁移。
筛选
SearchMiners 通过 JSON 请求体接收筛选条件，不同字段之间采用 AND。例如，查询“online 且存在风扇或电源异常”的矿机：
anomaly_filters 改为 anomaly_flags.in，ip_ranges 仍使用数组。
v2 的 status 只接受 online 和 stale，旧 offline 对应 stale。v1 中已被忽略的 error、low_hashrate 等健康状态不应转换成新的异常条件，否则会改变查询结果。详见兼容性说明。
精确 MAC 查询使用 search.field = "mac"，并通过 search.value 提供完整地址。由于字段搜索采用子串匹配，需要读取全部候选页，再忽略大小写比较完整 MAC，只统计精确匹配的记录。
last_updated_at 的 gt 和 lt 均为严格边界，返回结果不包含恰好等于边界的记录。
分类统计
QueryFarmMinerMetrics（beta）返回当前矿机分类和分布，请求从 GET 改为 POST，且不需要请求体。
v1：
v2 保留
theo 和 total，新增 period 表示数据观察时间，并在 mining_modes 的每项中增加 firmwares 分布。各分类可能重叠，总数以 total 为准；由于数据实时更新，不同请求的统计结果可能变化。
矿场不存在时，v1 可能返回空统计，v2 返回 404。查询历史趋势使用历史指标。
历史指标
QueryFarmMetrics（beta）用时间范围查询代替 v1 的分页查询，一次返回指定范围内的指标记录。以下示例查询 UTC 2026-09-01 的日级指标。
v1：
from_time，不包含 to_time。读取某一天的完整数据时，结束时间应设为次日零点。非 UTC 日期需要先按业务时区确定起止时间，再转换为 ISO 时间。
迁移时应明确传入 granularity：v1 默认 day，v2 默认 hour。
响应数据
历史记录从data 移到 data.snapshots，data 同时返回查询时间范围。日级记录仍包含 pool、agent、finance 和 electricity 字段。
snapshots 按时间升序排列，没有数据的时间段也会返回记录，其指标值为 null。null 表示数据缺失，不等同于 0，因此“最近 N 个时间段”与“最近 N 条有数据的记录”需要分别处理。
记录不再包含 id 和 workspace_id，需要唯一标识时，可组合使用 farm、时间粒度和 period。period 表示该时间段的开始时间，使用 ISO 8601 字符串。
查询范围
单次查询的最大范围如下：
超出上限时，应按原业务时区将查询拆成连续、不重叠的时间段，各段边界与所选粒度对齐，返回记录按
period 合并。旧的 7 天 10min 查询或 60 天 hour 查询，也需要按新的范围上限拆分。
task batch
列表使用 URL 查询参数，搜索使用 JSON 请求体。batch_id 改为 id。列表中的 failed_count 改为 unsuccessful_count，仍表示失败、超时和取消的合计。
详情与任务
v1 的 task batch 详情内嵌tasks；v2 改为由 GetTaskBatch 返回摘要，通过 ListTaskBatchTasks 单独分页读取任务。