{"id":2022,"library":"eth-keys","title":"eth-keys: Common API for Ethereum key operations","description":"eth-keys is a Python library providing a common API for Ethereum key operations, including private key, public key, and signature management. It is currently at version 0.7.0 and is actively maintained by the Ethereum Foundation, with development hosted on GitHub.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/ethereum/eth-keys","tags":["ethereum","cryptography","keys","privatekey","publickey","signature","blockchain"],"install":[{"cmd":"pip install eth-keys","lang":"bash","label":"Latest stable version"}],"dependencies":[{"reason":"Utility functions for Ethereum development.","package":"eth-utils","optional":false},{"reason":"Type hinting for Ethereum primitives.","package":"eth-typing","optional":false},{"reason":"Optional backend for faster ECC operations. eth-keys falls back to NativeECCBackend if not installed.","package":"coincurve","optional":true}],"imports":[{"note":"The primary API is accessed via the 'keys' submodule for PrivateKey, PublicKey, and Signature classes.","wrong":"from eth_keys.keys import PrivateKey","symbol":"PrivateKey","correct":"from eth_keys import keys; pk = keys.PrivateKey(...)"},{"symbol":"PublicKey","correct":"from eth_keys import keys; pub_key = keys.PublicKey(...)"},{"symbol":"Signature","correct":"from eth_keys import keys; signature = keys.Signature(...)"},{"note":"Used for explicitly selecting an ECC backend.","symbol":"KeyAPI","correct":"from eth_keys import KeyAPI"}],"quickstart":{"code":"from eth_keys import keys\n\n# Generate a new private key (random bytes in a real scenario)\npk_bytes = b'\\x01' * 32 # Example private key bytes\npk = keys.PrivateKey(pk_bytes)\n\n# Get the public key\npub_key = pk.public_key\n\n# Sign a message\nmessage = b'a message'\nsignature = pk.sign_msg(message)\n\n# Verify the signature\nis_valid = signature.verify_msg(message, pub_key)\nprint(f\"Private Key: {pk.to_hex()}\")\nprint(f\"Public Key: {pub_key.to_hex()}\")\nprint(f\"Ethereum Address: {pub_key.to_checksum_address()}\")\nprint(f\"Signature: {signature.to_hex()}\")\nprint(f\"Signature Valid: {is_valid}\")\n\n# Recover public key from signature\nrecovered_pub_key = signature.recover_public_key_from_msg(message)\nprint(f\"Recovered Public Key Matches: {recovered_pub_key == pub_key}\")","lang":"python","description":"Initializes a PrivateKey object, derives the corresponding PublicKey, signs a message, and verifies the signature. It also demonstrates address generation and public key recovery from a signature."},"warnings":[{"fix":"Update your import statements from `ethereum_keys` to `eth_keys` and install `eth-keys`.","message":"The library and PyPI package were renamed from `ethereum-keys` to `eth-keys` in November 2017. Ensure you are importing from `eth_keys` and not the old package name.","severity":"breaking","affected_versions":"All versions after 2017-11 (effectively 0.2.0 and later)"},{"fix":"For performance-critical applications, install `coincurve` explicitly: `pip install coincurve`.","message":"For optimal performance, `eth-keys` defaults to using the `CoinCurveECCBackend` if the `coincurve` library is installed. However, `coincurve` is not automatically installed as a dependency and must be installed separately. If not installed, it falls back to the pure Python `NativeECCBackend`, which is slower.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure public key input is in the expected 64-byte uncompressed format or use appropriate `from_...` class methods.","message":"The `PublicKey` class constructor expects a 64-byte `bytes` string. Common public key formats like 65-byte (with a leading `\\x04` byte) or 33-byte (compressed, starting with `\\x02` or `\\x03`) require pre-processing (e.g., stripping the first byte for 65-byte format or using `PublicKey.from_compressed_bytes`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always generate private keys using a cryptographically secure random number generator to ensure they are within the valid range and non-zero.","message":"A private key consisting of all zero bytes (`b'\\x00' * 32`) is mathematically invalid for generating a public key in elliptic-curve cryptography. While an address might be derived and accept funds, any transaction signed with this 'private key' will be rejected by the network as having an 'invalid sender'.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Store private keys in environment variables (e.g., `os.environ.get('PRIVATE_KEY', '')`) or a secure vault, and load them at runtime.","message":"Never hardcode, commit to version control, or expose private keys directly in source code. Private keys are critical secrets that should be handled securely, ideally loaded from environment variables or a secure key management system.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}