# Bitcoin Network Tools
A Python wrapper for https://bitnodes.io/api/.
This library provides tools for analyzing and monitoring Bitcoin network nodes. It supports both authenticated and unauthenticated requests, allowing flexibility based on your usage needs.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Initialization](#initialization)
- [Example Requests](#example-requests)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
# Features
- Easy-to-use Python wrapper for the Bitnodes API
- Analyze and monitor Bitcoin network nodes with minimal setup
- Support for authenticated requests using an API key
- Includes node status, latency, leaderboard, and propagation statistics
# Installation
### Install from PyPI
```bash
pip install bitcoin-network-tools
```
### Install from Source
Clone the repository and install:
```bash
git clone https://github.com/your-repo/bitcoin-network-tools.git
cd bitcoin-network-tools
pip install .
```
## Usage
### Initialization
This library supports both authenticated and unauthenticated requests. To authenticate, set `BITNODES_PUBLIC_KEY` and `BITNODES_PRIVATE_KEY` as environment variables or pass them directly during initialization.
#### Example Initialization
```python
from bitcoin_network_tools.bitnodes_api import BitnodesAPI
# Unauthenticated
bn = BitnodesAPI()
# Authenticated
bn = BitnodesAPI(public_api_key="your_public_key", private_key_path="path_to_private_key")
```
Keys can also be configured after initialization:
```python
In [3]: bn.set_public_api_key("examplekey")
Out[3]: True
In [4]: bn.set_private_key_path("private_key.txt")
Out[4]: True
```
Note: The private key is used ephemerally and **never** stored.
API keys are available at https://bitnodes.io/api/.
Snapshot data is retained on Bitnodes servers for up to 60 days.
### API Key Considerations
- Without an API key: Limited to **50 requests per 24 hours**.
- With an API key: Up to **200,000 requests per 24 hours**.
## Example Requests
### Fetch Snapshots
Retrieves a list of snapshots from the server, showing details such as timestamp, total nodes, and block height.
```python
In [3]: bn.get_snapshots(limit=5)
Out[3]:
{'count': 8612,
'next': 'https://bitnodes.io/api/v1/snapshots/?limit=5&page=2',
'previous': None,
'results': [{'url': 'https://bitnodes.io/api/v1/snapshots/1735849765/',
'timestamp': 1735849765,
'total_nodes': 20833,
'latest_height': 877541},
{'url': 'https://bitnodes.io/api/v1/snapshots/1735849164/',
'timestamp': 1735849164,
'total_nodes': 20816,
'latest_height': 877541},
{'url': 'https://bitnodes.io/api/v1/snapshots/1735848574/',
'timestamp': 1735848574,
'total_nodes': 20265,
'latest_height': 877541},
{'url': 'https://bitnodes.io/api/v1/snapshots/1735847963/',
'timestamp': 1735847963,
'total_nodes': 20293,
'latest_height': 877541},
{'url': 'https://bitnodes.io/api/v1/snapshots/1735847372/',
'timestamp': 1735847372,
'total_nodes': 20298,
'latest_height': 877538}]}
```
### Retrieve Node Status
Get the status of a specific node:
```python
In [4]: bn.get_node_status(address="31.47.202.112", port=8333)
Out[4]:
{'address': '31.47.202.112',
'status': 'UP',
'data': [70016,
'/Satoshi:27.1.0/',
1734410285,
3081,
877256,
'btc.dohmen.net',
'Gothenburg',
'SE',
57.7065,
11.967,
'Europe/Stockholm',
'AS34385',
'Tripnet AB'],
'mbps': '38.850493'}
```
# Testing
Tests can be run with BITNODES_PUBLIC_KEY and BITNODES_PRIVATE_KEY environment variables set and
```
pytest
```
# Contributing
Contributions are welcome! Here's how you can contribute:
1. Report bugs or request features by opening an issue.
2. Fork the repository and create a pull request for code contributions.
3. Expand the documentation or propose new analysis features.
# License
Apache v2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "bitcoin-network-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "bitcoin, blockchain, cryptocurrency, network analysis, bitnodes, api, tools, python, development, crypto, financial technology, decentralized networks",
"author": null,
"author_email": "\"Zachary A. Kraehling\" <zak@zakkraehling.net>",
"download_url": "https://files.pythonhosted.org/packages/6b/18/5aa1f989a180af6426edbeed7bae5e12b1f50de8b28f1a3d1f9a361fad0f/bitcoin_network_tools-0.0.1.tar.gz",
"platform": null,
"description": "\n# Bitcoin Network Tools\n\nA Python wrapper for https://bitnodes.io/api/. \n\nThis library provides tools for analyzing and monitoring Bitcoin network nodes. It supports both authenticated and unauthenticated requests, allowing flexibility based on your usage needs.\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Initialization](#initialization)\n - [Example Requests](#example-requests)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n\n# Features\n\n- Easy-to-use Python wrapper for the Bitnodes API\n- Analyze and monitor Bitcoin network nodes with minimal setup\n- Support for authenticated requests using an API key\n- Includes node status, latency, leaderboard, and propagation statistics\n\n\n# Installation \n\n### Install from PyPI\n```bash\npip install bitcoin-network-tools\n```\n\n### Install from Source\n\nClone the repository and install:\n```bash\ngit clone https://github.com/your-repo/bitcoin-network-tools.git\ncd bitcoin-network-tools\npip install .\n```\n\n## Usage\n\n### Initialization\n\nThis library supports both authenticated and unauthenticated requests. To authenticate, set `BITNODES_PUBLIC_KEY` and `BITNODES_PRIVATE_KEY` as environment variables or pass them directly during initialization.\n\n#### Example Initialization\n\n```python\nfrom bitcoin_network_tools.bitnodes_api import BitnodesAPI\n\n# Unauthenticated\nbn = BitnodesAPI()\n\n# Authenticated\nbn = BitnodesAPI(public_api_key=\"your_public_key\", private_key_path=\"path_to_private_key\")\n```\n\nKeys can also be configured after initialization:\n\n```python\nIn [3]: bn.set_public_api_key(\"examplekey\")\nOut[3]: True\n\nIn [4]: bn.set_private_key_path(\"private_key.txt\") \nOut[4]: True\n```\n\nNote: The private key is used ephemerally and **never** stored.\n\nAPI keys are available at https://bitnodes.io/api/. \nSnapshot data is retained on Bitnodes servers for up to 60 days.\n\n### API Key Considerations\n- Without an API key: Limited to **50 requests per 24 hours**.\n- With an API key: Up to **200,000 requests per 24 hours**.\n\n## Example Requests\n### Fetch Snapshots\nRetrieves a list of snapshots from the server, showing details such as timestamp, total nodes, and block height.\n\n\n```python\nIn [3]: bn.get_snapshots(limit=5)\nOut[3]: \n{'count': 8612,\n 'next': 'https://bitnodes.io/api/v1/snapshots/?limit=5&page=2',\n 'previous': None,\n 'results': [{'url': 'https://bitnodes.io/api/v1/snapshots/1735849765/',\n 'timestamp': 1735849765,\n 'total_nodes': 20833,\n 'latest_height': 877541},\n {'url': 'https://bitnodes.io/api/v1/snapshots/1735849164/',\n 'timestamp': 1735849164,\n 'total_nodes': 20816,\n 'latest_height': 877541},\n {'url': 'https://bitnodes.io/api/v1/snapshots/1735848574/',\n 'timestamp': 1735848574,\n 'total_nodes': 20265,\n 'latest_height': 877541},\n {'url': 'https://bitnodes.io/api/v1/snapshots/1735847963/',\n 'timestamp': 1735847963,\n 'total_nodes': 20293,\n 'latest_height': 877541},\n {'url': 'https://bitnodes.io/api/v1/snapshots/1735847372/',\n 'timestamp': 1735847372,\n 'total_nodes': 20298,\n 'latest_height': 877538}]}\n```\n\n### Retrieve Node Status\nGet the status of a specific node:\n\n```python\nIn [4]: bn.get_node_status(address=\"31.47.202.112\", port=8333)\nOut[4]:\n{'address': '31.47.202.112',\n'status': 'UP',\n'data': [70016,\n'/Satoshi:27.1.0/',\n1734410285,\n3081,\n877256,\n'btc.dohmen.net',\n'Gothenburg',\n'SE',\n57.7065,\n11.967,\n'Europe/Stockholm',\n'AS34385',\n'Tripnet AB'],\n'mbps': '38.850493'}\n```\n\n# Testing\n\nTests can be run with BITNODES_PUBLIC_KEY and BITNODES_PRIVATE_KEY environment variables set and \n\n```\npytest\n```\n\n# Contributing \n\nContributions are welcome! Here's how you can contribute:\n1. Report bugs or request features by opening an issue.\n2. Fork the repository and create a pull request for code contributions.\n3. Expand the documentation or propose new analysis features.\n\n# License \n\nApache v2.0\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "A wrapper for the Bitnodes API.",
"version": "0.0.1",
"project_urls": {
"homepage": "https://github.com/7astro7/bitcoin-network-tools",
"issues": "https://github.com/7astro7/bitcoin-network-tools/issues",
"repository": "https://github.com/7astro7/bitcoin-network-tools"
},
"split_keywords": [
"bitcoin",
" blockchain",
" cryptocurrency",
" network analysis",
" bitnodes",
" api",
" tools",
" python",
" development",
" crypto",
" financial technology",
" decentralized networks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e5c27a4d35ab887243f8d46411fa3a8ef2cebc5692c8ee265c24ae3853a98d86",
"md5": "fb879f09e62782a6495bfdbd1b41ba09",
"sha256": "120fd01a3dbf94b13f8081a5ff4856956df7371e911038d8dbcc0716bc2aae1c"
},
"downloads": -1,
"filename": "bitcoin_network_tools-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb879f09e62782a6495bfdbd1b41ba09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18535,
"upload_time": "2025-01-03T00:54:18",
"upload_time_iso_8601": "2025-01-03T00:54:18.718315Z",
"url": "https://files.pythonhosted.org/packages/e5/c2/7a4d35ab887243f8d46411fa3a8ef2cebc5692c8ee265c24ae3853a98d86/bitcoin_network_tools-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6b185aa1f989a180af6426edbeed7bae5e12b1f50de8b28f1a3d1f9a361fad0f",
"md5": "05046c6f883f0d92c4ecca023f224a14",
"sha256": "c7102efddfcb9b4f42260a499930a92d63533ff30ed2da267855c033be2d7c6e"
},
"downloads": -1,
"filename": "bitcoin_network_tools-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "05046c6f883f0d92c4ecca023f224a14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 19041,
"upload_time": "2025-01-03T00:54:20",
"upload_time_iso_8601": "2025-01-03T00:54:20.208659Z",
"url": "https://files.pythonhosted.org/packages/6b/18/5aa1f989a180af6426edbeed7bae5e12b1f50de8b28f1a3d1f9a361fad0f/bitcoin_network_tools-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-03 00:54:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "7astro7",
"github_project": "bitcoin-network-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "dnspython",
"specs": [
[
"==",
"2.7.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.3.4"
]
]
},
{
"name": "Requests",
"specs": [
[
"==",
"2.32.3"
]
]
}
],
"lcname": "bitcoin-network-tools"
}
JSON
