# Etherlens
EtherLens is a Python library designed to provide comprehensive insights into Blockchain transactions, token balances, and gas balances associated with a specific address. This library offers a range of functionalities, including decoding transactions made by an address, fetching token balances for various ERC-20 tokens, and retrieving gas balances.
### Key Feature
- **Transaction Decoding**: Decode any blockchain **(ETH,BSC,ARB,OP,BASE,POLY)** transaction that contain similar uniswap V2 router functions and universal router like function.It gives insight on token bought,token sold,amount bought,amount sold,hash of the transction
- **Token Balance Fetching**: Fetch token balances associated with a given blockchain address for a wide range of ERC-20 tokens, allowing users to quickly ascertain their token holdings.
- **Gas Balance Retrieval**: Retrieve gas balances associated with an Ethereum address, enabling users to monitor gas usage and ensure efficient management of gas resources.
### Caution
⚠ This library has not been audited, and there is no pledge for one !
⚠ Might be of advantage to be familiar with general blockchain concepts and [web3.py](https://github.com/ethereum/web3.py) in particular.
⚠ This project is a work in progress so not all swap transaction are decoded yet.
## Installation
It is recommended to use [Python virtual environments](https://python.readthedocs.io/en/latest/library/venv.html), here is a [tutorial](https://www.freecodecamp.org/news/how-to-setup-virtual-environments-in-python/) inorder for the dependencies not to conflict with any other Dependencies you might have in your system
```bash
# install the Etherlens from pypi.org
pip install Etherlens
```
---
## Utilization
This Library exposes a class Observe which has hpublic method that can be use to decode address transction,get token address balance,fetch native gas balance and more
## How to decode/get address transaction detail, assuming it swapped on uniswap/sushi or any dapp with similar V2 router contract functions
You can pass in only one address or list of addresses to the method
#### Blockchain usage
During instantiation of the class **Observe** user should specify which blockchain he/she wants eg 'ETH','BSC','BASE','OP','ARB','POLY'
```python
from etherlens import Observe
Your_rpc_url = 'https://.......'
Decode = Observe(Your_rpc_url,'ETH')
Address = ['0x82D55805Cd58E908772025F3f32AE55B0eD93143','0x26cE34d34724428138F2E5a6a5B5B95ad8e64f6C']
Output = Decode.monitor(Address)
print(Output)
```
Example of Output returned by the `monitor( )`:
```python
{'Address(0x15deac498767a6e997c007ca91df55cbdd8a6198)': [
{'hash(0x0ba00128c137225647c6e264659f156bde27eafb6133a2e89cfa450ea9eda5d2)':
{'amountIn': 321551417590518774759424,
'aountOut': 24405654217389512,
'tokenIn': '0xfEA9DcDc9E23a9068bF557AD5b186675C61d33eA',
'tokenOut': '0x4200000000000000000000000000000000000006'}},
'Address(0xc633843de683ff3e91353412b039b0699fa1615b)': [
{'hash(0x53633f8e720ba4f22387ff1e34dac802c07dd9b7ec5b1963b755ff99edf9c15e)':
{'ammountIn': 26697410107434513,
'amountOut': 1579868553164855380085,
'tokenIn': '0x4200000000000000000000000000000000000006',
'tokenOut': '0xBd59400A7b2062E6a4F64AbbE99D046Fe226757C'}}, {'hash(0xeafc84e5cb41260e32cdd094092b6e4e9189e3e813a4d56e9893b36ca13911b8)':
{'ammountIn': 1681333259230206230528,
'amountOut': 3864771106922855,
'tokenIn': '0xBd59400A7b2062E6a4F64AbbE99D046Fe226757C',
'tokenOut': '0x4200000000000000000000000000000000000006'}}]}
```
---
### Get Swap detail with hash
```python
hash = '0x53633f8e720ba4f22387ff1e34dac802c07dd9b7ec5b1963b755ff99edf9c15e'
output = Decode.monitor_with_hash(hash)
print(output)
```
Example of Output Returned by `monitor_with_hash( )`
```python
{'hash(0x53633f8e720ba4f22387ff1e34dac802c07dd9b7ec5b1963b755ff99edf9c15e)': {'ammountIn': 26697410107434513, 'amountOut': 1579868553164855380085, 'tokenIn': '0x4200000000000000000000000000000000000006', 'tokenOut': '0xBd59400A7b2062E6a4F64AbbE99D046Fe226757C'}}
```
---
### Retrive Address/Addresses token(ERC20) balance
```python
tokenContractAddress = '0x9DE16c805A3227b9b92e39a446F9d56cf59fe640'
Address = ['0x08c03a6b5d51a8915bae08a0f182dab6fb2c059b','0x94661f0b3619072c6ce591534e95019a4a3f7ad5'] # you can use a string of address too eg addresss = '0x08c03a6b5d51a8915bae08a0f182dab6fb2c059b'
output = Decode.token_balance(tokenContractAddress,Address)
print(output)
```
Example of output Returned by `token_balance( )`:
```python
{'0x08c03a6b5d51a8915bae08a0f182dab6fb2c059b': 1476352034707.0415, '0x94661f0b3619072c6ce591534e95019a4a3f7ad5': 1408145648317.3828}
```
---
### Retrive Address Eth/native gas balance
```python
Address = ['0x15deac498767a6e997c007ca91df55cbdd8a6198','0x94661f0b3619072c6ce591534e95019a4a3f7ad5']
output = Decode.eth_balance(Address)
print(output)
```
Example of Output Returned by `eth_balance( )`:
```python
{'0x15deac498767a6e997c007ca91df55cbdd8a6198': 0.001072, '0x94661f0b3619072c6ce591534e95019a4a3f7ad5': 0.039995}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/freemandaily/EtherLens",
"name": "Etherlens",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "blockchain, ethereum, uniswap, decoder",
"author": "freemandaily",
"author_email": "freemandaily <Onahchinemelem@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/70/4b/29c29677305cd5f8618dfc2fe1e23b5e11750c5a704aec498bbc2015ebdc/etherlens-0.0.1.tar.gz",
"platform": null,
"description": "# Etherlens\r\nEtherLens is a Python library designed to provide comprehensive insights into Blockchain transactions, token balances, and gas balances associated with a specific address. This library offers a range of functionalities, including decoding transactions made by an address, fetching token balances for various ERC-20 tokens, and retrieving gas balances.\r\n\r\n### Key Feature\r\n- **Transaction Decoding**: Decode any blockchain **(ETH,BSC,ARB,OP,BASE,POLY)** transaction that contain similar uniswap V2 router functions and universal router like function.It gives insight on token bought,token sold,amount bought,amount sold,hash of the transction\r\n- **Token Balance Fetching**: Fetch token balances associated with a given blockchain address for a wide range of ERC-20 tokens, allowing users to quickly ascertain their token holdings.\r\n- **Gas Balance Retrieval**: Retrieve gas balances associated with an Ethereum address, enabling users to monitor gas usage and ensure efficient management of gas resources.\r\n \r\n### Caution\r\n\u26a0 This library has not been audited, and there is no pledge for one !\r\n\r\n\u26a0 Might be of advantage to be familiar with general blockchain concepts and [web3.py](https://github.com/ethereum/web3.py) in particular.\r\n\r\n\u26a0 This project is a work in progress so not all swap transaction are decoded yet.\r\n\r\n\r\n## Installation\r\nIt is recommended to use [Python virtual environments](https://python.readthedocs.io/en/latest/library/venv.html), here is a [tutorial](https://www.freecodecamp.org/news/how-to-setup-virtual-environments-in-python/) inorder for the dependencies not to conflict with any other Dependencies you might have in your system\r\n\r\n\r\n\r\n```bash\r\n# install the Etherlens from pypi.org\r\npip install Etherlens\r\n```\r\n\r\n---\r\n## Utilization\r\nThis Library exposes a class Observe which has hpublic method that can be use to decode address transction,get token address balance,fetch native gas balance and more\r\n\r\n\r\n## How to decode/get address transaction detail, assuming it swapped on uniswap/sushi or any dapp with similar V2 router contract functions\r\nYou can pass in only one address or list of addresses to the method \r\n\r\n #### Blockchain usage\r\n During instantiation of the class **Observe** user should specify which blockchain he/she wants eg 'ETH','BSC','BASE','OP','ARB','POLY'\r\n \r\n```python\r\nfrom etherlens import Observe\r\n\r\nYour_rpc_url = 'https://.......'\r\nDecode = Observe(Your_rpc_url,'ETH')\r\nAddress = ['0x82D55805Cd58E908772025F3f32AE55B0eD93143','0x26cE34d34724428138F2E5a6a5B5B95ad8e64f6C']\r\nOutput = Decode.monitor(Address)\r\nprint(Output)\r\n```\r\nExample of Output returned by the `monitor( )`:\r\n```python\r\n\r\n{'Address(0x15deac498767a6e997c007ca91df55cbdd8a6198)': [\r\n {'hash(0x0ba00128c137225647c6e264659f156bde27eafb6133a2e89cfa450ea9eda5d2)':\r\n {'amountIn': 321551417590518774759424,\r\n 'aountOut': 24405654217389512,\r\n 'tokenIn': '0xfEA9DcDc9E23a9068bF557AD5b186675C61d33eA',\r\n 'tokenOut': '0x4200000000000000000000000000000000000006'}},\r\n'Address(0xc633843de683ff3e91353412b039b0699fa1615b)': [\r\n{'hash(0x53633f8e720ba4f22387ff1e34dac802c07dd9b7ec5b1963b755ff99edf9c15e)':\r\n {'ammountIn': 26697410107434513,\r\n 'amountOut': 1579868553164855380085,\r\n 'tokenIn': '0x4200000000000000000000000000000000000006',\r\n 'tokenOut': '0xBd59400A7b2062E6a4F64AbbE99D046Fe226757C'}}, {'hash(0xeafc84e5cb41260e32cdd094092b6e4e9189e3e813a4d56e9893b36ca13911b8)':\r\n {'ammountIn': 1681333259230206230528,\r\n 'amountOut': 3864771106922855,\r\n 'tokenIn': '0xBd59400A7b2062E6a4F64AbbE99D046Fe226757C',\r\n 'tokenOut': '0x4200000000000000000000000000000000000006'}}]}\r\n```\r\n---\r\n### Get Swap detail with hash\r\n```python\r\nhash = '0x53633f8e720ba4f22387ff1e34dac802c07dd9b7ec5b1963b755ff99edf9c15e'\r\noutput = Decode.monitor_with_hash(hash)\r\nprint(output)\r\n```\r\nExample of Output Returned by `monitor_with_hash( )`\r\n\r\n```python\r\n{'hash(0x53633f8e720ba4f22387ff1e34dac802c07dd9b7ec5b1963b755ff99edf9c15e)': {'ammountIn': 26697410107434513, 'amountOut': 1579868553164855380085, 'tokenIn': '0x4200000000000000000000000000000000000006', 'tokenOut': '0xBd59400A7b2062E6a4F64AbbE99D046Fe226757C'}}\r\n```\r\n---\r\n\r\n### Retrive Address/Addresses token(ERC20) balance\r\n\r\n```python\r\ntokenContractAddress = '0x9DE16c805A3227b9b92e39a446F9d56cf59fe640'\r\nAddress = ['0x08c03a6b5d51a8915bae08a0f182dab6fb2c059b','0x94661f0b3619072c6ce591534e95019a4a3f7ad5'] # you can use a string of address too eg addresss = '0x08c03a6b5d51a8915bae08a0f182dab6fb2c059b'\r\noutput = Decode.token_balance(tokenContractAddress,Address)\r\nprint(output)\r\n```\r\nExample of output Returned by `token_balance( )`:\r\n\r\n```python\r\n{'0x08c03a6b5d51a8915bae08a0f182dab6fb2c059b': 1476352034707.0415, '0x94661f0b3619072c6ce591534e95019a4a3f7ad5': 1408145648317.3828}\r\n```\r\n---\r\n\r\n### Retrive Address Eth/native gas balance\r\n```python\r\nAddress = ['0x15deac498767a6e997c007ca91df55cbdd8a6198','0x94661f0b3619072c6ce591534e95019a4a3f7ad5']\r\noutput = Decode.eth_balance(Address)\r\nprint(output)\r\n```\r\nExample of Output Returned by `eth_balance( )`:\r\n\r\n```python\r\n{'0x15deac498767a6e997c007ca91df55cbdd8a6198': 0.001072, '0x94661f0b3619072c6ce591534e95019a4a3f7ad5': 0.039995}\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "EtherLens is a Python library designed to provide comprehensive insights into Ethereum transactions",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/freemandaily/EtherLens"
},
"split_keywords": [
"blockchain",
" ethereum",
" uniswap",
" decoder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a96a0059bea94648aaae8a46e503b11e05f2c104b499615b91d16aebb0f8f3d",
"md5": "cd7da982c0c9a60c54d004d0ff0434ff",
"sha256": "5b837e062411c98fba2bd199bd7d62af7159cfadcaa7c9484c38aa3ab44f3c9a"
},
"downloads": -1,
"filename": "Etherlens-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cd7da982c0c9a60c54d004d0ff0434ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8478,
"upload_time": "2024-05-09T16:17:25",
"upload_time_iso_8601": "2024-05-09T16:17:25.208604Z",
"url": "https://files.pythonhosted.org/packages/5a/96/a0059bea94648aaae8a46e503b11e05f2c104b499615b91d16aebb0f8f3d/Etherlens-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "704b29c29677305cd5f8618dfc2fe1e23b5e11750c5a704aec498bbc2015ebdc",
"md5": "9c88d3bc634a68d70b6f759f9f164b4f",
"sha256": "f26013f633a88d6cf126fad501c5de635e8ceedbe26976261a92f4bdaac5eea7"
},
"downloads": -1,
"filename": "etherlens-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9c88d3bc634a68d70b6f759f9f164b4f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8089,
"upload_time": "2024-05-09T16:17:27",
"upload_time_iso_8601": "2024-05-09T16:17:27.842810Z",
"url": "https://files.pythonhosted.org/packages/70/4b/29c29677305cd5f8618dfc2fe1e23b5e11750c5a704aec498bbc2015ebdc/etherlens-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-09 16:17:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "freemandaily",
"github_project": "EtherLens",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "etherlens"
}
JSON
