Metadata-Version: 2.1
Name: opensea-api
Version: 0.1.7
Summary: Python 3 wrapper for the OpenSea NFT API
Home-page: https://github.com/zseta/python-opensea
Author: Attila Toth
Author-email: hello@attilatoth.dev
Maintainer: Attila Toth
Maintainer-email: hello@attilatoth.dev
License: MIT license
Project-URL: Documentation, https://opensea-api.attilatoth.dev
Project-URL: Source, https://github.com/zseta/python-opensea
Keywords: opensea,nft,non fungible token,crypto
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests (>=2.26.0)

# OpenSea NFT API Python 3 wrapper
This an API wrapper library for the [OpenSea API](https://docs.opensea.io/reference/api-overview) 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](https://docs.opensea.io/reference/retrieving-a-single-asset))
* Single asset contract ([/asset_contract](https://docs.opensea.io/reference/retrieving-a-single-contract))
* Single collection ([/collection](https://docs.opensea.io/reference/retrieving-a-single-collection))
* Collection stats ([/collection/{slug}/stats](https://docs.opensea.io/reference/retrieving-collection-stats))
* Multiple assets] ([/assets](https://docs.opensea.io/reference/getting-assets))
* Multiple collections ([/collections](https://docs.opensea.io/reference/retrieving-collections))
* Multiple events ([/events](https://docs.opensea.io/reference/retrieving-asset-events))
* Multiple bundles ([/bundles](https://docs.opensea.io/reference/retrieving-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.](https://docs.opensea.io/reference/request-an-api-key) <br><br>
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:
```bash
virtualenv env && source env/bin/activate
pip install opensea-api
```

### Upgrade
```bash
pip install opensea-api -U
```

## Usage examples

```python
# 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.](https://www.youtube.com/watch?v=ga4hTqNRjfw)

## Documentation
* [Wrapper documentation](https://opensea-api.attilatoth.dev)
* [OpenSea API documentation](https://docs.opensea.io/reference/api-overview)



# History

## 0.1.7 (2022-03-26)
* Add support for [asset listings](https://docs.opensea.io/reference/asset-listings)
    and [asset offers](https://docs.opensea.io/reference/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.


