{"id":34054433,"url":"https://github.com/gabedonnan/pythereum","last_synced_at":"2026-04-08T17:31:30.948Z","repository":{"id":174030060,"uuid":"651678162","full_name":"gabedonnan/pythereum","owner":"gabedonnan","description":"A lightweight Ethereum JSON RPC library for Python","archived":false,"fork":false,"pushed_at":"2025-05-05T20:50:38.000Z","size":1133,"stargazers_count":48,"open_issues_count":4,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-15T20:37:45.582Z","etag":null,"topics":["cryptocurrency","ethereum","library","python","python-library","rpc","rpc-library"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabedonnan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-06-09T19:48:21.000Z","updated_at":"2025-09-23T05:54:18.000Z","dependencies_parsed_at":"2023-12-17T22:22:43.701Z","dependency_job_id":"2c245db9-0c29-42a5-8b80-6b079c069292","html_url":"https://github.com/gabedonnan/pythereum","commit_stats":null,"previous_names":["gabedonnan/eth_rpc","gabedonnan/pythereum"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/gabedonnan/pythereum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabedonnan%2Fpythereum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabedonnan%2Fpythereum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabedonnan%2Fpythereum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabedonnan%2Fpythereum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabedonnan","download_url":"https://codeload.github.com/gabedonnan/pythereum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabedonnan%2Fpythereum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31566729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptocurrency","ethereum","library","python","python-library","rpc","rpc-library"],"created_at":"2025-12-14T02:13:43.003Z","updated_at":"2026-04-08T17:31:30.939Z","avatar_url":"https://github.com/gabedonnan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pythereum\n(formerly eth_rpc)\n### A lightweight Ethereum RPC library for Python\n\n#### Over four times faster than Web3.py, with more functionality!\n\nFeatures include:\n- Ability to initiate remote procedure calls on a wide variety of ethereum functions\n- Websocket pooling for high performance calls\n- Support for RPC batching, allowing multiple calls to the same function at once\n- \"eth_subscribe\" functionality\n- Currency conversion, with support for esoteric denomination names (e.g. lovelace)\n- Private transaction and Bundle support for communication directly with block builders\n- Automatic nonce and gas management for transactions\n- Early-stage support for L2 chain specific functionality (Optimism P2P implemented for now)\n- Automatic ABI decoding\n- Typed function outputs for intuitive library use\n\n### Implemented RPC methods\n\nAll methods listed in the [Ethereum JSON RPC API specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) are completed as of version `1.0.5`,\nalongside methods for subscriptions, and support for calling custom function names with custom parameters.\n\n### Supported Builders\n\nWith the `BuilderRPC` class, pythereum supports submitting bundles and private transactions directly to block builders.\nEach builder class that can be passed into BuilderRPC instances automatically manages communication with the given builder.\n\nThe following builder classes are currently implemented:\n\n- Titan Builder\n- Rsync Builder\n- Builder0x69\n- Flashbots Builder\n- Beaver Builder\n\n\nTitan Builder and Flashbots now have support for [mevboost](https://mevboost.pics) bundles.\n\n# Getting started\n\n## Poetry\n\nThis project and its dependencies are managed by python poetry,\nwhich will automatically manage the versions of each library / python version\nupon which this project depends.\n\nInstall poetry with the instructions [here.](https://python-poetry.org/docs/)\n\n## Documentation\n\nBrief documentation available on [readthedocs.](https://pythereum.readthedocs.io/en/latest/index.html)\n\nMore information and guides will be added to documentation over time.\n\n## Installation\n\n### Poetry Installation\nThe library currently requires python versions `\u003e=3.11`.\n\nIf you want to include this library for use in another project via Poetry\nyou must simply add the following to your `pyproject.toml` file under `[tool.poetry.dependencies]`\n\n```toml\npythereum = {git = \"https://github.com/gabedonnan/pythereum.git\"}\n```\n\nor\n\n```toml\npythereum = \"^1.2.1\"\n```\n\nIf you would like to install the library via pypi instead of via this git repository.\nThis git repository will always be the most up to date but the releases on pypi should\nbe more thoroughly tested.\n\n### Pip / PyPi installation\n\nThe library is now available via pip!! (I had to change the whole project name to get it there)\n\nIt can be installed with the following command, or downloaded [here](https://pypi.org/project/pythereum/):\n\n```commandline\npython3 -m pip install pythereum\n```\n\n## Example usage\n\n### Basic single function call\n\n```python\n# Example simple function\nimport asyncio\nfrom pythereum import EthRPC\n\nTEST_URL = \"ws://127.0.0.1:8545\"\n\nasync def test_transaction_count():\n  async with EthRPC(TEST_URL, pool_size=1) as erpc:\n    # Gets the number of transactions sent from a given EOA address\n    r = await erpc.get_transaction_count(\"0x5fC2E691E520bbd3499f409bb9602DBA94184672\")\n    print(r)\n\nif __name__ == \"__main__\":\n  asyncio.run(test_transaction_count())\n```\n\n### Example subscription\n\n```python\n# Example subscription\nimport asyncio\nfrom pythereum import EthRPC, SubscriptionType\n\nTEST_URL = \"ws://127.0.0.1:8545\"\n\nasync def test_subscription(subscription_type: SubscriptionType):\n  \"\"\"\n  Creates a subscription to receive data about all new heads\n  Prints each new subscription result as it is received\n  \"\"\"\n  async with EthRPC(TEST_URL, pool_size=1) as erpc:\n    async with erpc.subscribe(subscription_type) as sc:\n      # The following will iterate as each item is gotten by sc.recv()\n      async for item in sc.recv():\n        # 'item' is formatted into the appropriate form for its subscription type\n        # this is done by the sc.recv() automatically\n        print(item)\n\n\nif __name__ == \"__main__\":\n  asyncio.run(test_subscription(SubscriptionType.new_heads))\n```\n\n### Example batch call\n\n```python\n# Example batch call\nimport asyncio\nfrom pythereum import EthRPC\n\nTEST_URL = \"ws://127.0.0.1:8545\"\n\nasync def test_batching():\n  # Batch calls can be applied to any parameterised method\n  # Each parameter must be passed in as a list \n  # With list length k where k is the batch size\n  async with EthRPC(TEST_URL, pool_size=1) as erpc:\n    r = await erpc.get_block_by_number(\n      block_specifier=[\n        i for i in range(40000, 40010)\n      ],\n      full_object=[\n        True for _ in range(10)\n      ]\n    )\n    print(r)\n\n\nif __name__ == \"__main__\":\n  asyncio.run(test_batching())\n```\n\n### Example utility functions\n\n```python\n\u003e\u003e\u003e from pythereum import EthDenomination, convert_eth\n\u003e\u003e\u003e convert_eth(1_000_000, convert_from=EthDenomination.wei, convert_to=EthDenomination.ether)\n1e-12\n\u003e\u003e\u003e convert_eth(1_000, EthDenomination.babbage, EthDenomination.finney)\n1e-09\n\u003e\u003e\u003e convert_eth(1e18, \"wei\", \"eth\")  # We can now use strings to represent denominations\n1.0\n```\n\n```python\n\u003e\u003e\u003e from pythereum import to_checksum_address\n\u003e\u003e\u003e to_checksum_address(\"0x5050f69a9786f081509234f1a7f4684b5e5b76c9\")\nHexStr('0x5050F69a9786F081509234F1a7F4684b5E5b76C9')\n```\n\n\n### Example builder submission\n\n```python\n# Example builder submission\nimport asyncio\nfrom eth_account import Account\nfrom pythereum import BuilderRPC, TitanBuilder, HexStr, Transaction\n\n\nasync def test_builder_submission():\n  # Create new arbitrary account wallet\n  acct = Account.create()\n  # Create an arbitrary EIP-1559 transaction\n  # This transaction is an equivalence to a dictionary, \n  # it simply provides a convenient constructor\n  tx = Transaction(\n    from_address=acct.address,\n    to_address=\"0x5fC2E691E520bbd3499f409bb9602DBA94184672\",\n    value=1,\n    max_priority_fee_per_gas=1,\n    max_fee_per_gas=1,\n    gas=1,\n    chain_id=1,\n    nonce=0\n  )\n\n  # Sign your transaction with your account's key\n  signed_tx = Account.sign_transaction(tx, acct.key).rawTransaction\n\n  # BuilderRPC sends to TitanBuilder, private key used for creating a signed header\n  async with BuilderRPC(TitanBuilder(), private_key=acct.key) as brpc:\n    msg = await brpc.send_private_transaction(HexStr(signed_tx))\n    print(msg)\n\n\nif __name__ == \"__main__\":\n  asyncio.run(test_builder_submission())\n```\n\n### Example Gas and Nonce management\n\n```python\nimport asyncio\nfrom eth_account import Account\nfrom pythereum import GasManager, NonceManager, Transaction, EthRPC\n\nTEST_URL = \"ws://127.0.0.1:8545\"\n\nasync def test_management():\n  acct = Account.create()\n\n  tx = Transaction(\n    from_address=acct.address,\n    to_address=\"0x5fC2E691E520bbd3499f409bb9602DBA94184672\",\n    value=1,\n    chain_id=1\n  )\n  \n  manager_rpc = EthRPC(TEST_URL, pool_size=2)\n  await manager_rpc.start_pool()\n  gm = GasManager(manager_rpc)\n  \n  async with gm.informed_manager() as im:\n      im.fill_transaction(tx)\n  async with NonceManager(manager_rpc) as nm:\n      await nm.fill_transaction(tx)\n\n  signed_tx = Account.sign_transaction(tx, acct.key).rawTransaction\n\n  tx_result = await manager_rpc.send_raw_transaction(signed_tx)\n  print(tx_result)\n  \n  # Wait some time for transaction to be executed so we can get its receipt\n  await asyncio.sleep(3)\n  tx_receipt = await manager_rpc.get_transaction_receipt(tx_result)\n\n  # This means the next time gm.informed_manager() fills a tx, its price will update\n  # An execution success will mean the maxPriorityFeePerGas value of tx will\n  # be modified by im.success_multiplier, else it will be modified by im.fail_multiplier\n  async with gm.informed_manager() as im:\n    if tx_receipt is not None:\n      if tx_receipt.status == 1:\n        # Tell the gas manager that the transaction succeeded\n        im.execution_success()\n      else:\n        # Tell the gas manager that the transaction failed\n        im.execution_failure()\n    # Fill the next transaction with updated values\n    im.fill_transaction(tx)  \n  \n  print(tx)  \n  \n  await manager_rpc.close_pool()\n\nif __name__ == \"__main__\":\n    asyncio.run(test_management())\n```\n\nMore examples available in the [demo](https://github.com/gabedonnan/pythereum/tree/main/demo) folder, including performance comparisons to Web3.py.\n\n## Testing your programs\n\nTesting a program built with this library can be done with actual ethereum\nnodes, though they may rate limit you or cost eth to run.\nAs such using testing programs such as Anvil from the Foundry suite of products\nallows for faster and more productive testing.\n\n### Install foundry\n\nInstructions available at [this link.](https://book.getfoundry.sh/getting-started/installation)\n\n### Run anvil\n\nAnvil is a blockchain testing application included with foundry.\n\nThe following command will run an instance of anvil representing\nthe blockchain's status at block number ```EXAMPLE_BLOCK_NUM``` via url\n```EXAMPLE_RPC_URL```.\n\n```bash\nanvil rpc-url EXAMPLE_RPC_URL@EXAMPLE_BLOCK_NUM\n```\n\nThis is helpful for ensuring consistency in tests, or to simply have a simulated RPC client, run:\n\n```bash\nanvil\n```\n\n### Acknowledgements\n\nSpecial thanks to [@totlsota](https://github.com/totlsota) as a more experienced blockchain developer than I, for giving me pointers when I needed them and\ngenerally assisting in the development of this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabedonnan%2Fpythereum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabedonnan%2Fpythereum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabedonnan%2Fpythereum/lists"}