opensea-api

OpenSea NFT API Python 3 wrapper

This an API wrapper library for the OpenSea API written in Python 3.

The library provides a simplified interface to fetch a diverse set of NFT data points from OpenSea.

Supported endpoints

The wrapper covers the following OpenSea API endpoints:

• Single asset (/asset)
• Single asset contract (/asset_contract)
• Single collection (/collection)
• Collection stats (/collection/{slug}/stats)
• Multiple assets] (/assets)
• Multiple collections (/collections)
• Multiple events (/events)
• Multiple bundles (/bundles)

Prerequisite

You need to have an API key to use the OpenSea API, and thus you need one to use this wrapper too. You can request a key here.

NOTE: The API key can take over 4-7 days to be delivered. It also requires you to show the project you are working on.

Installation

Install with pip:

virtualenv env && source env/bin/activate
pip install opensea-api

Upgrade

pip install opensea-api -U

Usage examples

# import the OpenseaAPI object from the opensea module
from opensea import OpenseaAPI

# create an object to interact with the Opensea API (need an api key)
api = OpenseaAPI(apikey="YOUR APIKEY")

# fetch a single asset
contract_address = "0x495f947276749Ce646f68AC8c248420045cb7b5e"
token_id = "66406747123743156841746366950152533278033835913591691491127082341586364792833"
result = api.asset(asset_contract_address=contract_address, token_id=token_id)

# fetch multiple assets
result = api.assets(owner="0xce90a7949bb78892f159f428d0dc23a8e3584d75", limit=3)

# fetch a single contract
result = api.contract(asset_contract_address="0x495f947276749Ce646f68AC8c248420045cb7b5e")

# fetch a single collection
result = api.collection(collection_slug="cryptopunks")

# fetch multiple collections
result = api.collections(asset_owner="0xce90a7949bb78892f159f428d0dc23a8e3584d75", limit=3)

# fetch collection stats
result = api.collection_stats(collection_slug="cryptopunks")

# fetch multiple events
from opensea import utils as opensea_utils

period_end = opensea_utils.datetime_utc(2021, 11, 6, 14, 30)
result = api.events(
    occurred_before=period_end,
    limit=10,
    export_file_name="events.json",
)

# fetch multiple bundles
result = api.bundles(limit=2)

# paginate the events endpoint (cursors are handled internally)
from datetime import datetime, timezone

start_at = datetime(2021, 10, 5, 3, 25, tzinfo=timezone.utc)
finish_at = datetime(2021, 10, 5, 3, 20, tzinfo=timezone.utc)

event_generator = api.events_backfill(start=start_from,
                                      until=finish_at,
                                      event_type="successful")
for event in event_generator:
    if event is not None:
        print(event) # or do other things with the event data

Here's a demo video showcasing the basics.

Documentation

• Wrapper documentation
• OpenSea API documentation

History

0.1.7 (2022-03-26)

• Add support for asset listings and asset offers endpoints
• Add occured_after and collection_editor arguments to events endpoint
• Handle SSL error when making requests
• Docs: add example to paginate the events endpoint (using events_backfill())

0.1.6 (2022-02-25)

• Fix /events endpoint pagination (events_backfill() function) by passing only the cursor hash and not the full URL to the next request.

0.1.5 (2022-02-17)

• Ability to override base_url with any other URL
• Support for cursor-based pagination for /events endpoint (and removed deprecated arguments)
• New function to help paginate the /events endpoint
• Introducing a temporary function to fix the next url problem until OpenSea addresses this issue
• Minor docs updates and cleanup

0.1.3 (2021-12-03)

• Ability to reach all endpoints from one OpenseaAPI object
• API key support (Opensea requires it from now on)

0.1.0 (2021-11-07)

• First release on PyPI.