search

alchemyplatform / alchemy-sdk-py

30 stars 9 forks source link

readme

Alchemy SDK for Python

An Alchemy SDK to use the Alchemy API.

❗❗ THIS LIBRARY IS IN EARLY ALPHA ❗❗

This library is in active development and does not follow semantic versioning. Breaking changes may be introduced at any time. Please use with caution.

The SDK supports the exact same syntax and functionality of the Web3 eth, making it a 1:1 mapping for anyone using the Web3 eth library. However, it adds a significant amount of improved functionality on top of Web3, such as easy access to Alchemy’s Enhanced and NFT APIs, and quality-of-life improvements such as automated retries.

The SDK leverages Alchemy's hardened node infrastructure, guaranteeing best-in-class node reliability, scalability, and data correctness, and is undergoing active development by Alchemy's engineers.

🙋‍♀️ FEATURE REQUESTS:

We'd love your thoughts on what would improve your web3 dev process the most! If you have 5 minutes, tell us what you want on our Feature Request feedback form, and we'd love to build it for you.

The SDK currently supports the following chains:

Getting started

Use the package manager pip to install alchemy-sdk.

pip3 install alchemy-sdk

After installing the app, you can then import and use the SDK:

from alchemy import Alchemy, Network

# create Alchemy object using your Alchemy api key, default is "demo"
api_key = "your_api_key"

# choose preferred network from Network, default is ETH_MAINNET
network = Network.ETH_MAINNET

# choose the maximum number of retries to perform, default is 5
max_retries = 3

# create Alchemy object
alchemy = Alchemy(api_key, network, max_retries=max_retries)

ℹ️ Creating a unique Alchemy API Key

The public "demo" API key may be rate limited based on traffic. To create your own API key, sign up for an Alchemy account here and use the key created on your dashboard for the first app.

Using the Alchemy SDK

The Alchemy SDK currently supports 2 different namespaces, including:

If you are already using web3.eth, you should be simply able to replace the web3.eth object with alchemy.core and it should work properly.

ℹ️ ENS Name Resolution

The Alchemy SDK supports ENS names (e.g. vitalik.eth) for every parameter where you can pass in a Externally Owned Address, or user address (e.g. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045).

from alchemy import Alchemy
alchemy = Alchemy()

# Access standard Web3 request. Gets latest block hash
block_hash = Alchemy.to_hex(alchemy.core.get_block('latest')['hash'])

# Access Alchemy Enhanced API requests. Gets all transaction receipts for a given block hash.
alchemy.core.get_transaction_receipts(block_hash=block_hash)

# Access the Alchemy NFT API. Gets contract metadata for NFT and gets collection name
contract = "0x01234567bac6ff94d7e4f0ee23119cf848f93245"
print(alchemy.nft.get_contract_metadata(contract).opensea_metadata.collection_name)

The Alchemy class also supports static methods from Web3 object that streamline the development process:

Alchemy Core

The core namespace contains all commonly-used Web3.eth methods.

It also includes the majority of Alchemy Enhanced APIs, including:

Alchemy NFT API

The SDK currently supports the following NFT API endpoints under the alchemy.nft namespace:

Pagination

The Alchemy NFT endpoints return 100 results per page. To get the next page, you can pass in the page_key returned by the previous call.

SDK vs API Differences

The NFT API in the SDK standardizes response types to reduce developer friction, but note this results in some differences compared to the Alchemy REST endpoints:

Usage Examples

Below are a few usage examples.

Getting the NFTs owned by an address

from alchemy import Alchemy
from alchemy.nft import NftFilters

alchemy = Alchemy()

# Get how many NFTs an address owns.
response = alchemy.nft.get_nfts_for_owner('vitalik.eth')
print(response['total_count'])

# Get all the image urls for all the NFTs an address owns.
for nft in response['owned_nfts']:
    print(nft.image)

# Filter out spam NFTs.
nfts_without_spam = alchemy.nft.get_nfts_for_owner('vitalik.eth', exclude_filters=[NftFilters.SPAM])

Getting all the owners of the BAYC NFT

from alchemy import Alchemy

alchemy = Alchemy()

# Bored Ape Yacht Club contract address.
bayc_address = '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D'

# Omit the NFT metadata for smaller payloads.
response = alchemy.nft.get_nfts_for_contract(bayc_address, omit_metadata=True, page_size=5)
for nft in response['nfts']:
    owners = alchemy.nft.get_owners_for_nft(
        contract_address=nft.contract_address, token_id=nft.token_id
    )
    print(f"owners: {owners}, tokenId: {nft.token_id}")

Get all outbound transfers for a provided address

from alchemy import Alchemy

alchemy = Alchemy()
print(alchemy.core.get_token_balances('vitalik.eth'))

Questions and Feedback

If you have any questions, issues, or feedback, please file an issue on GitHub, or drop us a message on our Discord channel for the SDK.

License

MIT