TCMinerProxy API: Wallet Switching, Hashrate Routing & Farm Automation

TCMinerProxy for Large Bitcoin Mining Farms
Local Stratum Control, Multi-Pool Hashrate Routing, Wallet Switching and API Integration

Official website: https://www.tcminerproxy.com/
API documentation: https://www.tcminerproxy.com/document/tcminerproxy
GitHub project: https://github.com/mine-Proxy/TCMinerSystem

Target audience: large Bitcoin mining farms, hosting providers, site operators, mining hardware rental platforms and enterprise operations teams.

1. Overview

The difficult part of operating a large Bitcoin mining farm is not simply getting miners online. The real challenge is making controlled changes while thousands of ASICs continue to run: switching upstream pools, replacing wallets or pool subaccounts, migrating away from a failed route, applying customer-specific policies, and keeping a complete audit trail.

The traditional approach is to log in to each miner, or use several vendor-specific management interfaces, and then modify the pool URL, username or wallet on every device. This becomes difficult at scale:

Miner models and firmware versions expose different management interfaces.
Large batch operations take time and may only partially succeed.
The actual configuration on every device is difficult to verify.
Every policy change directly touches miner-side settings.
A failed update can leave part of the farm on the old configuration and part on the new one.

TCMinerProxy introduces a locally deployed control and forwarding layer between ASIC miners and upstream mining pools. After initial onboarding, miners connect to a stable TCMinerProxy address inside the farm network. Pool, wallet, subaccount, backup route and routing policies can then be managed at the proxy layer without repeatedly editing every miner.

The proxy can also route an authorized percentage of hashrate to multiple wallets or pool accounts. Each routing rule may use a different wallet, worker name, pool address and TCP or TLS connection mode.

This is more than changing a pool address. It moves network routing, settlement routing and operational policy from individual devices into a centralized and auditable control plane.

2. Why a local proxy layer is useful for institutional mining

2.1 Configure the miner once, manage later changes centrally

During initial onboarding, the owner or an authorized operator points each miner to a local TCMinerProxy listening address. After that, changes to upstream pools, wallet or subaccount targets and backup routes are made at the proxy layer.

Daily operations no longer depend on a particular ASIC brand, firmware version or vendor API. This can reduce repeated logins, device-side batch edits and inconsistent configurations across a mixed fleet.

"No miner modification" in this context means no additional miner-side modification after the initial proxy onboarding. The first connection to the local proxy must still be configured by the device owner or by an authorized mining farm operator.

2.2 Controlled switching for unpaid hosting or electricity fees

One practical hosting scenario is a customer who has not paid electricity or hosting charges by the contractual deadline. If the contract explicitly authorizes a temporary settlement-routing action, the overdue state can be converted into a controlled, reviewable and reversible proxy-layer workflow.

For example:

[list=1]

The billing system changes the customer state from ACTIVE to OVERDUE.
An orchestration service resolves the customer's site, rack, proxy port or miner group.
The service loads a pre-approved and whitelisted pool and wallet policy.
Finance and operations approve the change under a two-person control process.
TCMinerProxy applies the new upstream pool or wallet rule.
Monitoring verifies reconnects, hashrate, latency, accepted shares and rejected shares.
When payment is confirmed, the system restores the configuration version saved before the change.

The miners continue using the same local proxy address throughout this process. There is no need to log in to every ASIC or rewrite every miner's pool configuration.

Important: This function should only be used when the customer is informed, the contract clearly permits it, applicable law allows it, and the operator has a proper approval and audit process. It should not be used for hidden revenue redirection, and one administrator should not be able to bypass approval controls.

2.3 Pool failure and network instability can be handled at the proxy layer

A local proxy can monitor upstream connectivity and move affected ports to a validated backup pool when the primary pool is unavailable or a route experiences excessive latency or packet loss. The miner does not need to know that the upstream hostname or port has changed.

Multi-site operators can define a different pool priority for each location. A North American site, for example, may prefer a nearby pool endpoint and use a cross-region endpoint only as a backup.

2.4 Centralized observability and customer-level accounting

Proxy data can be integrated into an institutional monitoring platform. Useful metrics include:

Online and offline miners per proxy port, plus reconnect rate.
Real-time hashrate, short-period average and 24-hour average.
Upstream latency, connection success rate and failure reasons.
Accepted, rejected and stale shares.
Mappings among customers, sites, racks, ports, wallets and routing policies.
The requester, approver, time, configuration difference and result of every change.

The proxy can therefore become both a network boundary and an operational data boundary for billing reconciliation and customer support.

2.5 Local control and lower control-plane latency

Local deployment allows connection data, port mappings, customer identifiers and configuration versions to remain inside the mining farm network. If an external management platform is temporarily unavailable, the last published local forwarding policy can continue to operate.

Actual capacity, latency and bandwidth savings should still be tested against the farm's real network path, mining protocol and target pools.

3. Custom hashrate routing to multiple accounts, wallets and pools

The TCMinerProxy port model includes a wallets[] routing array. According to the public API documentation, one port can contain up to ten routing-wallet records. Each record can independently define:

addr — target wallet, pool account or subaccount
device — worker name submitted to that target
pool_address — target pool endpoint for this routing rule
pool_protocol — 0 for TCP or 1 for TLS/SSL
ratio — a value from 0 to 1; for example, 0.01 represents 1%

This allows an authorized portion of the hashrate carried by one proxy port to be routed to several settlement targets. The targets may be different accounts on the same pool or wallets/accounts on different pools.

Operational uses include:

Contract-based settlement: route an agreed hosting or operations share to an approved account, reducing manual off-chain reconciliation.
Multi-party revenue allocation: define transparent shares for the site operator, equipment owner, financing partner or other authorized participants.
Customer and site isolation: use different policies by customer, facility, rack, miner group or source wallet.
Multi-pool risk distribution: direct separate routing records to separate pools so that one pool's maintenance, account issue or network problem does not affect every routed share.
Low-cost policy updates: adjust ratios, wallets and pools at the proxy instead of modifying every ASIC.
Canary testing and gradual migration: route a small percentage to a new pool, verify latency and share quality, and then increase the percentage gradually.
Precisely scoped fee recovery: where explicitly authorized by contract, apply a temporary rule only to the relevant customer, wallet or miner group rather than changing the entire facility.

TCMinerProxy also exposes independent wallet-level and worker-level ratio controls. An institutional platform can therefore use three policy levels:

[list=1]

Port default: default multi-wallet and multi-pool routing rules for a miner group.
Source-wallet override: a customer-level percentage for miners connecting with a particular original wallet.
Worker/session override: an exception for an individual miner session, test unit or special device.

Percentage routing is not a guarantee of an exact payout amount. Final credited revenue depends on the pool's accounting rules, payout threshold, share calculation, rejection rate and network quality. Production systems should only accept whitelisted wallets and pools, validate policy totals against the contract, and log the requester, approver, start time, expiry condition and rollback version.

4. TCMinerProxy control API integration

The public documentation describes authentication, proxy-port management, wallet operations, worker statistics, remote fleet control and WebSocket behavior. API fields and responses may vary by installed version, so an institutional client should check the running version and implement compatibility handling before enabling write operations.

4.1 Enable and authenticate the API

The control API is enabled in rust-config:

[/list][/list]

Code:

ENABLE_CONTROL_API=1

After restarting the service, read or generate the API Key under Settings -> API and request a short-lived access token:

Code:

POST /{safe-route}/api/generate/access/token
Content-Type: application/json

{
  "k": "<API_KEY>"
}

Successful response:

Code:

{
  "access_token": "<ACCESS_TOKEN>"
}

Subsequent requests use the header defined by the documentation. Do not add a Bearer prefix:

Code:

X-ACCESS-TOKEN: <ACCESS_TOKEN>
Content-Type: application/json

The documented access-token lifetime is approximately two hours. Generating a new token invalidates the old token, while refreshing the API Key invalidates the previous key and existing tokens.

Because the current frontend does not expose multiple API keys, granular scopes or detailed API rate-limit controls, a large operator should add source-IP allowlists, rate limiting, credential isolation and network access control at its reverse proxy, firewall and orchestration layers.

4.2 Proxy-port, pool and wallet endpoints

Code:

GET    /api/ports               Read all proxy ports
GET    /api/port/{id}           Read one complete port configuration
POST   /api/port/new            Create a proxy port
POST   /api/port/{id}           Edit pool, protocol, backup and port settings
POST   /api/port/{id}/start     Start a port
POST   /api/port/{id}/stop      Stop a port
POST   /api/ping                Test target-pool connectivity before switching

A port object may contain pool_address, pool_address2, connect_mode, connect_mode2, proxy_addr, proxy_device, wallets[] and setting. pool_address2 can serve as a backup upstream endpoint. In unified-account mode, proxy_addr and proxy_device define the unified settlement target.

For automated edits, first retrieve the complete port object, merge only the intended changes, and then write the complete object back to /api/port/{id}. Do not construct a minimal replacement object that drops compatibility or reserved fields. After a successful HTTP response, retrieve the port again and verify the normalized server-side state.

4.3 Multi-wallet and multi-pool routing example

The following fragment illustrates two rules on the same proxy port. It routes 2% to an authorized account on pool A and 1% to an authorized account on pool B. The two targets also use different transport protocols.

Code:

{
  "wallets": [
    {
      "addr": "authorized_account_a",
      "device": "farm_a",
      "pool_address": "pool-a.example.com:3333",
      "pool_protocol": 0,
      "ratio": 0.02
    },
    {
      "addr": "authorized_account_b",
      "device": "farm_b",
      "pool_address": "pool-b.example.com:443",
      "pool_protocol": 1,
      "ratio": 0.01
    }
  ]
}

This is an explanatory fragment, not a complete port-update body. A real update must preserve the other fields returned by the server.

The documentation also exposes hot-update operations for individual routing-wallet records:

Code:

POST    /api/wallet/new         Create a complete routing-wallet rule
POST    /api/wallet/{id}        Update a specified routing-wallet rule
DELETE  /api/wallet/{id}        Delete a specified routing-wallet rule

For these operations, server_id must come from server.id in the owning port record. It is not the numeric miner-facing listening port. After every write, retrieve the port and verify the saved ratio, pool endpoint, protocol and wallet ID.

Three levels of ratio control

Code:

Port default:
  wallets[] and /api/wallet/*

Source-wallet override:
  GET/POST /api/port/{id}/wallet/ratio

Single-worker override:
  GET  /api/wallet/{wallet_id}/worker/{sid}/ratio
  POST /api/port/{id}/worker/ratio

A wallet-level write uses the original miner wallet wallet, target routing-wallet ID wid, and ratio r. A worker-level write uses the session ID sid, wid and r. The f flag saves an independent rule with f=1 or restores the default with f=0. The wid value must come from the current port's wallets[].id; it should not be generated by the API client.

4.4 Wallet and worker-name hot replacement

TCMinerProxy provides dedicated hot-replacement endpoints:

Code:

GET   /api/ht/{server_id}       Read current replacement rules
POST  /api/ht/new               Create a wallet or worker-name rule
POST  /api/ht                   Delete an existing rule

Example: apply a new wallet target to every device on one proxy port:

Code:

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

{
  "server_id": "cEdmA.46",
  "pat": "*",
  "target": "wallet_target",
  "t": 0
}

server_id must be the port record's server.id, not the numeric listening port.
pat can be an exact original wallet for precise matching; * matches all devices on the proxy port.
target is the wallet, subaccount or worker name to use after reconnect.
t=0 replaces the wallet; t=1 replaces the worker name.

Existing rules are deleted and recreated rather than edited in place. After an Ok response, query GET /api/ht/{server_id} and verify the active rule.

A wildcard rule can reconnect many miners at once. For a fleet of thousands, apply changes by port or miner group in batches to avoid a connection storm or upstream rate limiting.

4.5 Monitoring and real-time verification

Code:

GET /api/port/{id}/g/workers    Worker status, wallet, hashrate, latency and shares
GET /api/stat/port/{id}         Port hashrate history
GET /api/port/{id}/log          Port logs
GET /api/port/{id}/ips          Current TCP connections
GET /api/sys/base/info          Proxy node information
GET /api/sys/stat               Proxy node resource status
WSS /{safe-route}/api/ws        Real-time Stratum group data

WebSocket subscriptions use group_id, and the documentation recommends sending a ping heartbeat every ten seconds. An institutional platform can observe disconnect, reconnect and share recovery during a switch. This turns "the API accepted the request" into "the mining operation has recovered and is producing valid shares."

4.6 Multi-site fleet visibility

The Fleet API allows one TCMinerProxy instance to retrieve operational information from other instances, including remote ports, hashrate, connected devices, system resources and version data. A large operator can deploy proxy nodes per site and aggregate status centrally.

Fleet tokens and normal X-ACCESS-TOKEN credentials should be stored and rotated separately. Remote forwarding paths should use fixed allowlists and must not allow an external caller to construct arbitrary destinations.

5. What "seconds-level seamless switching" actually means

The public website and documentation describe API integration for pool switching and one-click wallet changes. This does not mean an established TCP/Stratum session is magically moved between two pools without interruption.

The miner-facing local proxy address remains unchanged. The proxy triggers a short reconnect, and the new pool, wallet or worker rule is applied to the new session. "Seamless" should therefore be understood at three levels:

Configuration continuity: there is no need to log in to the miner or change its pool URL again.
Operational continuity: an internal platform can select a target, publish a rule and verify the result as one workflow.
Near-transparent connection recovery: the miner briefly disconnects and automatically reconnects, normally entering the new session within seconds. This should not be marketed as absolute zero interruption at the network layer.

Example workflow for a contractually authorized overdue-payment case

Code:

Billing system confirms overdue status
        |
Finance + operations approval
        |
GET /api/ports and resolve the customer's server.id
        |
POST /api/ping to validate the new upstream pool
        |
Save the current port configuration and replacement rules
        |
POST /api/port/{id} to update primary/backup pool if required
        |
POST /api/ht/new to publish the wallet or worker-name rule
        |
Miners briefly reconnect through the same local proxy endpoint
        |
Workers / Stats / WebSocket verify hashrate and accepted shares
        |
Archive the audit result, or restore the saved configuration on failure

The orchestration service should wrap these API calls in an idempotent asynchronous task:

Code:

CREATED -> VALIDATING -> APPROVED -> APPLYING -> RECONNECTING -> OBSERVING -> SUCCEEDED
                  \-> REJECTED       \-> ROLLING_BACK -----------------> ROLLED_BACK

Pre-change validation

Confirm that pool domains, ports and protocols are whitelisted.
Validate wallet or subaccount formats and prevent copy/paste substitution errors.
Test DNS, TCP/TLS and Stratum connectivity from the proxy node.
Confirm that the customer-to-port mapping does not cross tenant boundaries.
Compare the current configuration version with the version expected by the caller.

Canary rollout

Switch a small miner group or one proxy port first. Observe connection success, accepted shares and rejection rate. Expand in batches only after the metrics are healthy. Thousands of miners should not reconnect in the same second.

Automatic verification and rollback

Do not treat an HTTP success response as proof of a successful mining transition. Wait through a configurable observation window and verify online percentage, hashrate, accepted shares and upstream latency. Restore the previous configuration version and raise a high-priority alert when metrics exceed thresholds.

Restoring service after payment

When the billing system confirms payment, restore the saved pre-overdue configuration version. Do not build a new configuration from memory, because the customer's original primary pool, wallet, subaccount, backup route and other port options should all be restored together.

6. Recommended topology for large mining farms

A large institution should not depend on a single proxy server. A more resilient design deploys nodes by site or network zone:

At least two proxy nodes per site to reduce single-point-of-failure risk.
Separate miner, proxy-management and office network segments.
Allow API access only from orchestration services and controlled operations terminals; do not expose the control API directly to the public Internet.
Maintain a validated primary and backup upstream route.
Use a common time source so logs, billing data and audit events share consistent timestamps.
Aggregate monitoring centrally, while keeping control operations close to each site where practical.
Use least-privilege service identities across sites and do not share a global administrator credential.

The project provides Linux and Windows deployment options. Large farms will normally benefit from running the proxy on controlled servers that are included in existing configuration-management, logging, backup and patching processes.

7. Security, audit and compliance

Changing a wallet or pool subaccount can affect revenue ownership. The control API therefore requires stronger protection than a read-only monitoring interface.

[list=1]

Separate read and write roles: monitoring reads metrics, billing requests a policy action, and only the orchestration service writes the final configuration.
Two-person approval: finance and operations should independently approve changes that affect settlement routing.
Short-lived credentials: avoid long-term shared administrator passwords; use short-lived tokens and protected service identities.
Wallet and pool allowlists: production requests should select pre-approved profiles rather than accepting arbitrary wallet strings or pool endpoints.
Immutable audit trail: store caller, approvers, old state, new state, business reason, ticket ID and verification result in protected audit storage.
Complete notifications: notify the customer and internal operators before a switch, after success, on rollback and after service restoration.
Emergency stop: suspend automated changes if a cross-tenant mapping, abnormal rejection rate or credential compromise is detected.
Contractual and regional compliance: define triggers, grace period, revenue ownership, restoration and dispute handling in the contract, and confirm that the process is lawful in the relevant jurisdiction.

8. Suggested implementation path

Phase 1 — Test environment

Connect a small number of test miners to a dedicated TCMinerProxy port. Validate primary and backup pools, wallet/subaccount replacement, multi-wallet and multi-pool percentage routing, wallet-level and worker-level overrides, reconnect behavior, accepted shares and rollback. Compare proxy statistics with every target pool and allow for normal short-window statistical variance.

Phase 2 — Asset and customer mapping

Create unique mappings among sites, racks, miners, proxy nodes, ports, customers, contracts and billing accounts. Correct mapping is essential to prevent one customer's policy from being applied to another customer's miners.

Phase 3 — Read-only monitoring

Integrate online state, hashrate, latency, connection quality and port health first. Let the read path operate until the data is stable before enabling configuration writes.

Phase 4 — Controlled writes and gradual expansion

Start with manual approval, one port and a low routing percentage. Expand gradually to multiple wallets, multiple pools, customer groups and full sites. Set an observation window before increasing the percentage or device count, and verify accepted shares at every target pool. Include capacity tests, reconnect-storm tests, failure injection and rollback drills at each stage.

9. Conclusion

For a large Bitcoin mining farm, TCMinerProxy is not only a pool traffic forwarder. It can act as a local policy layer between ASIC miners and upstream pools.

After miners are initially pointed to a stable local proxy endpoint, the operator can centrally manage upstream pools, wallets or subaccounts, backup routes and customer-specific policies. Authorized hashrate can also be routed by custom percentage to multiple accounts, with a different wallet and pool defined for each rule.

In an authorized operational case such as unpaid electricity or hosting fees, the proxy architecture can turn a risky and time-consuming device-by-device change into an approved, canary-tested, monitored, auditable and reversible configuration task.

For institutional use, API automation must be combined with high availability, configuration versioning, idempotency, two-person approval, wallet and pool allowlists, monitoring verification and legal compliance. Only then does "one-click switching" become a controlled operational capability rather than a dangerous shortcut.

References

Technical note: The /api/... paths, X-ACCESS-TOKEN header, hot-replacement fields and monitoring endpoints in this post are based on the currently published TCMinerProxy documentation. The overdue-payment approval workflow, idempotent task state machine, canary deployment and rollback design are proposed institutional integration patterns. API fields and responses can depend on the installed version; verify them against the exact deployment version before enabling production write operations.
[/list]