ETH_ACCOUNT(1)

NAME
eth_account - eth-account Documentation

Sign Ethereum transactions and messages with local private keys

INSTALLATION

    python -m pip install eth-account

  eth_account

  Account

See Signers for alternative signers.

  SignedTransaction & SignedMessage

  Messages

  Signers

These classes abstract away the private key, as opposed to eth_account.account.Account, which explicitly requires the private key on each usage.

All the signer classes in this package must meet the interface specified by BaseAccount.

Currently there is only one Local Signer. Some upcoming alternatives to the basic local signer include hierarchical deterministic (HD) wallets and hardware wallets.

  Local Signer

  Abstract Signer

  Typed Transactions

  Typed Transaction Base

  Access List Transaction

  Dynamic Fee Transaction

  Blob Transaction

  Set Code Transaction

  HD Account

CAUTION: These features are experimental and unaudited

  HD Mnemonic module

  Module contents

  Release Notes

  eth-account v0.13.7 (2025-04-21)

  Bugfixes

•   Fix issues with the json schema generation for Pydantic models (SignedSetCodeAuthorization) and simplify the serialization by moving a misplaced @field_validator decorator above @classmethod (not below it). (#318)

•   Remove doc warnings and unwanted generated docs (#321)

  Improved Documentation

•   Update and clarify documentation for authorization signing. (#319)

  eth-account v0.13.6 (2025-03-26)

  Bugfixes

•   Adds logic to interpret the string values "False", "false", and "0" as False when encoding EIP712 messages. (#303)

  Features

•   Implement EIP-7702 SetCodeTransaction. (#315)

  eth-account v0.13.5 (2025-02-04)

  Features

•   Make sign_typed_data available in the LocalAccount class. (#304)

•   Merge template, adding py313 support, replacing bumpversion with bump-my-version and bumping hypothesis test dep to >=6.22.0,<6.108.7. (#311)

  Internal Changes - for eth-account Contributors

•   deepcopy EIP712 messages used in test to avoid unintended mutation. (#308)

•   Update node.js version used in tests from 20 to 22. (#309)

  eth-account v0.13.4 (2024-09-25)

  Deprecations

•   Change language arg to enum in Mnemonic (#291)

  Features

•   Add new list_languages_enum method to HDAccount class (#302)

  Internal Changes - for eth-account Contributors

•   Pin eth-keyfile <0.9.0 due to breaking changes to typing (#299)

  eth-account v0.13.3 (2024-08-28)

  Bugfixes

•   Raise lower pin on eth-keyfile to >=0.7.0 where a bug was fixed in the default values for scrypt generated keyfiles. (#297)

  eth-account v0.13.2 (2024-08-21)

  Bugfixes

•   Pin ckzg to >=2.0; update the the trusted setup and how it is loaded. (#293)

  eth-account v0.13.1 (2024-07-24)

  Internal Changes - for eth-account Contributors

•   Update mypy checks to run with all dev dependencies installed (#280)

•   Enforce mypy strict_optional rule (#281)

•   Updated mypy types setting disallow_untyped_defs and disallow_untyped_calls to true (#283)

•   Set mypy rules disallow_any_generics, disallow_subclassing_any, and disallow_untyped_decorators to true (#285)

  eth-account v0.13.0 (2024-05-20)

  Bugfixes

•   Open up Pydantic dependency (#271)

  Features

•   Expose TypedTransactions for public use (#276)

  Internal Changes - for eth-account Contributors

•   Merge template updates, notably adding python 3.12 support (#274)

  Miscellaneous Changes

•   #275

  Removals

•   Remove signHash in favor of unsafe_sign_hash (#260)

•   Remove messageHash in favor of message_hash (#265)

•   Moved private _parsePrivateKey method to _parse_private_key (#267)

•   Remove SignedTransaction's rawTransaction attribute in favor of raw_transaction (#268)

•   Remove encode_structured_data in favor of encode_typed_data (#269)

  eth-account v0.12.1 (2024-04-02)

  Improved Documentation

•   Update documentation to include blob transaction signing example. (#258)

  eth-account v0.12.0 (2024-04-01)

  Bugfixes

•   Import cytoolz methods via eth_utils instead of cytoolz directly (#251)

  Improved Documentation

•   Add encode_typed_data to list of functions that return a SignableMessage (#247)

  Features

•   Add support for type 3, BlobTransaction, introduced by the Cancun network upgrade. (#253)

  Internal Changes - for eth-account Contributors

•   Bump deps to hexbytes>=1.2.0 and eth-rlp>=2.1.0 (#254)

  eth-account v0.11.0 (2024-02-05)

  Breaking Changes

•   Drop support for python 3.7 (#248)

  Internal Changes - for eth-account Contributors

•   Change older % and .format strings to use f-strings (#245)

•   Merge template updates, notably use pre-commit for linting and change the name of the master branch to main (#248)

  Removals

•   Remove deprecated signTransaction, it has been replaced by sign_transaction (#244)

  eth-account v0.10.0 (2023-10-30)

  Deprecations

•   Deprecate encode_structured_data in favor of new encode_typed_data (#235)

  Improved Documentation

•   Added usage notes and example for encode_structured_data (#233)

  Features

•   Add new encode_typed_data to better handle EIP712 message signing (#235)

•   Added option to call encode_typed_data with a single dict arg in addition to the existing 3-dict style (#238)

•   Add sign_typed_data as a method of the Account class (#239)

  Internal Changes - for eth-account Contributors

•   Added tests for encode_structured_data for easier comparison with Metamask's SignTypedData (#233)

•   Bump version for node and ethers.js in integration tests, update ethers usage to match (#236)

•   Add build.os to readthedocs settings (#237)

•   Add upper pin to hexbytes dependency to due incoming breaking change (#240)

•   Add tests comparing output of signed EIP712 messages with metamask and ethers (#241)

  eth-account v0.9.0 (2023-06-07)

  Breaking Changes

•   drop python3.6 support from setup (#228)

  Improved Documentation

•   remove notices of Draft status for eips 712 and 191 (#222)

  Features

•   Add support for Python 3.11 (#212)

  Internal Changes - for eth-account Contributors

•   Upgrade Node from v12.x to v18.x in tests (#217)

•   pulled full new node_v18 install script (#223)

•   bump versions for docs dependencies (#224)

•   add sphinx_rtd_theme to docs/conf.py extensions list (#225)

•   merge in updates from python project template (#288)

  eth-account v0.8.0 (2022-12-15)

  Features

•   update all references to deprecated eth_abi.encode_abi to eth_abi.encode (#200)

  Performance improvements

•   Reduce the number of pbkdf2 iterations to speed up tests (#77)

  Deprecations and Removals

•   remove deprecated methods that were noted to go in v0.5 (#195)

  Internal Changes - for eth-account Contributors

•   add coverage reporting to pytest (#192)

•   Use updated circleci Python images, fix Sphinx warning (#194)

  Miscellaneous changes

•   #197, #198, #199, #202, #203, #204, #206

  eth-account v0.7.0 (2022-08-17)

  Bugfixes

•   bump ansi-regex to 5.0.1 to fix minor ReDos vulnerability (#129)

•   Enable lint runs again on CI (#166)

•   fix DoS-able regex pattern (#178)

•   Allow towncrier to build the release notes again (#185)

  Improved Documentation

•   Add example to generate multiple accounts from a mnemonic (#153)

•   Pin Jinja2 at >=3.0.0,<3.1.0; pin towncrier==18.5.0; open up Sphinx requirement to allow >=1.6.5,<5. (#156)

•   added missing quotes to readme dev environment setup example (#172)

  Miscellaneous changes

•   #79, #155, #162, #164, #165

  Breaking changes

•   Change bitarray dependency requirement to be >=2.4,<3 since 2.4 has wheels for all platform types. (#154)

•   Fix errors in EIP-712 signing (#175)

  eth-account v0.6.1 (2022-02-24)

  Bugfixes

•   Allow encoding of structured data containing bytes (#91)

  Miscellaneous changes

•   #68, #144

  eth-account v0.6.0 (2022-01-20)

  Features

•   Update dependencies: - eth-abi - eth-keyfile - eth-keys - eth-rlp - pyrlp - eth-utils (#138)

•   Add support for Python 3.9 and 3.10 (#139)

  Deprecations and Removals

•   Drop support for Python 3.6 (#139)

  eth-account v0.5.9 (2022-08-04)

  Bugfixes

•   fix DoS-able regex pattern (#178)

  Miscellaneous changes

•   #183, #184

  eth-account v0.5.8 (2022-06-06)

  Miscellaneous changes

•   #163, #168

  eth-account v0.5.7 (2022-01-27)

  Features

•   Add support for Python 3.9 and 3.10 (#139)

  Bugfixes

•   recover_message now raises an eth_keys.exceptions.BadSignature error if the v, r, and s points are invalid (#142)

  eth-account v0.5.6 (2021-09-22)

  Features

•   An explicit transaction type is no longer required for signing a transaction if we can implicitly determine the transaction type from the transaction parameters (#125)

  Bugfixes

•   When signing a transaction, the regular JSON-RPC structure is now expected as input and is converted to the appropriate rlp transaction structure when signing (#125)

•   Fix string interpolation in ValidationError message of _hash_eip_191_message (#128)

  Improved Documentation

•   Updated docs for sign_transaction to show that transaction type can be implicitly determined based on transaction parameters if one is not provided (#126)

•   Add encode_defunct to list of example message encoders (#127)

  eth-account v0.5.5 (2021-07-21)

  Features

•   Added support for EIP-2718 (Typed Transaction) and EIP-2939 (Access List Transaction) (#115)

•   Added support for EIP-1559 (Dynamic Fee Transaction) (#117)

  Bugfixes

•   Structured messages (EIP-712) new permit leaving some (but not all) domain fields undefined. (#72)

  Internal Changes - for eth-account Contributors

•   Upgrade project template, of note: a new mypy & pydocstyle, and types being exported correctly. (#121)

  Miscellaneous changes

•   #116

  v0.5.3 (2020-08-31)

  Performance improvements

•   RLP encoding/decoding speedup by using rlp v2alpha1, which has a rust implementation. (#104)

  v0.5.2 (2020-04-30)

  Bugfixes

•   Makes sure that the raw txt files needed for Mnemonics get packaged with the release. (#99)

  v0.5.1

Released 2020-04-23

•   Fix a crash in signing typed messages with arrays #97

•   Replace attrdict with NamedTuple to silence a deprecation warning #76

•   Run more doctests & improve docs #94

  v0.5.0

Released 2020-03-30

•   Add Python 3.8 support #86

•   Add opt-in support for Mnemonic seed phrases #87 (NOTE: This API is unaudited and likely to change)

•   Dependency change: support eth-keys v0.3.* #69

  v0.4.0

Released 2019-05-06

•   BREAKING CHANGE: drop python 3.5 (and therefore pypy3 support). #60 (includes other housekeeping)

•   New message signing API: sign_message() and recover_message. #61

•   New eth_account.messages.encode_intended_validator() for EIP-191's Intended Validator message-signing format. #56

•   New eth_account.messages.encode_structured_data() for EIP-712's Structured Data message-signing format. #57

•   Add optional param iterations to encrypt() #52

•   Add optional param kdf to encrypt(), plus env var ETH_ACCOUNT_KDF. Default kdf switched from hmac-sha256 to scrypt. #38

•   Accept "to" addresses formatted as bytes in addition to checksummed, hex-encoded. #36

  v0.3.0

Released July 24, 2018

•   Support eth_keys.datatypes.PrivateKey in params that accept a private key.

•   New docs for Signers

•   Under the hood: add a new BaseAccount abstract class, so that upcoming signing classes can implement it (be on the lookout for upcoming hardware wallet support)

  v0.2.3

Released May 27, 2018

•   Implement __eq__ and __hash__ for LocalAccount, so that accounts can be used in set, or as keys in dict, etc.

  v0.2.2

Released Apr 25, 2018

•   Compatibility with pyrlp v0 and v1

  v0.2.1

Released Apr 23, 2018

•   Accept 'from' in signTransaction, if it matches the sending private key's address

  v0.2.0 (stable)

Released Apr 19, 2018

•   Audit cleanup is complete

•   Stopped requiring chainId, until tooling to automatically derive it gets better (Not that transactions without chainId are potentially replayable on fork chains)

  v0.2.0-alpha.0

Released Apr 6, 2018

•   Ability to sign an already-hashed message

•   Moved eth_sign-style message hashing to eth_account.messages.defunct_hash_message()

•   Stricter transaction input validation, and better error messages. Including: to field must be checksummed.

•   PyPy3 support & tests

•   Upgrade dependencies

•   Moved non-public interfaces to internal module

•   Documentation

•   use getpass instead of typing in password manually

•   eth_account.signers.local.LocalAccount attributes

•   readme improvements

•   more

  v0.1.0-alpha.2

•   Imported the local signing code from web3.py's w3.eth.account

•   Imported documentation and added more

•   Imported tests and pass them

  v0.1.0-alpha.1

•   Launched repository, claimed names for pip, RTD, github, etc

  Contributing

Thank you for your interest in contributing! We welcome all contributions no matter their size. Please read along to learn how to get started. If you get stuck, feel free to ask for help in Ethereum Python Discord server.

  Setting the stage

To get started, fork the repository to your own github account, then clone it to your development machine:

    git clone git@github.com:your-github-username/eth-account.git

Next, install the development dependencies. We recommend using a virtual environment, such as virtualenv.

    cd eth-account
    virtualenv -p python venv
    . venv/bin/activate
    python -m pip install -e ".[dev]"
    pre-commit install

  Running the tests

A great way to explore the code base is to run the tests.

We can then run the core tests with:

    pytest tests/core

To run the integration test cases, we need to install node and the custom cli tool as follows:

    # on Ubuntu
    chmod +x ./tests/integration/js-scripts/setup_node_v22.sh
    ./tests/integration/js-scripts/setup_node_v22.sh  # As sudo
    apt-get install -y nodejs  # As sudo
    cd tests/integration/js-scripts
    npm install

We can then run all tests with:

    pytest tests

  Code Style

We use pre-commit to enforce a consistent code style across the library. This tool runs automatically with every commit, but you can also run it manually with:

    make lint

If you need to make a commit that skips the pre-commit checks, you can do so with git commit --no-verify.

This library uses type hints, which are enforced by the mypy tool (part of the pre-commit checks). All new code is required to land with type hints, with the exception of code within the tests directory.

  Documentation

Good documentation will lead to quicker adoption and happier users. Please check out our guide on how to create documentation for the Python Ethereum ecosystem.

  Pull Requests

It's a good idea to make pull requests early on. A pull request represents the start of a discussion, and doesn't necessarily need to be the final, finished submission.

GitHub's documentation for working on pull requests is available here.

Once you've made a pull request, take a look at the Circle CI build status in the GitHub interface and make sure all tests are passing. In general pull requests that do not pass the CI build yet won't get reviewed unless explicitly requested.

If the pull request introduces changes that should be reflected in the release notes, please add a newsfragment file as explained here.

If possible, the change to the release notes file should be included in the commit that introduces the feature or bugfix.

  Releasing

Releases are typically done from the main branch, except when releasing a beta (in which case the beta is released from main, and the previous stable branch is released from said branch).

  Final test before each release

Before releasing a new version, build and test the package that will be released:

    git checkout main && git pull
    make package-test

This will build the package and install it in a temporary virtual environment. Follow the instructions to activate the venv and test whatever you think is important.

You can also preview the release notes:

    towncrier --draft

  Build the release notes

Before bumping the version number, build the release notes. You must include the part of the version to bump (see below), which changes how the version number will show in the release notes.

    make notes bump=$$VERSION_PART_TO_BUMP$$

If there are any errors, be sure to re-run make notes until it works.

  Push the release to github & pypi

After confirming that the release package looks okay, release a new version:

    make release bump=$$VERSION_PART_TO_BUMP$$

This command will:

•   Bump the version number as specified in .pyproject.toml and setup.py.

•   Create a git commit and tag for the new version.

•   Build the package.

•   Push the commit and tag to github.

•   Push the new package files to pypi.

  Which version part to bump

$$VERSION_PART_TO_BUMP$$ must be one of: major, minor, patch, stage, or devnum.

The version format for this repo is {major}.{minor}.{patch} for stable, and {major}.{minor}.{patch}-{stage}.{devnum} for unstable (stage can be alpha or beta).

If you are in a beta version, make release bump=stage will switch to a stable.

To issue an unstable version when the current version is stable, specify the new version explicitly, like make release bump="--new-version 4.0.0-alpha.1"

You can see what the result of bumping any particular version part would be with bump-my-version show-bump

  Code of Conduct

  Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

  Our Standards

Examples of behavior that contributes to creating a positive environment include:

•   Using welcoming and inclusive language

•   Being respectful of differing viewpoints and experiences

•   Gracefully accepting constructive criticism

•   Focusing on what is best for the community

•   Showing empathy towards other community members

    Examples of unacceptable behavior by participants include:

•   The use of sexualized language or imagery and unwelcome sexual attention or advances

•   Trolling, insulting/derogatory comments, and personal or political attacks

•   Public or private harassment

•   Publishing others' private information, such as a physical or electronic address, without explicit permission

•   Other conduct which could reasonably be considered inappropriate in a professional setting

  Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

  Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

  Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at snakecharmers@ethereum.org. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

  Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

AUTHOR
The Ethereum Foundation

COPYRIGHT
2018-2025, The Ethereum Foundation