Java EtherScan API

Etherscan.io Java API implementation.

Library supports EtherScan API for all available Ethereum Networks for etherscan.io

Dependency :rocket:

Gradle

implementation "com.github.goodforgod:java-etherscan-api:3.0.0"

Maven

<dependency>
    <groupId>com.github.goodforgod</groupId>
    <artifactId>java-etherscan-api</artifactId>
    <version>3.0.0</version>
</dependency>

Content

• Ethereum Networks
• Custom HttpClient
• API examples
  • Account
  • Block
  • Contract
  • Logs
  • Proxy
  • Stats
  • Transactions
  • Token
• Version History

MainNet and TestNets

API support all Ethereum default networks: - Mainnet - Goerli - Sepolia

EtherScanAPI api = EtherScanAPI.builder().build();
EtherScanAPI apiGoerli = EtherScanAPI.builder().withNetwork(EthNetworks.GORLI).build();
EtherScanAPI apiSepolia = EtherScanAPI.builder().withNetwork(EthNetworks.SEPOLIA).build();

Custom Network

In case you want to use API for other EtherScan compatible network, you can easily provide custom network with domain api URI.

EtherScanAPI api = EtherScanAPI.builder()
        .withNetwork(() -> URI.create("https://api-my-custom.etherscan.io/api"))
        .build();

Custom HttpClient

In case you need to set custom timeout, custom headers or better implementation for HttpClient, just implement EthHttpClient by your self or initialize it with your values.

Supplier<EthHttpClient> ethHttpClientSupplier = () -> new UrlEthHttpClient(Duration.ofMillis(300), Duration.ofMillis(300));
EtherScanAPI api = EtherScanAPI.builder()
    .withHttpClient(supplier)
    .build();

Also you can use Java 11+ HttpClient:

Supplier<EthHttpClient> ethHttpClientSupplier = () -> new JdkEthHttpClient();
EtherScanAPI api = EtherScanAPI.builder()
    .withHttpClient(supplier)
    .build();

API Examples

You can read about all API methods on Etherscan

Library support all available EtherScan API.

You can use library with or without API key (Check API request\sec restrictions when used without API key).

Library will automatically limit requests up to 1 requests in 5 seconds when used without key and up to 5 requests in 1 seconds when used with API KEY (free plan).

EtherScanAPI.builder()
        .withApiKey(ApiRunner.API_KEY)
        .build();

Below are examples for each API category.

Account API

Get Ether Balance for a single Address

EtherScanAPI api = EtherScanAPI.builder().build();
Balance balance = api.account().balance("0x8d4426f94e42f721C7116E81d6688cd935cB3b4F");

Block API

Get uncles block for block height

EtherScanAPI api = EtherScanAPI.builder().build();
Optional<UncleBlock> uncles = api.block().uncles(200000);

Contract API

Request contract ABI from verified codes

EtherScanAPI api = EtherScanAPI.builder().build();
Abi abi = api.contract().contractAbi("0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413");

Logs API

Get event logs for single topic

EtherScanAPI api = EtherScanAPI.builder().build();
LogQuery query = LogQuery.builder("0x33990122638b9132ca29c723bdf037f1a891a70c")
           .withTopic("0xf63780e752c6a54a94fc52715dbc5518a3b4c3c2833d301a204226548a2a8545")
           .build();
List<Log> logs = api.logs().logs(query);

Get event logs for 3 topics with respectful operations

EtherScanAPI api = EtherScanAPI.builder().build();
LogQuery query = LogQuery.builder("0x33990122638b9132ca29c723bdf037f1a891a70c")
        .withBlockFrom(379224)
        .withBlockTo(400000)
        .withTopic("0xf63780e752c6a54a94fc52715dbc5518a3b4c3c2833d301a204226548a2a8545",
        "0x72657075746174696f6e00000000000000000000000000000000000000000000",
        "0x72657075746174696f6e00000000000000000000000000000000000000000000")
        .setOpTopic0_1(LogOp.AND)
        .setOpTopic0_2(null)
        .setOpTopic1_2(LogOp.AND)
        .build();

List<Log> logs = api.logs().logs(query);

Proxy API

Get tx details with proxy endpoint

EtherScanAPI api = EtherScanAPI.builder().build();
Optional<TxProxy> tx = api.proxy().tx("0x1e2910a263.0.08d0616a0beb24c1a491d78771baa54a33e66065e03b1f46bc1");

Get block info with proxy endpoint

EtherScanAPI api = EtherScanAPI.builder().build();
Optional<BlockProxy> block = api.proxy().block(15215);

Stats API

Statistic about last price

EtherScanAPI api = EtherScanAPI.builder().build();
Price price = api.stats().priceLast();

Transaction API

Request receipt status for tx

EtherScanAPI api = EtherScanAPI.builder().build();
Optional<Boolean> status = api.txs().receiptStatus("0x513c1ba0bebf66436b5fed86ab668452b7805593c05073eb2d51d3a52f480a76");

Token API

You can read about token API here

Token API methods migrated to Account & Stats respectfully.

License

This project licensed under the MIT - see the LICENSE file for details.