unMineable API - Integrate mining data and account tools

概览

该 API 通过 HMAC-SHA256 签名认证提供对 unMineable 平台功能的编程访问。这个无状态 API 面向服务器到服务器集成和高级用户。

基础 URL

https://api.unmineable.dev/v1

认证

Public metadata and simulator routes do not require signing. All other requests must be signed with HMAC-SHA256 using your API credentials.

速率限制

每个 token/IP 每分钟 500 个请求

HMAC 认证

Authenticated endpoints require three HTTP headers:

x-user-api-key

你的 API token 公钥

x-user-api-timestamp

13 位毫秒级 Unix 时间戳

x-user-api-signature

小写十六进制 HMAC-SHA256 签名

签名载荷

签名通过将以下值用换行符拼接后计算得到：

<HTTP_METHOD>
<请求路径>
<原始 query 字符串（不含 ?）>
<x-user-api-timestamp>
<原始请求体的 sha256 十六进制值>

权限范围规则

read

仅限 GET 和 HEAD 请求

read_write

GET、POST、PATCH 和 DELETE 请求

错误代码

401 UNAUTHORIZED

凭证无效或缺失

401 INVALID_SIGNATURE

HMAC 签名校验失败

401 INVALID_TIMESTAMP

请求时间戳超出 5 分钟窗口

403 INSUFFICIENT_SCOPE

该 token 没有执行此操作所需的 scope

403 IP_NOT_ALLOWED

请求 IP 不在 token 的允许 IP 列表中

409 USER_ALIAS_REQUIRED

用户必须先创建默认 alias

代码示例（JavaScript）

const crypto = require('crypto');

function signRequest(method, path, queryString, body, timestamp, secret) {
  const payload = [
    method.toUpperCase(),
    path,
    queryString || '',
    timestamp,
    crypto.createHash('sha256').update(body || '').digest('hex')
  ].join('\n');
  return crypto.createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

const timestamp = Date.now().toString();
const signature = signRequest('GET', '/v1/me', '', '', timestamp, 'your-secret');

资料

GET

/v1/me

获取当前账户的资料信息，包括 UUID、电子邮件、用户名、推荐码以及 alias 状态。

Auth: 必需 (scope: read)

请求头

x-user-api-key: upk_abc123...
x-user-api-timestamp: 1743460800000
x-user-api-signature: a1b2c3d4...

POST

/v1/me

每次请求只更新一个资料字段。接受 username（用于创建默认 alias）或 referrer_code，也接受 null 来清除它。

Auth: 必需 (scope: read_write)

请求（用户名）

{ "username": "myalias" }

Workers

GET

/v1/workers

列出所有 workers，支持分页、过滤和排序。返回未过滤计数以及过滤后的细分计数。

Auth: 必需 (scope: read, 需要 alias)

Query 参数：

page, algorithm, online, region, name, chart_algo, period, sort, dir

Query 字符串

?page=1&algorithm=randomx&online=true&chart_algo=randomx&period=24h&sort=last_seen&dir=desc

GET

/v1/workers/counts

返回 workers 数量：总数、在线和离线。

Auth: 必需 (scope: read, 需要 alias)

Query 字符串

GET

/v1/workers/chart

返回按算法分组的时间序列 hashrate 数据，用于图表展示。

Auth: 必需 (scope: read, 需要 alias)

Query 参数：

chart_algo, period (1h|24h)

Query 字符串

?period=24h&chart_algo=randomx

付款

GET

/v1/payments

分页返回用户付款，并附带 coin/network 补充信息和过滤后的计数器。

Auth: 必需 (scope: read, 需要 alias)

Query 参数：

page, coin, network, date_from, date_to, tz, status, sort, dir

Query 字符串

?page=1&coin=BTC&network=BTC&date_from=2026-03-01&date_to=2026-03-31&tz=-180&status=success&sort=timestamp&dir=desc

POST

/v1/payments

请求一次手动付款。付款金额由账户余额推导得出。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{ "coin": "BTC", "uuid": "addr-uuid" }

GET

/v1/payments/:uuid/events

返回指定付款的事件时间线。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/payments/550e8400-e29b-41d4-a716-446655440001/events

资产

GET

/v1/assets

返回账户的混合资产目录，包括 coin 资产和已附加的旧版地址。

Auth: 必需 (scope: read, 需要 alias)

Query 参数：

is_active, sort, dir

Query 字符串

?is_active=true&sort=amount&dir=desc

GET

/v1/assets/:coin/stats

返回 coin 级别统计信息，包括余额、挖矿奖励、推荐奖励和付款总额。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/assets/BTC/stats

POST

/v1/assets/update

替换当前登录账户的奖励分配。接受 { coins: [...] }、{ targets: [...] } 或原始数组。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{
  "targets": [
    { "type": "coin", "coin": "BTC", "reward_hashrate_percentage": 0.6, "reward_algorithm": "randomx" },
    { "type": "legacy_address", "uuid": "legacy-address-uuid", "reward_hashrate_percentage": 0.4 }
  ]
}

旧版地址

POST

/v1/legacy-addresses/attach

将一个已存在的共享旧版地址附加到当前登录账户。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{ "uuid": "legacy-address-uuid" }

GET

/v1/legacy-addresses/:uuid

返回一个已附加旧版地址的当前设置。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/legacy-addresses/550e8400-e29b-41d4-a716-446655440002

GET

/v1/legacy-addresses/:uuid/stats

返回共享旧版地址的统计信息，包括余额和奖励总额。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/legacy-addresses/550e8400-e29b-41d4-a716-446655440002/stats

PATCH

/v1/legacy-addresses/:uuid

更新一个已附加旧版地址的设置。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{ "auto_detach_on_payment": true }

DELETE

/v1/legacy-addresses/:uuid

将旧版地址从当前登录账户解除绑定。

Auth: 必需 (scope: read_write, 需要 alias)

路径

/v1/legacy-addresses/550e8400-e29b-41d4-a716-446655440002

POST

/v1/legacy-addresses/:uuid/payments

为一个已附加旧版地址请求手动付款。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{ "platform": "api" }

推荐

GET

/v1/referrals

列出当前登录账户在 account-flow 和 legacy 来源中的被推荐 workers。

Auth: 必需 (scope: read)

Query 参数：

page, type, algorithm, online, sort, dir

Query 字符串

?page=1&type=user,legacy&online=true

仪表盘

GET

/v1/dashboard/assets

用于快速渲染仪表盘的最小化资产视图。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/dashboard/assets

GET

/v1/dashboard/summary

仪表盘数据的最新汇总快照。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/dashboard/summary

GET

/v1/dashboard/events

分页返回仪表盘事件，包括 worker、奖励和付款事件。

Auth: 必需 (scope: read, 需要 alias)

Query 参数：

page, type, dir

Query 字符串

?page=1&type=worker,reward,payout&dir=desc

地址

GET

/v1/addresses

列出当前账户拥有的所有提现地址。

Auth: 必需 (scope: read, 需要 alias)

Query 参数：

network, enabled, page, sort, dir

Query 字符串

?network=BTC,ETH&enabled=1&page=1

POST

/v1/addresses

创建一个新的提现地址。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{
  "network": "ETH",
  "alias": "Main Wallet",
  "address": "0xabc123...",
  "memo": "",
  "platform": "api"
}

PATCH

/v1/addresses/:uuid

更新现有提现地址中可变的字段。

Auth: 必需 (scope: read_write, 需要 alias)

Query 参数：

dry_run

请求

{ "alias": "New Label", "platform": "api" }

DELETE

/v1/addresses/:uuid

软删除一个提现地址。

Auth: 必需 (scope: read_write, 需要 alias)

Query 参数：

dry_run

路径

/v1/addresses/550e8400-e29b-41d4-a716-446655440098

提现设置

GET

/v1/assets/:coin/withdraw/address

返回指定资产当前的提现偏好设置。

Auth: 必需 (scope: read, 需要 alias)

路径

/v1/assets/BTC/withdraw/address

POST

/v1/assets/:coin/withdraw/address

设置指定资产的提现偏好。

Auth: 必需 (scope: read_write, 需要 alias)

请求

{
  "uuid": "addr-uuid",
  "payment_threshold": "0.005",
  "auto_withdraw": true
}

元数据

GET

/v1/meta/coin

Public coin metadata with optional compact mode and categories grouping.

Auth: none

Query 参数：

compact, categories

Query 字符串

?compact=true

GET

/v1/meta/coin/:coin

Public coin detail for a specific coin.

Auth: none

路径

/v1/meta/coin/ADA

Simulator

POST

/v1/simulator

Public forward mining simulator for advanced and device modes.

Auth: none

请求

{
  "mode": "advanced",
  "coin": "BTC",
  "algorithm": "randomx",
  "hashrate_hs": "120000000",
  "scenario_set": "default",
  "referral_discount": false
}