FAQ

Authentication & Access

• How do I get an API key? Sign up at TheRPC.io, open your Dashboard, go to API Keys, and click Generate. Drop the key into https://bitcoin.therpc.io/YOUR_API_KEY or send it as a Bearer header.
• Can I have more than one key? Yes. Create a separate key per app or environment (dev, staging, production) so you can track usage independently and revoke one without breaking the others.
• What if a key leaks? Revoke it immediately from the dashboard, then generate a new one and update your environment variables. Treat any key seen in a log, screenshot, or chat as compromised.

API Usage

• Is there a WebSocket or subscription API? No. Bitcoin Core RPC is HTTP POST request/response only — there is no subscribe method and no push channel, so TheRPC doesn't offer one either.
• How do I watch for new blocks? Poll the tip. Call getblockcount (or getbestblockhash) on a sensible interval and react when the value changes. Since blocks arrive roughly every 10 minutes, polling every few seconds wastes quota — a short interval only while actively watching is enough.
• How should I handle rate limits? Retry with exponential backoff on the rate-limit error, cache slow-changing data, and upgrade your plan if you regularly hit the ceiling.
• What HTTP timeout should I use? Light reads like getblockcount return fast, but heavier ones — getblock at verbosity 2 or 3, or a verbose getrawmempool — return much larger payloads and take longer. Set a generous timeout (several seconds or more) for those calls rather than a tight one tuned to the cheap reads.

Error Handling

Bitcoin Core returns errors in the error object with a numeric code. The standard JSON-RPC codes flag envelope problems — -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params — while Bitcoin's own codes flag domain failures: -5 invalid address/key or not found, -8 invalid parameter, -22 deserialization (bad transaction hex), -25 verify error, -26 transaction rejected by the mempool, and -27 transaction already in the chain. The full table is below. Four habits keep integrations robust: always check the error field before reading result; retry transient failures (timeouts, rate limits) with exponential backoff, but never blindly retry deterministic rejections like -26; log the code and message so failures are diagnosable; and set sensible HTTP timeouts so a slow heavy read fails cleanly instead of hanging.

Common Error Response

1{
2  "result": null,
3  "error": {
4    "code": -5,
5    "message": "No such mempool or blockchain transaction. Use -txindex or provide a block hash to enable blockchain transaction queries."
6  },
7  "id": "therpc"
8}

Bitcoin Core JSON-RPC Error Codes

Technical Questions

• How do I track a transaction? Poll getrawtransaction with verbose true and read its confirmations field — 0 or absent means it's still pending. While it's unconfirmed you can inspect it in the mempool with getmempoolentry to see its fee and how long it's been waiting. Once confirmations climbs, it's in a block.
• Why can't getrawtransaction find an old transaction? Without -txindex, a node only resolves transactions still in the mempool or in blocks it specifically knows to look in, so a historical txid lookup fails unless you also pass the blockhash. TheRPC runs Bitcoin with transaction indexing on; you can confirm txindex is active and synced via getindexinfo.
• How do I handle a chain reorganization? Don't treat shallow confirmations as final. Wait for several confirmations before considering a payment settled, watch getbestblockhash for an unexpected tip change, and use getchaintips to detect competing branches. A transaction that was confirmed can return to the mempool after a reorg, so re-check confirmations rather than caching "confirmed" permanently.

Transaction Tracking Example

1// Read confirmations for a transaction (verbose getrawtransaction)
2const tx = await rpc('getrawtransaction', [txid, true]);
3if (tx.confirmations && tx.confirmations >= 1) {
4  console.log(`Confirmed in block ${tx.blockhash} with ${tx.confirmations} confirmations`);
5} else {
6  console.log('Still unconfirmed (in mempool)');
7}

Performance

• How do I optimize usage? Batch independent calls into a single JSON-RPC array request, cache immutable data (a confirmed block or transaction never changes, so it's safe to cache indefinitely), and size polling intervals to Bitcoin's ~10-minute block time instead of hammering the tip every second.
• What about high throughput? Reuse HTTP connections (keep-alive) rather than opening a socket per call, queue and pace requests so you stay under your rate limit, watch the X-RateLimit-* response headers to back off before you're throttled, and avoid pulling full verbose mempool dumps (getrawmempool true) on a loop — they're large and change constantly.

Network Specific

• How do I switch between mainnet and testnet? Point at the matching endpoint URL — the request format, JSON-RPC envelope, and your API key are identical on both, so only the host changes.
• How do I confirm which network an endpoint serves? Call getblockchaininfo and read the chain field: main for mainnet, test for testnet, plus signet and regtest for the test networks. This is the reliable way to be sure you're not broadcasting a real BTC transaction against testnet or vice versa.
• What unit are amounts in? Bitcoin's native unit is BTC, and 1 BTC = 1e8 satoshis. Most RPC methods report values in BTC (for example the value from gettxout and the feerate from estimatesmartfee), so multiply by 1e8 when you need satoshis. Remember there are no accounts and no nonce — the UTXO model tracks unspent outputs, not address balances.

Development & Integration

• What's the recommended integration approach? Talk raw JSON-RPC over any HTTP client — fetch/axios in JavaScript, requests in Python, net/http in Go. Bitcoin has no dominant high-level SDK, so a plain POST of the 1.0 envelope works everywhere; thin clients like python-bitcoinrpc are optional conveniences, not requirements.
• How should I test my integration? Start on testnet with a test API key so mistakes cost nothing, wire up error handling for the codes above before going live, sanity-check connectivity with a getblockchaininfo call (confirm the chain field matches the network you expect), and monitor latency and rate-limit headers as you scale. Move to mainnet only once the testnet path is solid.