# Quick Start
The following is a subset of the supported blockchain explorers:
| Network Name | Explorer Link |
| ------------------- | ------------------------------------------------------- |
| Arbitrum | [Arbiscan](https://arbiscan.io) |
| Avalanche | [Snowtrace](https://snowtrace.io) |
| Base | [Basescan](https://basescan.org) |
| Binance Smart Chain | [Bscscan](https://bscscan.com) |
| Bittorrent | [BTTCscan](https://bttcscan.com) |
| Blast | [Blastscan](https://blastscan.io) |
| Celo | [Celoscan](https://celoscan.com) |
| Ethereum | [Etherscan](https://etherscan.io/) |
| Fantom | [Ftmscan](https://ftmscan.com) |
| Fraxtal | [Fraxscan](https://fraxscan.com) |
| Gnosis | [Gnosisscan](https://gnosisscan.io) |
| Kroma | [Kromascan](https://kromascan.com) |
| Moonbeam | [Moonscan](https://moonscan.io) |
| Optimism | [Optimistic Etherscan](https://optimistic.etherscan.io) |
| Polygon | [Polygonscan](https://polygonscan.com) |
| Polygon ZkEVM | [Polygonscan ZkEVM](https://zkevm.polygonscan.com) |
| Scroll | [Scrollscan](https://scrollscan.com) |
| Unichain | [Uniscan](https://sepolia.uniscan.xyz) |
To see the full list of networks supported by Etherscan, see Etherscan's [Supported Chains](https://docs.etherscan.io/contract-verification/supported-chains) guide.
## Dependencies
- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.
## Installation
### via `pip`
You can install the latest release via [`pip`](https://pypi.org/project/pip/):
```bash
pip install ape-etherscan
```
### via `setuptools`
You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:
```bash
git clone https://github.com/ApeWorX/ape-etherscan.git
cd ape-etherscan
python3 setup.py install
```
## Quick Usage
### Set up the environment
Specify API keys as environment variables. You could put them in your shell's config like `~/.profile`
or use a tool like [direnv](https://direnv.net/) and store them locally in `.envrc`.
You can also specify multiple comma-separated keys, a random key will be chosen for each request.
This could be useful if you hit API rate limits.
You can obtain an API key by registering with Etherscan and visiting [this page](https://etherscan.io/myapikey).
```bash
export ETHERSCAN_API_KEY=SAMPLE_KEY
export FTMSCAN_API_KEY=SAMPLE_KEY
export ARBISCAN_API_KEY=SAMPLE_KEY
export POLYGON_ZKEVM_ETHERSCAN_API_KEY=SAMPLE_KEY
export BASESCAN_API_KEY=SAMPLE_KEY
```
### Transaction URLs
When you have this plugin installed, Etherscan explorer URLs appear in CLI output.
```bash
INFO: Submitted 0x123321123321123321123321123aaaadaaaee4b2aaa07901b80716cc357a9646
etherscan URL: https://rinkeby.etherscan.io/tx/0x123321123321123321123321123aaaadaaaee4b2aaa07901b80716cc357a9646
```
### Contract Types
The `ape-etherscan` plugin also assists in fetching `contract_types`.
Use the `Contract` top-level construct to create contract instances.
When the explorer plugin locates a contract type for a given address, the `Contract` return-value uses that contract type.
```python
from ape import accounts, Contract
contract = Contract("0x55a8a39bc9694714e2874c1ce77aa1e599461e18")
receipt = contract.call_mutable_method("arg0", sender=accounts.load("acct"))
```
The first line `contract = Contract("0x55a8a39bc9694714e2874c1ce77aa1e599461e18")` checks if ape has a cached contract-type for the address `0x55a8a39bc9694714e2874c1ce77aa1e599461e18`.
If it does not find a cached contract type, it uses an explorer plugin to attempt to find one.
If found, the contract type is then cached to disk and in memory for the active session so that subsequent invocations don't require HTTP calls.
The return value from `Contract` is a `ContractInstance`, so it is connected to your active provider and ready for transactions.
**NOTE**: Vyper contracts from Etherscan always return the name `Vyper_contract`.
However, if the plugin detects that the contract type has a method named `symbol`, it will use the return value from that call instead.
### Contract Verification
Use the `ape-etherscan` plugin to publish and verify your contracts.
Contract verification associates a contract type from Ape with an Ethereum address on Etherscan.
Learn more about Etherscan verification [here](https://info.etherscan.com/types-of-contract-verification/).
To verify contract in Ape, you can set the `publish` key to `True` when deploying:
```python
from ape import accounts, project
account = accounts.load("testnetacct")
account.deploy(project.MyContract, publish=True)
```
You can also use the explorer class directly to publish at a later time:
```python
from ape import networks
etherscan = networks.provider.network.explorer
etherscan.publish_contract("0x55a8a39bc9694714e2874c1ce77aa1e599461e18")
```
Not every network's explorer supports multi-file verification.
For those networks, the corresponding compiler plugin's `flatten` functionality is invoked, in order to verify the contract as a single file.
**NOTE**: You must set an Etherscan API key environment variable to use the publishing feature.
### Custom Networks
If you would like to use ape-etherscan with your [custom network configuration](https://docs.apeworx.io/ape/stable/userguides/networks.html#custom-network-connection), you can use the same network identifier you used to configure it.
For instance, with a custom Ethereum network called "apechain" your configuration might look something like this:
```yaml
networks:
custom:
- name: apechain
chain_id: 31337
node:
ethereum:
apechain:
uri: http://localhost:8545
etherscan:
ethereum:
rate_limit: 15
apechain:
uri: https://custom.scan
api_uri: https://api.custom.scan/api
```
### Dependencies
You can use dependencies from Etherscan in your projects.
Configure them like this:
```yaml
dependencies:
- name: Spork
etherscan: "0xb624FdE1a972B1C89eC1dAD691442d5E8E891469"
ecosystem: ethereum
network: mainnet
```
Then, access contract types from the dependency in your code:
```python
from ape import project
spork_contract_type = project.dependencies["Spork"]["etherscan"].Spork
```
### Querying Accounts
Etherscan offers a query-provider plugin for account data.
Query account transactions from Etherscan using the following syntax:
```python
from ape import chain
history = chain.history["vitalik.eth"]
# NOTE: Also showing how you can use `start_nonce=` and `stop_nonce=`
# to limit the history.
result = history.query("*", start_nonce=1000, stop_nonce=1001, engine_to_use="etherscan")
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/ape-etherscan",
"name": "ape-etherscan",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/44/59/6682c72e60217ea5e031f5525babe2046e8e477c6345a63757f516503cec/ape_etherscan-0.8.4.tar.gz",
"platform": null,
"description": "# Quick Start\n\nThe following is a subset of the supported blockchain explorers:\n\n| Network Name | Explorer Link |\n| ------------------- | ------------------------------------------------------- |\n| Arbitrum | [Arbiscan](https://arbiscan.io) |\n| Avalanche | [Snowtrace](https://snowtrace.io) |\n| Base | [Basescan](https://basescan.org) |\n| Binance Smart Chain | [Bscscan](https://bscscan.com) |\n| Bittorrent | [BTTCscan](https://bttcscan.com) |\n| Blast | [Blastscan](https://blastscan.io) |\n| Celo | [Celoscan](https://celoscan.com) |\n| Ethereum | [Etherscan](https://etherscan.io/) |\n| Fantom | [Ftmscan](https://ftmscan.com) |\n| Fraxtal | [Fraxscan](https://fraxscan.com) |\n| Gnosis | [Gnosisscan](https://gnosisscan.io) |\n| Kroma | [Kromascan](https://kromascan.com) |\n| Moonbeam | [Moonscan](https://moonscan.io) |\n| Optimism | [Optimistic Etherscan](https://optimistic.etherscan.io) |\n| Polygon | [Polygonscan](https://polygonscan.com) |\n| Polygon ZkEVM | [Polygonscan ZkEVM](https://zkevm.polygonscan.com) |\n| Scroll | [Scrollscan](https://scrollscan.com) |\n| Unichain | [Uniscan](https://sepolia.uniscan.xyz) |\n\nTo see the full list of networks supported by Etherscan, see Etherscan's [Supported Chains](https://docs.etherscan.io/contract-verification/supported-chains) guide.\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.\n\n## Installation\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install ape-etherscan\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/ape-etherscan.git\ncd ape-etherscan\npython3 setup.py install\n```\n\n## Quick Usage\n\n### Set up the environment\n\nSpecify API keys as environment variables. You could put them in your shell's config like `~/.profile`\nor use a tool like [direnv](https://direnv.net/) and store them locally in `.envrc`.\n\nYou can also specify multiple comma-separated keys, a random key will be chosen for each request.\nThis could be useful if you hit API rate limits.\n\nYou can obtain an API key by registering with Etherscan and visiting [this page](https://etherscan.io/myapikey).\n\n```bash\nexport ETHERSCAN_API_KEY=SAMPLE_KEY\nexport FTMSCAN_API_KEY=SAMPLE_KEY\nexport ARBISCAN_API_KEY=SAMPLE_KEY\nexport POLYGON_ZKEVM_ETHERSCAN_API_KEY=SAMPLE_KEY\nexport BASESCAN_API_KEY=SAMPLE_KEY\n```\n\n### Transaction URLs\n\nWhen you have this plugin installed, Etherscan explorer URLs appear in CLI output.\n\n```bash\nINFO: Submitted 0x123321123321123321123321123aaaadaaaee4b2aaa07901b80716cc357a9646\netherscan URL: https://rinkeby.etherscan.io/tx/0x123321123321123321123321123aaaadaaaee4b2aaa07901b80716cc357a9646\n```\n\n### Contract Types\n\nThe `ape-etherscan` plugin also assists in fetching `contract_types`.\nUse the `Contract` top-level construct to create contract instances.\nWhen the explorer plugin locates a contract type for a given address, the `Contract` return-value uses that contract type.\n\n```python\nfrom ape import accounts, Contract\n\ncontract = Contract(\"0x55a8a39bc9694714e2874c1ce77aa1e599461e18\")\nreceipt = contract.call_mutable_method(\"arg0\", sender=accounts.load(\"acct\"))\n```\n\nThe first line `contract = Contract(\"0x55a8a39bc9694714e2874c1ce77aa1e599461e18\")` checks if ape has a cached contract-type for the address `0x55a8a39bc9694714e2874c1ce77aa1e599461e18`.\nIf it does not find a cached contract type, it uses an explorer plugin to attempt to find one.\nIf found, the contract type is then cached to disk and in memory for the active session so that subsequent invocations don't require HTTP calls.\nThe return value from `Contract` is a `ContractInstance`, so it is connected to your active provider and ready for transactions.\n\n**NOTE**: Vyper contracts from Etherscan always return the name `Vyper_contract`.\nHowever, if the plugin detects that the contract type has a method named `symbol`, it will use the return value from that call instead.\n\n### Contract Verification\n\nUse the `ape-etherscan` plugin to publish and verify your contracts.\nContract verification associates a contract type from Ape with an Ethereum address on Etherscan.\nLearn more about Etherscan verification [here](https://info.etherscan.com/types-of-contract-verification/).\n\nTo verify contract in Ape, you can set the `publish` key to `True` when deploying:\n\n```python\nfrom ape import accounts, project\n\naccount = accounts.load(\"testnetacct\")\naccount.deploy(project.MyContract, publish=True)\n```\n\nYou can also use the explorer class directly to publish at a later time:\n\n```python\nfrom ape import networks\n\netherscan = networks.provider.network.explorer\netherscan.publish_contract(\"0x55a8a39bc9694714e2874c1ce77aa1e599461e18\")\n```\n\nNot every network's explorer supports multi-file verification.\nFor those networks, the corresponding compiler plugin's `flatten` functionality is invoked, in order to verify the contract as a single file.\n\n**NOTE**: You must set an Etherscan API key environment variable to use the publishing feature.\n\n### Custom Networks\n\nIf you would like to use ape-etherscan with your [custom network configuration](https://docs.apeworx.io/ape/stable/userguides/networks.html#custom-network-connection), you can use the same network identifier you used to configure it.\nFor instance, with a custom Ethereum network called \"apechain\" your configuration might look something like this:\n\n```yaml\nnetworks:\n custom:\n - name: apechain\n chain_id: 31337\n\nnode:\n ethereum:\n apechain:\n uri: http://localhost:8545\n\netherscan:\n ethereum:\n rate_limit: 15\n apechain:\n uri: https://custom.scan\n api_uri: https://api.custom.scan/api\n```\n\n### Dependencies\n\nYou can use dependencies from Etherscan in your projects.\nConfigure them like this:\n\n```yaml\ndependencies:\n - name: Spork\n etherscan: \"0xb624FdE1a972B1C89eC1dAD691442d5E8E891469\"\n ecosystem: ethereum\n network: mainnet\n```\n\nThen, access contract types from the dependency in your code:\n\n```python\nfrom ape import project\n\nspork_contract_type = project.dependencies[\"Spork\"][\"etherscan\"].Spork\n```\n\n### Querying Accounts\n\nEtherscan offers a query-provider plugin for account data.\nQuery account transactions from Etherscan using the following syntax:\n\n```python\nfrom ape import chain\n\nhistory = chain.history[\"vitalik.eth\"]\n\n# NOTE: Also showing how you can use `start_nonce=` and `stop_nonce=`\n# to limit the history.\nresult = history.query(\"*\", start_nonce=1000, stop_nonce=1001, engine_to_use=\"etherscan\")\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "ape-etherscan: Etherscan Explorer Plugin for Ethereum-based networks",
"version": "0.8.4",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/ape-etherscan"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8199b3940db2799714e507b76fbc7976523426d0095cf0d3cdd9108bff984a2f",
"md5": "1cbf34e680a3bc47adc130438fa11f75",
"sha256": "23358309badd10e71754473de7244becdd066b2239bc2c6640516a6e0a4907a8"
},
"downloads": -1,
"filename": "ape_etherscan-0.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cbf34e680a3bc47adc130438fa11f75",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 27485,
"upload_time": "2024-12-02T18:43:59",
"upload_time_iso_8601": "2024-12-02T18:43:59.029010Z",
"url": "https://files.pythonhosted.org/packages/81/99/b3940db2799714e507b76fbc7976523426d0095cf0d3cdd9108bff984a2f/ape_etherscan-0.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44596682c72e60217ea5e031f5525babe2046e8e477c6345a63757f516503cec",
"md5": "97e75641b21323026e6a6e6fc982cbdb",
"sha256": "39f17738a32a1199fdf10fed0b5d7794a93aca4670c1c9256e8698f66c6ee9b9"
},
"downloads": -1,
"filename": "ape_etherscan-0.8.4.tar.gz",
"has_sig": false,
"md5_digest": "97e75641b21323026e6a6e6fc982cbdb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 105862,
"upload_time": "2024-12-02T18:44:01",
"upload_time_iso_8601": "2024-12-02T18:44:01.059491Z",
"url": "https://files.pythonhosted.org/packages/44/59/6682c72e60217ea5e031f5525babe2046e8e477c6345a63757f516503cec/ape_etherscan-0.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-02 18:44:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "ape-etherscan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ape-etherscan"
}
JSON
