Introduction

An authentication failure from the ViaBTC Pool API is not, by itself, evidence that an API key has been revoked or compromised. ViaBTC's API documentation separates several distinct causes of a failed authenticated request — an invalid API key, a signature error, an invalid timestamp parameter, and an IP address that is not on the account's whitelist. These conditions have distinct documented error codes. An invalid API key and a signature error require different checks, but an incorrect or mismatched secret key can also cause a signature failure. Resetting or deleting credentials before identifying which condition applies can interrupt a working integration without addressing the underlying configuration issue.

Start with the returned error code: check the API key for 12001, the signature and secret-key pairing for 12002, the timestamp for 12003, and the IP whitelist for 12004. If you suspect credential exposure, rotate or delete the affected credentials promptly rather than waiting to complete routine troubleshooting.

This article explains these authentication requirements, suggests a practical troubleshooting sequence, and outlines when replacing the key pair is appropriate.

API Credentials Are Not Mining-Worker Credentials

Before troubleshooting an authentication error, it is worth separating two unrelated credential types that are sometimes confused in support requests.

A ViaBTC API key and its paired secret key are used by an external application — a monitoring script, a dashboard, or an accounting tool — to request account-level data such as balances or hashrate statistics from the pool's API. They are entered into that application's configuration, not into mining hardware.

ASICs and mining software instead connect to the pool using a Stratum URL and a worker name, following the standard mining-protocol flow in which a miner submits proof-of-work shares to the pool. This connection does not use the API key or secret key at all. If a miner has stopped submitting shares or a dashboard is showing stale hashrate data, the first question to resolve is which of these two systems is actually failing, since the diagnostic steps for each are unrelated.

How ViaBTC Verifies an API Request

According to ViaBTC's published API authentication requirements, a request can be rejected for any of four distinct reasons, and not every endpoint checks for all of them in the same way.

The account must have an IP whitelist configured, and the request's source address must appear on it; this check applies regardless of whether the endpoint requires a signature. The X-API-KEY header must contain a value that belongs to the account or subaccount being queried. For endpoints that are documented as requiring a signature, the request must include an X-SIGNATURE header computed with HMAC-SHA256 using the secret key paired with that API key — calculated from the query string for GET and DELETE requests, or from the JSON request body for POST and PUT requests. Signed requests must include a tonce parameter, defined as the current timestamp in milliseconds, generated immediately before the signature is created.

Each account and subaccount has its own API key and secret key. ViaBTC's documentation also notes that a subaccount uses the primary account's IP whitelist only when the subaccount's own whitelist has not been configured — it does not state that this inheritance applies unconditionally, so operations that manage several subaccounts should confirm which whitelist is actually in effect for the one producing the error.

Reading the Error Code Before Reacting

ViaBTC's API responses are returned as JSON, with a code field indicating success or failure and a message field describing the result. A value of 0 indicates success; any other value corresponds to a documented error. The ViaBTC API error codes reference lists four codes relevant to authentication:

Use the error code to choose the next check, not to rule out every other possible issue. For 12001, verify the API key being sent and confirm that the integration uses the intended account's credentials. For 12002, check both the paired secret key and signature construction. Replacing credentials is usually unnecessary for timestamp or whitelist errors because it does not correct those settings.

A Diagnostic Checklist Before Resetting Credentials

The following is a suggested troubleshooting sequence. It does not describe a documented server-side validation order; use the returned error code to prioritize the relevant checks.

1. Log the exact code and message returned. Capture the JSON response body (with the secret key redacted before sharing it anywhere) rather than relying on a generic "authentication failed" message from an application layer that may be summarizing several possible causes.

2. Confirm whether the endpoint requires a signature. ViaBTC's API reference marks each endpoint as requiring a signature or not. For example, the account-hashrate endpoint is documented as a GET request that needs only the coin parameter and X-API-KEY, with no signature required. If this request succeeds and a signed request using the same API key and outbound IP fails with 12002 or 12003, prioritize secret-key pairing, signature construction, and timestamp generation. The successful request confirms only that request's authentication conditions. For other failure codes, follow the reported error rather than assuming a signature or timestamp problem.

3. Compare the request's source IP against the whitelist. A script that continues to run correctly after a server migration, a change of cloud region, or a new NAT gateway can still fail with 12004 if its outbound IP address changed and the whitelist was not updated. This is a common and easily overlooked cause, since the API key and secret are unaffected by an infrastructure change of this kind.

4. Verify that the API key and secret belong to the same account or subaccount. Because each account and subaccount has its own key pair, an integration that monitors multiple subaccounts can end up pairing one account's API key with another account's secret, particularly after a previous key reset. This produces a signature error even though both values are individually valid credentials.

5. Rebuild the signature from the exact data that is actually transmitted. The HMAC-SHA256 signature must be calculated from the same query string or JSON body that is sent on the wire. If request middleware, a serialization library, or a proxy reorders parameters, changes encoding, or adds fields after the signature was generated, the server will compute a different signature than the client did and return 12002. The fix here is to verify the request-construction pipeline, not to assume the secret key is wrong.

6. Check system clock synchronization and timestamp units. tonce must be a current timestamp expressed in milliseconds. A ten-digit seconds-based value, a timestamp generated well before the request is actually sent, or a system clock that has drifted can all produce 12003. None of these are corrected by replacing the key pair.

If there is no suspected credential exposure, complete the checks relevant to the reported error before replacing credentials. Replacement may be appropriate if 12001 persists after verifying the submitted key, or if the correct secret key cannot be recovered for signed requests. Suspected exposure warrants prompt rotation or deletion without waiting for this checklist.

When Replacing the Key Pair Is the Appropriate Response

ViaBTC's API setup guide documents options to reset an API secret key pair or delete it; deletion requires email verification and a Google Authenticator code. Resetting or deleting credentials is a reasonable response in several specific situations:

• The error persists as 12001 after confirming the request is sending the correct key for the correct account or subaccount.
• The secret key was lost or was never recorded, making it impossible to restore a signed integration.
• An integration or third-party application has been retired and no longer needs access.
• There is any reason to suspect the key or secret has been exposed — for example, pasted into a public repository, screenshot, chat log, or support ticket.

In the exposure case specifically, prompt rotation or deletion is appropriate without extended troubleshooting, since the risk of continued use outweighs the value of diagnosing the original error. ViaBTC advises keeping both the API key and secret key confidential, and this applies throughout any troubleshooting process — neither value should be shared in a support request, forum post, or log file. Up to 20 IP addresses can be configured per account whitelist, one per line, which is generally enough to cover a small number of application servers without needing to loosen the whitelist as a workaround.

FAQ

Does an API key need to be entered into my ASIC's configuration?

No. The API key and secret key authenticate requests to the ViaBTC Pool API from an external application. ASICs and mining software connect to the pool using a Stratum URL and worker name, which is a separate credential system.

My API key is correct, so why does the request fail with "IP not allowed"?

ViaBTC's API checks the request's source IP address against the account's configured whitelist independently of whether the API key itself is valid. A correct key sent from an address that is not on the whitelist still returns error 12004.

Why does one endpoint return a signature error while another works fine with the same key?

Not all ViaBTC endpoints require a signature. An unsigned endpoint can succeed without X-SIGNATURE when its other requirements are met. If a signed endpoint returns 12002 using the same API key and outbound IP, check that the secret key is paired with that API key and that the signature is calculated from the transmitted request data.

Should I reset my API key after receiving an invalid-tonce error?

Not as a first step. Error 12003 points to the timestamp parameter rather than the key. Check that the system clock is synchronized and that tonce is sent as a current timestamp in milliseconds rather than seconds before considering any credential change.

References

• ViaBTC Pool API, "API Authentication", GitHub wiki.
• ViaBTC Pool API, "Error Code", GitHub wiki.
• ViaBTC Pool API, "Acquire Account Hashrate", GitHub wiki.
• ViaBTC Help Center, "What is API and How to Set Up".