代理端口与抽水钱包 API

端口和钱包接口会直接改变挖矿代理行为。创建、修改、删除或批量调用前应备份配置，并把 X-ACCESS-TOKEN 视为高权限凭据。

本章字段来自已完成的前端表单模型，并使用当前实例的只读响应做过结构核对。真实响应中的钱包、矿池地址和标识不会写入文档。

端口接口与返回值

{id} 是 server.id，可能是字符串，也不等于监听端口 server.port。只有 /api/stat/port/{id} 使用实际监听端口号，详见图表标识说明。

PortRecord 完整结构

{
  "server": {},
  "wallets": [],
  "stat": {},
  "setting": {}
}

server 字段

KENC 和 SOCKS5 不通过额外的 protocol 数值区分：KENC 使用 protocol=1, setting.et_mode=1，SOCKS5 使用 protocol=0, setting.et_mode=2。

wallets[] 字段

wallets 最多配置 10 组。比例为 0 的表单行不会随端口创建/编辑请求提交。

server_id 必须来自GET /api/port/{id}响应的 server.id，不能使用监听端口号。

setting 字段

兼容保留字段没有足够的前端语义可安全推断。编辑端口时应先 GET，然后合并修改，避免把未知字段重置。

stat 字段

创建或编辑端口

创建和编辑使用相同主体：

{
  "port": 3333,
  "name": "BTC Proxy",
  "currency": "BTC",
  "category": "sha256",
  "protocol": 0,
  "limit_connections": 60000,
  "pool_address": "stratum.example.com:3333",
  "pool_address2": "backup.example.com:3333",
  "connect_mode": 0,
  "connect_mode2": 0,
  "mode": 0,
  "nc": 1,
  "pattern_addr": "",
  "replace_addr": "",
  "wallets": [
    {
      "addr": "fee-wallet",
      "device": "fee-worker",
      "pool_address": "fee-pool.example.com:3333",
      "pool_protocol": 0,
      "ratio": 0.01
    }
  ],
  "setting": {
    "port": 3333,
    "cp_name": "",
    "cp_mode": 1,
    "pu_mode": 0,
    "et_mode": 0,
    "pth": 1,
    "cut": 0,
    "fr": 0,
    "ft": 0,
    "op": 0,
    "sp": 0,
    "sd": "",
    "st": "",
    "ra": null,
    "lj": 0,
    "li": null,
    "cs": 0,
    "cl": 8
  }
}

若 currency 为 NGINX，或监听协议为纯转发 protocol=9，当前前端会禁用高级配置、清空 wallets，并把 mode 固定为 0。

无损模式请求约束

无损抽水当前仅支持 BTC 和 LTC。创建或编辑无损端口前，先请求 /api/lossless/pools，让用户按主矿池地址实际所属的平台选择一项，然后提交 mode: 2，并把所选项的 id 写入 setting.li。

所有 wallets[].pool_address 和 pool_protocol 必须与主矿池的 server.pool_address 和 connect_mode 一致；addr、device 和 ratio 不受此限制。setting.li 必须直接使用列表返回的 ID，不要自行生成。

后端无法仅根据地址替调用方确认矿池平台，因此客户端必须让用户主动选择。所选平台必须与主矿池地址属于同一矿池；列表中没有目标矿池时应提交 mode=0，不要强行使用无损模式。

无损模式矿池列表与检查

GET /api/lossless/pools 的典型响应：

[
  {
    "id": 1,
    "name": "Pool name",
    "state": 0
  }
]

列表由服务端动态返回，调用方不应缓存为固定白名单。切换币种或主矿池后，应清空旧选择并让用户重新确认。

GET /api/port/{id}/lossless/ok 返回 { "is_ok": true } 或 { "is_ok": false }，其中 {id} 使用 server.id。该接口只检查已有端口当前配置是否可使用无损模式，不会修改端口，也不能代替用户选择实际矿池平台。

批量导入

POST /api/ports/import

{
  "ports": [
    {
      "server": {},
      "wallets": [],
      "setting": {}
    }
  ]
}

ports[] 应使用本章的端口模型。响应是逐端口错误数组；即使 HTTP 状态为 200，也必须检查数组内容并展示部分失败。

测试矿池地址

POST /api/ping

{
  "address": "stratum.example.com:3333",
  "conn_type": 0
}

address 不带 stratum+tcp:// 等前缀。conn_type=0 表示普通连接，1 表示 TLS/SSL 类连接。此接口只测试连通性，不返回端口对象。

抽水钱包热更新

热更新表单用百分数展示，但请求中的 ratio 仍是 0–1 小数。钱包 id 和 server_id 均来自端口详情响应。

对 mode=2 的端口，热更新仍可新增、删除或修改钱包，并可调整 addr、device 和 ratio。pool_address 与 pool_protocol 必须继续跟随主矿池，不允许通过钱包热更新单独切换；如需更换主矿池或无损矿池平台，应编辑完整端口。

钱包与矿工名热替换

热替换规则属于一个已经创建的代理端口，因此所有接口中的 server_id 都必须使用 server.id，不能使用监听端口号。规则命中后，服务端会强制断开对应矿机；替换内容不会修改当前连接，而是在矿机下次接入时生效。

Web 后台的完整操作流程见钱包与矿工名热替换。

当前接口只支持 t=2 的钱包与矿工名组合规则；t=0 和 t=1 已废弃，不应继续提交。pat 与 target 都必须使用 wallet.device 格式，并且只能包含一个用于分隔钱包与矿工名的 .。

pat 左右两侧均支持单个值、逗号分隔的多个值或整侧 *，列表数量不受规则格式限制。普通值只允许英文字母、数字以及 _ @ -。例如 a.* 匹配钱包为 a 的所有矿工，*.b 匹配矿工名为 b 的所有钱包，*.* 匹配所有矿机，a,b,c.* 与 *.d,e,f 分别用于多钱包和多矿工名匹配。规则按完整值匹配，不支持正则表达式或把 * 嵌在普通文本中。

target 左右两侧均填写由上述普通字符组成的固定值或保留原值占位符。钱包侧可使用 #{WALLET}，矿工名侧可使用 #{DEVICE}。例如 a.#{DEVICE} 只替换钱包，#{WALLET}.b 只替换矿工名，c.d 同时替换两侧。占位符不能放到错误的一侧。

接口速查

热替换规则创建后不支持编辑。需要修改匹配规则或替换目标时，请先删除旧规则，再创建新规则。

创建规则

POST /api/ht/new
X-ACCESS-TOKEN: <Access Token>
Content-Type: application/json

{
  "server_id": "cEdmA.46",
  "pat": "wallet_a,wallet_b.*",
  "target": "#{WALLET}.worker-new",
  "t": 2,
  "address": "stratum.example.com:3333",
  "c": 0
}

address 和 c 是一组可选字段：需要同时重定向矿池时必须成对提交；只需要替换身份时，应同时省略这两个字段，而不是提交空 address。矿池重定向不会改变组合替换规则，规则命中后会应用钱包与矿工名目标，并让矿机在重新接入时连接到指定矿池。

获取规则

GET /api/ht/cEdmA.46
X-ACCESS-TOKEN: <Access Token>

[
  ["8ZLG", "cEdmA.46", "wallet_a,wallet_b.*", "#{WALLET}.worker-new", 2, "stratum.example.com:3333", 0],
  ["Mirr", "cEdmA.46", "*.worker_a,worker_b", "wallet-new.#{DEVICE}", 2]
]

当前前端也兼容字段含义相同的对象数组：

[
  {
    "id": "8ZLG",
    "server_id": "cEdmA.46",
    "pat": "wallet_a,wallet_b.*",
    "target": "#{WALLET}.worker-new",
    "t": 2,
    "address": "stratum.example.com:3333",
    "c": 0
  }
]

对象响应使用表中同名字段。调用方应把 address 和 c 作为一组处理；address 为空或不存在时，矿机继续使用当前端口配置的矿池，不应仅凭 c 推断已启用重定向。

删除规则

向 POST /api/ht 提交规则的 id 和所属端口的 server_id：

{
  "id": "8ZLG",
  "server_id": "cEdmA.46"
}

创建或删除成功后，应重新调用 GET /api/ht/{server_id}，不要只依赖 Ok 文本推断最终规则状态。矿工列表中的 wd 返回命中的组合规则 ID，它对应规则元组下标 0 的 id；hw 和 hd 已废弃。详见矿工响应字段。