Bitcoin Explorer
A bitcoin explorer library that utilizes multiple data sources at once.
| Branch | Build | Unit Tests |
|---|---|---|
| master |  |
 |
| development |  |
 |
Table of Contents
Prerequisites
Features
- Thread-safe.
- Rate-limit abidance.
- Rate-limit mitigation.
- Multiple data sources.
Install with Maven
Replace {version} with the latest version indicated above.
<dependency>
<groupId>io.github.bitscorpio</groupId>
<artifactId>bitcoin-explorer</artifactId>
<version>{version}</version>
</dependency>
Supported Data Sources
| Provider | API Documentation |
|---|---|
| Blockchain | Blockchain Data API |
| Blockcypher | Blockcypher API |
Usage
1. Specific data source (Default rate-limit avoider)
All data sources come with no-args constructor that use default settings in abidance with the corresponding rate-limits mentioned in their API documentations.
BTCExplorer explorer = new BlockchainBTCExplorer();
BTCAddress address = explorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
BTCTransaction transaction = explorer.getTransaction("4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b");
2. Specific data source (Custom rate-limit avoider)
It is also possible to customize the rate-limit avoidance behaviour by using our own RateLimitAvoider instance.
// Minimum time duration between two API requests
Duration timeBetweenCalls = Duration.ofSeconds(5);
// Duration to sleep before checking if the minimum duration has passed
Duration retrySleepDuration = Duration.ofMillis(200);
// Create our RateLimitAvoider instance
RateLimitAvoider rateLimitAvoider = new RateLimitAvoider(timeBetweenCalls,retrySleepDuration);
// Use the custom RateLimitAvoider in our preferred BTCExplorer and continue as usual
BTCExplorer explorer = new BlockcypherBTCExplorer(rateLimitAvoider);
BTCAddress address = explorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
BTCTransaction transaction = explorer.getTransaction("4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b");
3. Multiple data sources
Now to the best part, we can chain multiple data sources together so that when one is being throttled by its own instance of RateLimitAvoider the other one gets used instead; effectively reducing the time required to wait in order to avoid getting rate-limited.
// Create a MultiBTCExplorer that utilizes all available data sources
BTCExplorer explorer = MultiBTCExplorer.createDefault();
// Create a MultiBTCExplorer that utilizes specific data sources (Using the varargs constructor)
BTCExplorer explorer = new MultiSourceBTCExplorer(new BlockchainBTCExplorer(), new BlockcypherBTCExplorer());
Using the MultiBTCExplorer is simillar to the previous examples.
// The following operations will get performed quicker
address = explorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
BTCTransaction transaction = explorer.getTransaction("4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b");
Warning
Since every BTCExplorer instance has its own RateLimitAvoider, using multiple instances of the same implementation (Ex: BlockchainBTCAddress) will lead to getting rate-limited. Always make sure that only one instance of BTCExplorer being used across the application.
There is a special case for MultiBTCExplorer where the prior warning does not apply; since MultiBTCExplorer itself does not use a specific data source and instead utilizes several data sources, the following code will run just fine.
BTCExplorer blockchainBTCExplorer = new BlockchainBTCExplorer();
BTCExplorer blockcypherBTCExplorer = new BlockcypherBTCExplorer();
// We are utilizing an already-existing instance of each implementation
BTCExplorer multiBTCExplorer = new MultiBTCExplorer(blockchainBTCExplorer, blockcypherBTCExplorer);
BTCAddress address1 = blockchainBTCExplorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
BTCAddress address2 = blockcypherBTCExplorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
// This line will not immediately send API requests
BTCAddress address3 = multiBTCExplorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
However, the following code is NOT SAFE and will lead to getting rate-limited.
BTCExplorer blockchainBTCExplorer = new BlockchainBTCExplorer();
BTCExplorer blockcypherBTCExplorer = new BlockcypherBTCExplorer();
// This will internally create different instances than the ones we declared above
BTCExplorer multiBTCExplorer = MultiBTCExplorer.createDefault();
BTCAddress address1 = blockchainBTCExplorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
BTCAddress address2 = blockcypherBTCExplorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
// This line will immediately send API requests
BTCAddress address3 = multiBTCExplorer.getAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
3 Dec 11, 2022
4 Oct 4, 2022
20 Nov 29, 2022
8 Dec 31, 2021
188 Dec 17, 2022
20 Dec 28, 2022
5 Aug 27, 2022
5 Nov 28, 2022
6 Nov 2, 2022