{"id":13517991,"url":"https://github.com/ruimarinho/bitcoin-core","last_synced_at":"2025-05-15T15:00:18.163Z","repository":{"id":41002775,"uuid":"49685674","full_name":"ruimarinho/bitcoin-core","owner":"ruimarinho","description":"A modern Bitcoin Core REST and RPC client.","archived":false,"fork":false,"pushed_at":"2025-01-23T15:13:25.000Z","size":232,"stargazers_count":494,"open_issues_count":22,"forks_count":194,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-07T06:40:58.507Z","etag":null,"topics":["bitcoin","client","request","rest","rpc"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruimarinho.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-01-15T00:58:33.000Z","updated_at":"2025-05-02T11:02:41.000Z","dependencies_parsed_at":"2022-08-02T18:00:21.582Z","dependency_job_id":"193d4cfc-3c69-4e1a-8307-c86d018be97e","html_url":"https://github.com/ruimarinho/bitcoin-core","commit_stats":{"total_commits":90,"total_committers":17,"mean_commits":5.294117647058823,"dds":0.6777777777777778,"last_synced_commit":"e5cf9120db5b09d4e98c4cfb3b7b3e60bc4ceb99"},"previous_names":["seegno/bitcoin-core"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fbitcoin-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fbitcoin-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fbitcoin-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fbitcoin-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruimarinho","download_url":"https://codeload.github.com/ruimarinho/bitcoin-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254364264,"owners_count":22058877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","client","request","rest","rpc"],"created_at":"2024-08-01T05:01:39.478Z","updated_at":"2025-05-15T15:00:18.027Z","avatar_url":"https://github.com/ruimarinho.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# bitcoin-core\nA modern Bitcoin Core REST and RPC client to execute administrative tasks, [multiwallet](https://bitcoincore.org/en/2017/09/01/release-0.15.0/#multiwallet) operations and queries about network and the blockchain.\n\n## Status\n[![npm version][npm-image]][npm-url] [![build status][travis-image]][travis-url]\n\n## Installation\n\nInstall the package via `yarn`:\n\n```sh\nyarn add bitcoin-core\n```\n\nor via `npm`:\n\nInstall the package via `npm`:\n\n```sh\nnpm install bitcoin-core --save\n```\n\n## Usage\n### Client(...args)\n#### Arguments\n1. `[headers={}]` _(object)_: Custom request headers.\n2. `[host=http://localhost:8332]` _(string)_: The host to connect to.\n3. `[logger=debugnyan('bitcoin-core')]` _(Function)_: Custom logger (by default, `debugnyan`).\n4. `[password]` _(string)_: The RPC server user password.\n5. `[timeout=30000]` _(number)_: How long until the request times out (ms).\n6. `[username]` _(number)_: The RPC server user name.\n7. `[version]` _(string)_: Which version to check methods for ([read more](#versionchecking)).\n8. `[wallet]` _(string)_: Which wallet to manage ([read more](#multiwallet)).\n\n### Examples\n\n#### Using promises to process the response\n\n```js\nclient.getInfo().then((help) =\u003e console.log(help));\n```\n\n#### Using callbacks to process the response\n\nCallback support was removed. Since every method returns a `Promise`, [callbackify()](https://nodejs.org/api/util.html#util_util_callbackify_original) (`\u003enode@v8.2.0`) can be used, or for older `node` versions you can use the npm package [callbackify](https://www.npmjs.com/package/callbackify).\n\n```js\nutil.callbackify(() =\u003e client.getInfo())((error, help) =\u003e console.log(help));\n```\n\n## Named parameters\n\nSince version v0.14.0, it is possible to send commands via the JSON-RPC interface using named parameters instead of positional ones. This comes with the advantage of making the order of arguments irrelevant. It also helps improving the readability of certain function calls when leaving out arguments for their default value.\n\nYou **must** provide a version in the client arguments to enable named parameters.\n\n```js\nconst client = new Client({ version: '0.15.1' });\n```\nFor instance, take the `getBalance()` call written using positional arguments:\n```js\nconst balance = await new Client().getBalance('*', 0);\n```\n\nIt is functionally equivalent to using the named arguments `account` and `minconf`, leaving out `include_watchonly` (defaults to `false`):\n\n```js\nconst balance = await new Client({ version: '0.15.1' }).getBalance({\n  account: '*',\n  minconf: 0\n});\n```\n\nThis feature is available to all JSON-RPC methods that accept arguments.\n\n### Floating point number precision in JavaScript\n\nDue to [JavaScript's limited floating point precision](http://floating-point-gui.de/), all big numbers (numbers with more than 15 significant digits) are returned as strings to prevent precision loss. This includes both the RPC and REST APIs.\n\n## Multiwallet\n\nSince Bitcoin Core v0.15.0, it's possible to manage multiple wallets using a single daemon. This enables use-cases such as managing a personal and a business wallet simultaneously in order to simplify accounting and accidental misuse of funds.\n\nHistorically, the _accounts_ feature was supposed to offer similar functionality, but it has now been replaced by this more powerful feature.\n\nTo enable Multi Wallet support, start by specifying the number of added wallets you would like to have available and loaded on the server using the `-wallet` argument multiple times. For convenience, the bitcoin-core docker image will be used, but it's not a requirement:\n\n```sh\ndocker run --rm -it -p 18332:18332 ruimarinho/bitcoin-core:0.15-alpine \\\n  -printtoconsole \\\n  -server \\\n  -rpcauth='foo:e1fcea9fb59df8b0388f251984fe85$26431097d48c5b6047df8dee64f387f63835c01a2a463728ad75087d0133b8e6' \\\n  -regtest \\\n  -wallet=wallet1.dat \\\n  -wallet=wallet2.dat \\\n  -rpcallowip=172.17.0.0/16\n```\n\nNotice the `rpcauth` hash which has been previously generated for the password `j1DuzF7QRUp-iSXjgewO9T_WT1Qgrtz_XWOHCMn_O-Y=`. Do **not** copy and paste this hash **ever** beyond this exercise.\n\nInstantiate a client for each wallet and execute commands targeted at each wallet:\n\n```js\nconst Client = require('bitcoin-core');\n\nconst wallet1 = new Client({\n  network: 'regtest',\n  wallet: 'wallet1.dat',\n  username: 'foo',\n  password: 'j1DuzF7QRUp-iSXjgewO9T_WT1Qgrtz_XWOHCMn_O-Y='\n});\n\nconst wallet2 = new Client({\n  network: 'regtest',\n  wallet: 'wallet2.dat',\n  username: 'foo',\n  password: 'j1DuzF7QRUp-iSXjgewO9T_WT1Qgrtz_XWOHCMn_O-Y='\n});\n\n(async function() {\n  await wallet2.generate(100);\n\n  console.log(await wallet1.getBalance());\n  // =\u003e 0\n  console.log(await wallet2.getBalance());\n  // =\u003e 50\n}());\n```\n\n\n### Version Checking\nBy default, all methods are exposed on the client independently of the version it is connecting to. This is the most flexible option as defining methods for unavailable RPC calls does not cause any harm and the library is capable of handling a `Method not found` response error correctly.\n\n```js\nconst client = new Client();\n\nclient.command('foobar');\n// =\u003e RpcError: -32601 Method not found\n```\n\nHowever, if you prefer to be on the safe side, you can enable strict version checking. This will validate all method calls before executing the actual RPC request:\n\n```js\nconst client = new Client({ version: '0.12.0' });\n\nclient.getHashesPerSec();\n// =\u003e Method \"gethashespersec\" is not supported by version \"0.12.0\"\n```\n\nIf you want to enable strict version checking for the bleeding edge version, you may set a very high version number to exclude recently deprecated calls:\n\n```js\nconst client = new Client({ version: `${Number.MAX_SAFE_INTEGER}.0.0` });\n\nclient.getWork();\n// =\u003e Throws 'Method \"getwork\" is not supported by version \"9007199254740991.0.0\"'.\n```\n\nTo avoid potential issues with prototype references, all methods are still enumerable on the library client prototype.\n\n### RPC\nStart the `bitcoind` with the RPC server enabled and optionally configure a username and password:\n\n```sh\ndocker run --rm -it ruimarinho/bitcoin-core:0.12-alpine -printtoconsole -rpcuser=foo -rpcpassword=bar -server\n```\n\nThese configuration values may also be set on the `bitcoin.conf` file of your platform installation.\n\nThe RPC services binds to the localhost loopback network interface, so use `rpcbind` to change where to bind to and `rpcallowip` to whitelist source IP access.\n\n#### Methods\nAll RPC [methods](src/methods.js) are exposed on the client interface as a camelcase'd version of those available on `bitcoind` (see examples below).\n\nFor a more complete reference about which methods are available, check the [RPC documentation](https://bitcoin.org/en/developer-reference#remote-procedure-calls-rpcs) on the [Bitcoin Core Developer Reference website](https://bitcoin.org/en/developer-reference).\n\n##### Examples\n\n```js\nclient.createRawTransaction([{ txid: '1eb590cd06127f78bf38ab4140c4cdce56ad9eb8886999eb898ddf4d3b28a91d', vout: 0 }], { 'mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe': 0.13 });\nclient.sendMany('test1', { mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN: 0.1, mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe: 0.2 }, 6, 'Example Transaction');\nclient.sendToAddress('mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6', 0.1,  'sendtoaddress example', 'Nemo From Example.com');\n```\n\n#### Batch requests\nBatch requests are support by passing an array to the `command` method with a `method` and optionally, `parameters`. The return value will be an array with all the responses.\n\n```js\nconst batch = [\n  { method: 'getnewaddress', parameters: [] },\n  { method: 'getnewaddress', parameters: [] }\n]\n\nnew Client().command(batch).then((responses) =\u003e console.log(responses)));\n\n// Or, using ES2015 destructuring.\nnew Client().command(batch).then(([firstAddress, secondAddress]) =\u003e console.log(firstAddress, secondAddress)));\n```\n\nNote that batched requests will only throw an error if the batch request itself cannot be processed. However, each individual response may contain an error akin to an individual request.\n\n```js\nconst batch = [\n  { method: 'foobar', parameters: [] },\n  { method: 'getnewaddress', parameters: [] }\n]\n\nnew Client().command(batch).then(([address, error]) =\u003e console.log(address, error)));\n// =\u003e `mkteeBFmGkraJaWN5WzqHCjmbQWVrPo5X3, { [RpcError: Method not found] message: 'Method not found', name: 'RpcError', code: -32601 }`.\n```\n\n### REST\nSupport for the REST interface is still **experimental** and the API is still subject to change. These endpoints are also **unauthenticated** so [there are certain risks which you should be aware](https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md#risks), specifically of leaking sensitive data of the node if not correctly protected.\n\nError handling is still fragile so avoid passing user input.\n\nStart the `bitcoind` with the REST server enabled:\n\n```sh\ndocker run --rm -it ruimarinho/bitcoin-core:0.12-alpine -printtoconsole -server -rest\n```\n\nThese configuration values may also be set on the `bitcoin.conf` file of your platform installation. Use `txindex=1` if you'd like to enable full transaction query support (note: this will take a considerable amount of time on the first run).\n\n### Methods\n\nUnlike RPC methods which are automatically exposed on the client, REST ones are handled individually as each method has its own specificity. The following methods are supported:\n\n- [getBlockByHash](#getblockbyhashhash-options)\n- [getBlockHeadersByHash](#getblockheadersbyhashhash-count-options)\n- [getBlockchainInformation](#getblockchaininformation)\n- [getMemoryPoolContent](#getmemorypoolcontent)\n- [getMemoryPoolInformation](#getmemorypoolinformation)\n- [getTransactionByHash](#gettransactionbyhashhash-options)\n- [getUnspentTransactionOutputs](#getunspenttransactionoutputsoutpoints-options)\n\n#### getBlockByHash(hash, [options])\nGiven a block hash, returns a block, in binary, hex-encoded binary or JSON formats.\n\n##### Arguments\n1. `hash` _(string)_: The block hash.\n2. `[options]` _(Object)_: The options object.\n3. `[options.extension=json]` _(string)_: Return in binary (`bin`), hex-encoded binary (`hex`) or JSON (`json`) format.\n\n##### Example\n\n```js\nclient.getBlockByHash('0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206', { extension: 'json' });\n```\n\n#### getBlockHeadersByHash(hash, count, [options])\nGiven a block hash, returns amount of block headers in upward direction.\n\n##### Arguments\n1. `hash` _(string)_: The block hash.\n2. `count` _(number)_: The number of blocks to count in upward direction.\n3. `[options]` _(Object)_: The options object.\n4. `[options.extension=json]` _(string)_: Return in binary (`bin`), hex-encoded binary (`hex`) or JSON (`json`) format.\n\n##### Example\n\n```js\nclient.getBlockHeadersByHash('0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206', 1, { extension: 'json' });\n```\n\n#### getBlockchainInformation()\nReturns various state info regarding block chain processing.\n\n##### Example\n\n```js\nclient.getBlockchainInformation();\n```\n\n#### getMemoryPoolContent()\nReturns transactions in the transaction memory pool.\n\n##### Example\n\n```js\nclient.getMemoryPoolContent();\n```\n\n#### getMemoryPoolInformation()\nReturns various information about the transaction memory pool. Only supports JSON as output format.\n- size: the number of transactions in the transaction memory pool.\n- bytes: size of the transaction memory pool in bytes.\n- usage: total transaction memory pool memory usage.\n\n##### Example\n\n```js\nclient.getMemoryPoolInformation();\n```\n\n#### getTransactionByHash(hash, [options])\nGiven a transaction hash, returns a transaction in binary, hex-encoded binary, or JSON formats.\n\n#### Arguments\n1. `hash` _(string)_: The transaction hash.\n2. `[options]` _(Object)_: The options object.\n3. `[options.summary=false]` _(boolean)_: Whether to return just the transaction hash, thus saving memory.\n4. `[options.extension=json]` _(string)_: Return in binary (`bin`), hex-encoded binary (`hex`) or JSON (`json`) format.\n\n##### Example\n\n```js\nclient.getTransactionByHash('b4dd08f32be15d96b7166fd77afd18aece7480f72af6c9c7f9c5cbeb01e686fe', { extension: 'json', summary: false });\n```\n\n#### getUnspentTransactionOutputs(outpoints, [options])\nQuery unspent transaction outputs (UTXO) for a given set of outpoints. See [BIP64](https://github.com/bitcoin/bips/blob/master/bip-0064.mediawiki) for input and output serialisation.\n\n#### Arguments\n1. `outpoints` _(array\\\u003cObject\\\u003e|Object)_: The outpoint to query in the format `{ id: '\u003ctxid\u003e', index: '\u003cindex\u003e' }`.\n2. `[options]` _(Object)_: The options object.\n3. `[options.extension=json]` _(string)_: Return in binary (`bin`), hex-encoded binary (`hex`) or JSON (`json`) format.\n\n##### Example\n\n```js\nclient.getUnspentTransactionOutputs([{\n  id: '0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206',\n  index: 0\n}, {\n  id: '0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206',\n  index: 1\n}], { extension: 'json' })\n```\n\n#### Connecting via SSL\nDeprecated since release 0.5.0.\n\n## Logging\n\nBy default, all requests made with `bitcoin-core` are logged using [uphold/debugnyan](https://github.com/uphold/debugnyan) with `bitcoin-core` as the logging namespace.\n\nPlease note that all sensitive data is obfuscated before calling the logger.\n\n#### Example\n\nExample output defining the environment variable `DEBUG=bitcoin-core`:\n\n```javascript\nconst client = new Client();\n\nclient.getTransactionByHash('b4dd08f32be15d96b7166fd77afd18aece7480f72af6c9c7f9c5cbeb01e686fe');\n\n// {\n//   \"name\": \"bitcoin-core\",\n//   \"hostname\": \"localhost\",\n//   \"pid\": 57908,\n//   \"level\": 20,\n//   \"request\": {\n//     \"headers\": {\n//       \"host\": \"localhost:8332\",\n//       \"accept\": \"application/json\"\n//     },\n//     \"id\": \"82cea4e5-2c85-4284-b9ec-e5876c84e67c\",\n//     \"method\": \"GET\",\n//     \"type\": \"request\",\n//     \"uri\": \"http://localhost:8332/rest/tx/b4dd08f32be15d96b7166fd77afd18aece7480f72af6c9c7f9c5cbeb01e686fe.json\"\n//   },\n//   \"msg\": \"Making request 82cea4e5-2c85-4284-b9ec-e5876c84e67c to GET http://localhost:8332/rest/tx/b4dd08f32be15d96b7166fd77afd18aece7480f72af6c9c7f9c5cbeb01e686fe.json\",\n//   \"time\": \"2017-02-07T14:40:35.020Z\",\n//   \"v\": 0\n// }\n```\n\n### Custom logger\n\nA custom logger can be passed via the `logger` option and it should implement [bunyan's log levels](https://github.com/trentm/node-bunyan#levels).\n\n## Tests\nCurrently the test suite is tailored for Docker (including `docker-compose`) due to the multitude of different `bitcoind` configurations that are required in order to get the test suite passing.\n\nTo test using a local installation of `node.js` but with dependencies (e.g. `bitcoind`) running inside Docker:\n\n```sh\nnpm run dependencies\nnpm test\n```\n\nTo test using Docker exclusively (similarly to what is done in Travis CI):\n\n```sh\nnpm run testdocker\n```\n\n## Release\n\n```sh\nnpm version [\u003cnewversion\u003e | major | minor | patch] -m \"Release %s\"\n```\n\n## License\nMIT\n\n[npm-image]: https://img.shields.io/npm/v/bitcoin-core.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/bitcoin-core\n[travis-image]: https://img.shields.io/travis/ruimarinho/bitcoin-core.svg?style=flat-square\n[travis-url]: https://travis-ci.org/ruimarinho/bitcoin-core\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruimarinho%2Fbitcoin-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruimarinho%2Fbitcoin-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruimarinho%2Fbitcoin-core/lists"}