API Overview

Architecture

TheRPC exposes the native Bitcoin Core JSON-RPC interface — the same RPC that bitcoind speaks — over plain HTTP POST. You reach it at https://bitcoin.therpc.io/YOUR_API_KEY. Four traits define the surface: a single standard HTTPS endpoint (one URL, no per-method routes); API-key authentication in place of the node's HTTP Basic credentials; the JSON-RPC request/response format Bitcoin Core has used since its earliest releases; and positional parameters passed as a JSON array — arguments are ordered, not named. There is no chain ID, no account or contract model, and no signing on the server: TheRPC reads from and broadcasts to the Bitcoin network on your behalf.

Communication Protocol

Bitcoin Core RPC is strictly request/response over HTTP POST: you send one JSON body, you get one JSON body back. There is no WebSocket and no subscription RPC — Bitcoin Core has never offered eth_subscribe-style push notifications, so TheRPC does not either. To track the chain in real time you poll the tip: call getblockcount or getbestblockhash on a sensible interval (blocks arrive roughly every 10 minutes under proof-of-work, so a few seconds between polls is plenty) and act when the height or hash changes. For ready-to-run request examples, see the HTTP / curl guide linked at the bottom of this page.

HTTP Endpoint

https://bitcoin.therpc.io/YOUR_API_KEY

JSON-RPC Format

Bitcoin Core uses the legacy JSON-RPC 1.0 envelope rather than the 2.0 form common on other chains. Each request carries four fields: jsonrpc set to the string "1.0"; id, a client-chosen string used to match the response (TheRPC examples use "therpc"); method, the RPC name such as getblock; and params, a positional JSON array. Params are positional — the order of the array elements is the order of the method's arguments, so ["<hash>", 1] means "this block hash, verbosity 1". There are no named-object params here; omit trailing optional arguments rather than passing keys.

Request Structure

1{
2  "jsonrpc": "1.0",
3  "id": "therpc",
4  "method": "getblock",
5  "params": [
6    "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
7    1
8  ]
9}

Response Format

Every response shares the same three-field shape: result, error, and id. The id echoes the value you sent so you can pair responses with requests. On success, error is null and result holds the value — a number for getblockcount, an object for getblock, a hex string for getrawtransaction. On failure, result is null and error is an object with a numeric code and a human-readable message. Always branch on error before reading result; a non-null error means result carries nothing useful.

Success Response

1{
2  "result": 880123,
3  "error": null,
4  "id": "therpc"
5}

Error Response

1{
2  "result": null,
3  "error": {
4    "code": -5,
5    "message": "Block not found"
6  },
7  "id": "therpc"
8}

Authentication

Every request to https://bitcoin.therpc.io/YOUR_API_KEY must carry your TheRPC API key. You can place it directly in the URL path (shown above) or send it as a Bearer token in the Authorization header — either works, and you only need one. The full Authentication guide covers obtaining a key from your dashboard, header placement, environment-variable setup, and what an auth-failure response looks like.

Authorization Header

1Authorization: Bearer YOUR_API_KEY

Method Categories

The supported methods fall into five groups. Block and chain reads cover the ledger itself: getblockchaininfo for overall state and sync progress, getblockcount and getbestblockhash for the tip, getblockhash to map a height to a hash, getblock to read a block, and gettxout to read a single unspent output from the UTXO set. Mempool methods inspect pending transactions: getmempoolinfo for size and minimum relay fee, getrawmempool for the pending set, and getmempoolentry for one entry's fees and ancestors. Raw transaction methods handle individual transactions: getrawtransaction to fetch and optionally decode by txid, sendrawtransaction to broadcast a signed transaction, and decoderawtransaction to parse hex without broadcasting. Network and mining read methods report node and network conditions: getnetworkinfo, getmininginfo, and getnetworkhashps. Utility methods cover fees and addresses: estimatesmartfee for a fee rate, validateaddress to check an address and return its scriptPubKey, and deriveaddresses for descriptor-based derivation. Wallet methods and node-admin methods are deliberately not exposed — they act on a single node's private wallet or configuration and do not belong on a shared, multi-tenant endpoint.

Error Handling

Errors come back in the error object with a numeric code. The standard JSON-RPC codes signal envelope problems: -32700 parse error (malformed JSON), -32600 invalid request, -32601 method not found (typo'd or unsupported method), and -32602 invalid params (wrong number or shape of arguments). Bitcoin Core layers its own codes on top for domain failures: -5 not found (no such block, transaction, or address), -8 invalid parameter, -22 deserialization failed (bad transaction hex), -25 verify error, -26 transaction rejected by the mempool (for example a fee below the minimum relay rate), and -27 transaction already in the chain. The FAQ covers each code in a table along with retry and backoff strategies.

Implementation Examples

• JavaScript / TypeScript — POST the JSON-RPC 1.0 body with axios, node-fetch, or the built-in fetch; see the Quick Start for a reusable rpc() helper.
• Python — use requests for raw calls, or the thin python-bitcoinrpc client that puts the API key in the URL path.
• Go — build the request with net/http and encoding/json; no Bitcoin-specific SDK is required.
• HTTP / curl — the curl examples throughout these docs send the exact request body Bitcoin Core expects against https://bitcoin.therpc.io/YOUR_API_KEY.