{"id":18254701,"url":"https://github.com/bitcoin-sv/spv-wallet-js-client","last_synced_at":"2025-04-04T17:30:45.206Z","repository":{"id":37094190,"uuid":"458217893","full_name":"bitcoin-sv/spv-wallet-js-client","owner":"bitcoin-sv","description":"TypeScript client for interacting with spv-wallet","archived":false,"fork":false,"pushed_at":"2024-10-30T14:16:12.000Z","size":4228,"stargazers_count":24,"open_issues_count":2,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-30T15:24:18.576Z","etag":null,"topics":["bsv","bux","js","npm","spv-wallet","spv-wallet-client","spv-wallet-team","typescript","utxo","xpub"],"latest_commit_sha":null,"homepage":"https://docs.bsvblockchain.org/network-topology/applications/spv-wallet","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitcoin-sv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"BuxOrg","custom":"https://getbux.io/?utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=bux-website\u0026utm_term=bux-website\u0026utm_content=bux-website"}},"created_at":"2022-02-11T14:24:47.000Z","updated_at":"2024-10-30T14:12:34.000Z","dependencies_parsed_at":"2024-03-25T15:14:30.232Z","dependency_job_id":"b3f87419-a14b-49a0-9f57-c09d4961d4a6","html_url":"https://github.com/bitcoin-sv/spv-wallet-js-client","commit_stats":{"total_commits":524,"total_committers":6,"mean_commits":87.33333333333333,"dds":"0.12595419847328249","last_synced_commit":"4f3483855423b96d19e355873f5207a4b899df86"},"previous_names":["bitcoin-sv/spv-wallet-js-client","buxorg/js-buxclient"],"tags_count":39,"template":false,"template_full_name":"jasonsturges/typescript-npm-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fspv-wallet-js-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fspv-wallet-js-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fspv-wallet-js-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fspv-wallet-js-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitcoin-sv","download_url":"https://codeload.github.com/bitcoin-sv/spv-wallet-js-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223150707,"owners_count":17095959,"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":["bsv","bux","js","npm","spv-wallet","spv-wallet-client","spv-wallet-team","typescript","utxo","xpub"],"created_at":"2024-11-05T10:13:18.809Z","updated_at":"2025-04-04T17:30:45.200Z","avatar_url":"https://github.com/bitcoin-sv.png","language":"TypeScript","funding_links":["https://github.com/sponsors/BuxOrg","https://getbux.io/?utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=bux-website\u0026utm_term=bux-website\u0026utm_content=bux-website"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# [SPV Wallet: JS Client](https://www.npmjs.com/package/@bsv/spv-wallet-js-client)\n\n[![last commit](https://img.shields.io/github/last-commit/bitcoin-sv/spv-wallet-js-client.svg?style=flat\u0026v=2)](https://github.com/bitcoin-sv/spv-wallet-js-client/commits/main)\n[![version](https://img.shields.io/github/release-pre/bitcoin-sv/spv-wallet-js-client.svg?style=flat\u0026v=2)](https://github.com/bitcoin-sv/spv-wallet-js-client/releases)\n[![Npm](https://img.shields.io/npm/v/@bsv/spv-wallet-js-client?style=flat\u0026v=2)](https://www.npmjs.com/package/@bsv/spv-wallet-js-client)\n[![license](https://img.shields.io/badge/license-Open%20BSV-brightgreen.svg?style=flat\u0026v=2)](/LICENSE)\n[![Mergify Status](https://img.shields.io/endpoint.svg?url=https://api.mergify.com/v1/badges/bitcoin-sv/spv-wallet-js-client\u0026style=flat\u0026v=2)](https://mergify.io)\n\u003cbr/\u003e\n\u003c/div\u003e\n\n## Table of Contents\n\n- [About](#about)\n- [Installation](#installation)\n- [Client Usage](#client-usage)\n- [Admin Usage](#admin-usage)\n- [Development](#development)\n- [Code Standards](#code-standards)\n- [Contributing](#contributing)\n- [License](#license)\n\n## About\n\n**SPV Wallet: JS Client** is a TypeScript package which acts as a http client to [SPV Wallet](https://github.com/bitcoin-sv/spv-wallet).\nUsing this library, you can build your own solutions that utilize this non-custodial wallet.\n\nFor comprehensive information and guidance, please refer to the [SPV Wallet Documentation](https://docs.bsvblockchain.org/network-topology/applications/spv-wallet).\n\n### Client Features (SPVWalletUserAPI)\n- Managing transactions (draft, send, finalize)\n- Listing and managing UTXOs\n- Managing contacts and paymails\n- Generating and managing access keys\n- Handling merkle roots\n- Managing user xPub information\n\n### Admin Features (SPVWalletAdminAPI) \n- Managing xPubs (create, list)\n- Managing paymails (create, delete, list)\n- Managing contacts (create, update, delete)\n- Viewing transactions and UTXOs\n- Managing webhooks\n- Accessing server statistics\n- Managing system configurations\n\n## Installation\n\nTo use this package in your application, you can add it using `yarn`.\n\n```bash\nyarn add @bsv/spv-wallet-js-client\n```\n\n## Client Usage\n\nThe client API provides standard wallet operations for end users.\n\n```typescript\nimport { SPVWalletUserAPI } from '@bsv/spv-wallet-js-client';\n\nconst spvWalletServerUrl = 'http://localhost:3003';\n\n// Create a new instance of the SPV Wallet user client\nconst userClient = new SPVWalletUserAPI(spvWalletServerUrl, {\n  xPriv: 'xpriv.....',\n});\n\n// Example: Get user balance\nconst userInfo = await userClient.xPub();\nconsole.log('Current balance:', userInfo.currentBalance);\n```\n\n\u003e During creation or usage of the client an exception can be thrown - see [handle-exceptions example](./examples/handle-exceptions.ts) how to handle these situations.\n\u003e Additionally you can check [./src/errors.ts](./src/errors.ts) file where custom errors are defined.\n\n### Client Options\n\nTo make user requests, provide one of:\n- `xPriv` string - Full access to non-admin operations\n- `accessKey` string - Limited access (no transaction finalization/sending)\n- `xPub` string - Read-only access with unsigned requests\n\n```typescript\n// Full access with xPriv\nconst userClient = new SPVWalletUserAPI(spvWalletServerUrl, {\n  xPriv: 'xpriv.....',\n});\n\n// Limited access with accessKey\nconst userClient = new SPVWalletUserAPI(spvWalletServerUrl, {\n  accessKey: 'accesskey.....',\n});\n\n// Read-only access with xPub\nconst userClient = new SPVWalletUserAPI(spvWalletServerUrl, {\n  xPub: 'xpub.....',\n});\n```\n\n## Admin Usage\n\nThe admin API provides administrative operations for managing the SPV Wallet system.\n\n```typescript\nimport { SPVWalletAdminAPI } from '@bsv/spv-wallet-js-client';\n\nconst spvWalletServerUrl = 'http://localhost:3003';\n\n// Create a new instance of the SPV Wallet admin client\nconst adminClient = new SPVWalletAdminAPI(spvWalletServerUrl, 'adminkey.....');\n\n// Example: Get server statistics\nconst stats = await adminClient.stats();\nconsole.log('Server stats:', stats);\n```\n\n### Admin Options\n\nAdmin operations require an admin key string as the second parameter when initializing the client:\n\n```typescript\nconst adminClient = new SPVWalletAdminAPI(spvWalletServerUrl, 'adminkey.....');\n```\n\n### Optional Logger Configuration\n\nBoth client and admin APIs accept an optional logger configuration:\n```typescript\nconst client = new SPVWalletUserAPI(url, options, {\n  level: 'debug' // or 'info', 'warn', 'error', 'disabled'\n});\n```\n\nYou can also provide a custom logger implementing the `Logger` interface.\n\n## Development\n\nThis package is based on [rollup.js](https://rollupjs.org/) which handles configuration, hot-reloading and making a build.\n\nTo run the package for develompent purposes, make sure you've installed all dependencies with `yarn install`, then just run:\n\n```bash\nyarn dev\n```\n\nAfter that, in the `dist` directory, compiled package should appear. Additionally, `rollup` will observe the source files rebuilding the dist if needed (hot-reloading).\n\nYou can test your changes locally, the same way as our examples are run. You can find them in [examples](./examples) directory.\n\n### Build the package\n\nTo build the package use\n\n```bash\nyarn build\n```\n\nSee more scripts in the [package.json](package.json) file or the [makefile](Makefile).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eLibrary Deployment\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nReleases are automatically created when you create a new [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging)!\n\nIf you want to manually make releases, please install GoReleaser:\n\n[goreleaser](https://github.com/goreleaser/goreleaser) for easy binary or library deployment to Github and can be installed:\n\n- **using make:** `make install-releaser`\n- **using brew:** `brew install goreleaser`\n\nThe [.goreleaser.yml](.goreleaser.yml) file is used to configure [goreleaser](https://github.com/goreleaser/goreleaser).\n\n\u003cbr/\u003e\n\n### Automatic Releases on Tag Creation (recommended)\n\nAutomatic releases via [Github Actions](.github/workflows/release.yml) from creating a new tag:\n\n```shell\nmake tag version=1.2.3\n```\n\n\u003cbr/\u003e\n\n### Manual Releases (optional)\n\nUse `make release-snap` to create a snapshot version of the release, and finally `make release` to ship to production (manually).\n\n\u003cbr/\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eMakefile Commands\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nView all `makefile` commands\n\n```shell script\nmake help\n```\n\nList of all current commands:\n\n```text\naudit                         Checks for vulnerabilities in dependencies\nclean                         Remove previous builds and any test cache data\nhelp                          Show this help message\ninstall                       Installs the dependencies for the package\ninstall-all-contributors      Installs all contributors locally\noutdated                      Checks for outdated packages via npm\npublish                       Will publish the version to npm\nrelease                       Full production release (creates release in Github)\nrelease                       Run after releasing - deploy to npm\nrelease-snap                  Test the full release (build binaries)\nrelease-test                  Full production test release (everything except deploy)\nreplace-version               Replaces the version in HTML/JS (pre-deploy)\ntag                           Generate a new tag and push (tag version=0.0.0)\ntag-remove                    Remove a tag if found (tag-remove version=0.0.0)\ntag-update                    Update an existing tag to current commit (tag-update version=0.0.0)\ntest                          Will run unit tests\nupdate-contributors           Regenerates the contributors html/list\n```\n\n\u003c/details\u003e\n\n## Code Standards\n\nPlease read our [code standards document](.github/CODE_STANDARDS.md)\n\n## Contributing\n\nAll kinds of contributions are welcome!\n\u003cbr/\u003e\nTo get started, take a look at [code standards](.github/CODE_STANDARDS.md).\n\u003cbr/\u003e\nView the [contributing guidelines](.github/CODE_STANDARDS.md#3-contributing) and follow the [code of conduct](.github/CODE_OF_CONDUCT.md).\n\n\u003cbr/\u003e\n\n## License\n\n[![License](https://img.shields.io/badge/license-Open%20BSV-brightgreen.svg?style=flat\u0026v=2)](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-sv%2Fspv-wallet-js-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcoin-sv%2Fspv-wallet-js-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-sv%2Fspv-wallet-js-client/lists"}