Proxy Port and Fee-Wallet API

These calls directly change proxy behavior. Back up configuration and treat X-ACCESS-TOKEN as a high-privilege credential. The models below come from the completed frontend and were checked against read-only responses from a running instance.

Endpoints and responses

{id} is server.id, which may be a string and is not the listen port. /api/stat/port/{id} is the exception: it uses server.port.

Complete PortRecord

Every record contains server, wallets[], stat, and setting.

server

KENC uses protocol=1, setting.et_mode=1; SOCKS5 uses protocol=0, setting.et_mode=2.

wallets[]

At most ten fee-wallet rows are supported. Rows with a zero ratio are omitted by the current frontend.

Never substitute the numeric listen port for server_id.

setting

Reserved fields do not have enough frontend semantics to infer safer values. Read the port first and merge changes instead of replacing the object.

stat

Create or edit body

{
  "port": 3333,
  "name": "BTC Proxy",
  "currency": "BTC",
  "category": "sha256",
  "protocol": 0,
  "limit_connections": 60000,
  "pool_address": "stratum.example.com:3333",
  "pool_address2": "",
  "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
  }
}

For NGINX or protocol=9, the frontend disables advanced options, clears wallets, and forces mode=0.

Lossless-mode request rules

Lossless pumping currently supports BTC and LTC only. Before creating or editing a lossless port, call /api/lossless/pools, ask the user to select the platform that actually owns the primary-pool address, and submit mode: 2 with the selected pool id in setting.li.

Every wallets[].pool_address and pool_protocol must match server.pool_address and connect_mode. Wallet addr, device, and ratio remain independent. Use the ID returned by the endpoint; do not invent one.

The backend cannot determine the user’s pool platform from the address alone. If the selected platform does not match the primary-pool address, lossless operation can fail with serious, unpredictable results. If the target pool is absent from the returned list, submit mode: 0 instead.

Lossless pool list and eligibility

GET /api/lossless/pools returns entries shaped as follows:

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

Treat this as a dynamic server list, not a hard-coded allowlist. Clear the old selection and ask the user again after the coin or primary pool changes.

GET /api/port/{id}/lossless/ok returns { "is_ok": true } or { "is_ok": false }. {id} is server.id. This read-only check reports eligibility for the current configuration and does not replace the required user selection of the actual pool platform.

Bulk import and connectivity test

POST /api/ports/import accepts { "ports": [...] }, where each item follows this chapter’s port model. Inspect the returned error array even on HTTP 200.

POST /api/ping accepts:

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

Do not include a stratum+tcp:// prefix. conn_type=0 is plain TCP and 1 is TLS/SSL-like.

Hot-update fee wallets

The form displays percentages, but ratio in the request remains a 0–1 fraction. Both IDs come from the port-detail response.

For a mode=2 port, hot update can still add, remove, or edit wallets and can change addr, device, and ratio. pool_address and pool_protocol must continue to follow the primary pool and cannot be switched independently. Edit the complete port to change the primary pool or lossless pool platform.

Wallet and worker-name hot replacement

A hot-replacement rule belongs to an existing proxy port. Every server_id below must therefore be the port’s server.id, never its numeric listen port. When a rule matches, the server forcibly disconnects the affected miner. The replacement does not alter the current connection; it takes effect when the miner reconnects.

See Wallet and worker-name hot replacement for the complete Web UI workflow.

The current endpoint accepts only the combined wallet-and-worker rule type t=2. Types t=0 and t=1 are deprecated and must no longer be submitted. Both pat and target use the wallet.device format with exactly one dot separating the wallet and worker-name sides.

Each side of pat accepts one value, a comma-separated list, or a whole-side *; the rule format does not cap the list length. Ordinary values accept ASCII letters, digits, _, @, and -. For example, a.* matches every worker using wallet a, *.b matches worker name b under any wallet, *.* matches every miner, and a,b,c.* or *.d,e,f match several wallets or worker names. Matching uses complete values; regular expressions and partial wildcards are not supported.

Each side of target is either a fixed value made from the ordinary characters above or its preserve-current-value placeholder. Use #{WALLET} on the wallet side and #{DEVICE} on the worker-name side. For example, a.#{DEVICE} changes only the wallet, #{WALLET}.b changes only the worker name, and c.d changes both. A placeholder cannot be used on the wrong side.

Endpoint summary

Hot-replacement rules cannot be edited after creation. To change the match pattern or replacement target, delete the existing rule and create a new one.

Create a rule

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 and c form one optional pair. Send both when the matched miner should also be redirected to another pool. When only the identity should change, omit both fields instead of sending an empty address. Pool redirection does not alter the combined replacement rule: after a match, the server applies the wallet and worker-name targets and reconnects the miner to the specified pool.

Read rules

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]
]

The current frontend also accepts an object array with the same field meanings:

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

Object responses use the corresponding named fields. Treat address and c as one pair. If address is empty or absent, the miner keeps using the pool configured on the current port; do not infer that redirection is enabled from c alone.

Delete a rule

Send the rule id and its port server_id to POST /api/ht:

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

After creating or deleting a rule, call GET /api/ht/{server_id} again instead of treating the Ok text as the final state. Worker-list field wd contains the matched combined rule ID and corresponds to tuple index 0 (id) in the rule response. Fields hw and hd are deprecated. See the worker response fields.