OpenSea

Build your own marketplace in minutes

OpenSea provides a one-stop shop for creating your own customizable marketplace for your ERC721 or non-fungible token (NFT) project. Allow users to smoothly buy and sell your items, get custom stats and analytics, and earn revenue when your items get traded.

Guides
Suggest Edits

API Overview

 

In addition to an instant marketplace for ERC721-based items, OpenSea provides an HTTP API for fetching non-fungible ERC721 assets based on a set of query parameters. Monitoring every ERC721 contract and caching metadata for each individual token can be a lot of overhead for wallets and websites that wish to display all of a user's collectibles, gaming items, and other assets. By aggregating this data in an easy-to-consume API, we make it easy for wallets and other sites.

Here are a couple of products that have integrated the OpenSea API:
Coinbase Wallet
Trust Wallet
Balance
CryptoGoods
ToknTalk
CKBox
Vault Wallet
Bitski
Portis
Amberdata

We provide this API free of charge, but ask in return that you give credit to OpenSea on your site, and link to the OpenSea marketplace from the assets you display (where appropriate). Please see our Logos & Brand Guidelines for images that you can use to credit OpenSea.

This API is rate-limited. If you'd like to use it in a production environment, contact us to request an API key.

Suggest Edits

Asset Object

 

The primary object in the OpenSea API is the asset, which represents a unique digital item whose ownership is managed by the blockchain. The below CryptoSaga hero is an example of an asset shown on OpenSea.

Here's an overview of some of the fields contained in an asset:

Field name
Description

token_id

The token ID of the ERC721 asset

image_url

An image for the item

background_color

The background color to be displayed with the item

name

Name of the item

external_link

External link to the original website for the item

asset_contract

Dictionary of data on the contract itself (see asset contract section)

owner

Dictionary of data on the owner (see account section)

traits

A list of traits associated with the item (see traits section)

last_sale

When this item was last sold (null if there was no last sale)

Traits

Traits are special properties on the item, that can either be numbers or strings. Below is an example of how OpenSea displays the traits for a specific item.

Here are some of the fields contained in a trait:

trait_type

The name of the trait (for example color)

value

The value of this trait (can be a string or number)

Asset contracts

Asset contracts contain data about the contract itself, such as the CryptoKitties contract or the CryptoFighters contract. Here are the field associated with an asset contract:

address

Address of the asset contract

name

Name of the asset contract

symbol

Symbol, such as CKITTY

image_url

Image associated with the asset contract

description

Description of the asset contract

external_link

Link to the original website for this contract

Suggest Edits

Event Object

 

Asset events represent state changes that occur for assets. This includes putting them on sale, bidding on them, selling, them, cancelling sales, composing assets, transferring them, and more.

Suggest Edits

Account Object

 

Accounts represent wallet addresses and associated usernames, if the owner entered one on OpenSea. Here's an overview of the fields contained in an account:

Field name
Description

address

The Ethereum wallet address that uniquely identifies this account.

profile_img_url

An auto-generated profile picture to use for this wallet address. To get the user's Ethmoji avatar, use the Ethmoji SDK.

user

An object containing username, a string for the the OpenSea username associated with the account. Will be null if the account owner has not yet set a username on OpenSea.

config

A string representing public configuration options on the user's account, including affiliate and affiliate_requested for OpenSea affiliates and users waiting to be accepted as affiliates.

Suggest Edits

Retrieving assets

 
gethttps://api.opensea.io/api/v1/assets
curl --request GET \
  --url https://api.opensea.io/api/v1/assets?owner=0x0239769a1adf4def9f07da824b80b9c4fcb59593&order_by=current_price&order_direction=asc
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "count": 11,
    "assets": [
      {
      	"token_id": "8123",
      	"name": "Gerard Piqué",
      	...
      	"current_price": "6561000000000000"
      },
      {
        "token_id": "6169",
        "name": "Manuel Neuer",
        ...
        "current_price": "10530000000000000"
      }
     	...
    ]
}

Query Params

owner
string

The address of the owner of the assets

token_ids
array of strings

An array of token IDs to search for (e.g. ?token_ids=1&token_ids=209). Will return a list of assets with token_id matching any of the IDs in this array.

asset_contract_address
string

The NFT contract address for the assets

order_by
string

How to order the assets returned. If the ordering option isn't implied by last_sale or num_sales, the API will return its value in an attribute with the same name. By default, the API returns the fastest ordering (contract address and token id). Options you can set are token_id, listing_date (the last off-chain sell order's creation date), current_price (the lowest off-chain sell order's current price), current_escrow_price (the lowest price for an escrowed asset on sale), top_bid (the highest off-chain buy order's W-ETH amount), sale_date (the last sale's transaction's timestamp), sale_count (number of sales), visitor_count (number of unique visitors), and sale_price (the last sale's total_price)

order_direction
string

Can be asc for ascending or desc for descending

trait__{value_type}__{trait_type}
string

Search for assets with specific traits, e.g. trait__int__generation=0 to search for Gen 0 assets. value_type can be either int, float, or string and represents the data type of the value. trait_name is dependent on the type of asset being searched, but options will appear in the results and also in each category's sidebar on opensea.io/assets

on_sale
boolean

Set on_sale to true to retrieve only assets for sale, i.e. ones with an open sell order, bundle for sale, or escrow auction. Set to false to show assets with no known sell order or escrow auction

offset
string

Offset

limit
string

Limit

Headers

X-API-KEY
string

Your API Key (contact us to request one!)

 

To retrieve assets from our API, call the /assets endpoint with the desired filter parameters.

Note: sorting by listing_date or current_price will filter out assets that are not on sale, along with assets being sold on an escrow contract (where the true owner doesn't own the asset anymore). To sort assets by their escrowed auction price, use current_escrow_price for your order_by parameter. You'll need to do this to display and sort auctions from the CryptoKitties contract, for example.

Auctions created on OpenSea don't use an escrow contract, which enables gas-free auctions and allows users to retain ownership of their items while they're on sale. So this is just a heads up in case you notice some assets from opensea.io not appearing in the API.

The endpoint will return the following fields:

estimated_count

Total number of assets returned (estimate)

assets

List of Asset Object

Suggest Edits

Retrieving bundles

Bundles are groups of items for sale on OpenSea. You can buy them all at once in one transaction, and you can create them without any transactions or gas, as long as you've already approved the assets inside.

 
gethttps://api.opensea.io/api/v1/bundles/
curl --request GET \
  --url https://api.opensea.io/api/v1/bundles/
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "estimated_count": 364,
    "bundles": [
        {
            "maker": {
                "user": {...},
                "profile_img_url": "https://storage.googleapis.com/opensea-static/opensea-profile/11.png",
                "address": "0xe96a1b303a1eb8d04fb973eb2b291b8d591c8f72",
                "config": "affiliate"
            },
            "slug": "strikerkitty",
            "assets": [
                {
                    "token_id": "503",
                    "image_url": "...",
                    "name": "#503 unique.",
                  	...
                },
                {
                    "token_id": "109",
                    "name": "Medhi Benatia",
                    ...
                }
            ],
            "name": "StrikerKitty",
            "description": "",
            "image_url": null,
            "external_link": "",
            "permalink": "https://opensea.io/bundles/strikerkitty"
        }
   ]
}

Query Params

on_sale
boolean

If set to true, only show bundles currently on sale. If set to false, only show bundles that have been sold or cancelled.

owner
string

Account address of the owner of a bundle (and all assets within)

asset_contract_address
string

Contract address of one or more of the assets in a bundle

token_ids
array of strings

A list of token IDs for showing only bundles with at least one of the token IDs in the list

search
string

Search within the "name" or "description" of a bundle

limit
int32

For pagination: how many results to return

offset
int32

For pagination: the index of the result to start at (beginning with 0)

 
Suggest Edits

Retrieving a single asset

 
gethttps://api.opensea.io/api/v1/asset/asset_contract_address/token_id/
curl --request GET \
  --url https://api.opensea.io/api/v1/asset/0x06012c8cf97bead5deae237070f9587f8e7a266d/556324/
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "token_id": "556324",
    "image_url": "https://storage.googleapis.com/opensea-prod.appspot.com/0x06012c8cf97bead5deae237070f9587f8e7a266d%2F556324.svg",
    "background_color": "dfdffa",
    "name": "喵喵",
    "description": "Ciao. I'm 喵喵. I collect skorts and I love cucumber salad...",
    "external_link": "https://www.cryptokitties.co/kitty/556324",
    "asset_contract": {
        "address": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
        "name": "CryptoKitties",
        ...
    },
    "owner": {
        "user": null,
        "profile_img_url": "https://storage.googleapis.com/opensea-static/opensea-profile/10.png",
        "address": "0xcc601972761b5f153e697a34d2921e5cca090ed4",
        ...
    },
    "auctions": [...],
    "traits": [...],
    "last_sale": {
        "winner_account": {...},
        "seller": {...},
        "created_date": "2018-05-21T07:42:05.131227",
        "total_price": "2949040509259260",
        ...
    },
    "num_sales": 2,
    "orders": [...],
    "related_assets": [...]
}

Path Params

asset_contract_address
string
required

Address of the contract for this NFT

token_id
string
required

Token ID for this item

Headers

X-API-KEY
string

Your API Key (contact us to request one!)

 

To retrieve an individual from our API, call the /asset endpoint with the address of the asset's contract and the token id. The endpoint will return an Asset Object.

Suggest Edits

Retrieving contracts

 
gethttps://api.opensea.io/api/v1/asset_contracts
curl --request GET \
  --url https://api.opensea.io/api/v1/asset_contracts/
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[{
        "address": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
        "name": "CryptoKitties",
        "symbol": "CKITTY",
        "image_url": "https://storage.googleapis.com/opensea-static/cryptokitties-logo.png",
        "description": "CryptoKitties is a game centered around breedable, collectible, and oh-so-adorable creatures we call CryptoKitties! Each cat is one-of-a-kind and 100% owned by you; it cannot be replicated, taken away, or destroyed.",
        "external_link": "https://www.cryptokitties.co/",
        "wiki_link": "https://opensea.readme.io/page/cryptokitties",
        "stats": {
            "seven_day_volume": 131.620722711119,
            "seven_day_change": 0.0,
            "total_volume": 45012.4514676574,
            "count": 820390,
            "market_cap": 15179.09336577036,
            "average_price": 0.115436669644085,
            "items_sold": 389932
        },
        "traits": {...}
}]

Headers

X-API-KEY
string

Your API Key (contact us to request one!)

 

The /asset_contracts endpoint provides a list of all the asset contracts supported by OpenSea. Each asset_contract in the returned area follows the schema of the previously-described asset_contract.

Suggest Edits

Retrieving a single contract

 
gethttps://api.opensea.io/api/v1/asset_contract/asset_contract_address
curl --request GET \
  --url https://api.opensea.io/api/v1/asset_contract/0xf766b3e7073f5a6483e27de20ea6f59b30b28f87
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[{
        "address": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
        "name": "CryptoKitties",
        "symbol": "CKITTY",
        "image_url": "https://storage.googleapis.com/opensea-static/cryptokitties-logo.png",
        "description": "CryptoKitties is a game centered around breedable, collectible, and oh-so-adorable creatures we call CryptoKitties! Each cat is one-of-a-kind and 100% owned by you; it cannot be replicated, taken away, or destroyed.",
        "external_link": "https://www.cryptokitties.co/",
        "wiki_link": "https://opensea.readme.io/page/cryptokitties",
        "stats": {
            "seven_day_volume": 131.620722711119,
            "seven_day_change": 0.0,
            "total_volume": 45012.4514676574,
            "count": 820390,
            "market_cap": 15179.09336577036,
            "average_price": 0.115436669644085,
            "items_sold": 389932
        },
        "traits": {...}
}]

Path Params

asset_contract_address
string
required

Address of the contract

Headers

X-API-KEY
string

Your API Key (contact us to request one!)

 
Suggest Edits

Retrieving events

 
gethttps://api.opensea.io/api/v1/events
curl --request GET \
  --url https://api.opensea.io/api/v1/events/?event_type=successful
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "estimated_count": 2332539,
    "asset_events": [
        {
            "id": 5005754,
            "transaction": {
                "from_account": {...},
                "to_account": {...},
                "transaction_hash": "0xc9306fa50bb6a61af1b46d3ed6ae48704f55412cf689bf9127dbe537b09841f3",
                "transaction_index": "68",
                "block_number": "6171110",
                "block_hash": "0x0f6d166b22ef93fc72003f7ab627c5f0a77fc04baec00e31b1a34fe1d38f269b",
                "timestamp": "2018-08-18T18:55:21",
                ...
            },
            "asset": {
                "token_id": "3628",
                "image_url": "https://storage.googleapis.com/opensea-prod.appspot.com/0x4fece400c0d3db0937162ab44bab34445626ecfe/3628.png",
                "name": "Annie Einstein (L9)",
                "asset_contract": {...},
                "owner": {...}
            },
            "winner_account": {...},
            "seller": {...},
            "contract_address": "0x7be8076f4ea4a4ad08075c2508e481d6c946d12b",
            "event_type": "successful",
            "bid_amount": null,
            "total_price": "161676394353158989",
            ...
        }
   ]
}

Query Params

asset_contract_address
string

The NFT contract address for the assets for which to show events

token_id
int32

The token's id to optionally filter by

account_address
string

A user account's wallet address to filter for events on an account

event_type
string

The event type to filter. Can be created for new auctions, successful for sales, cancelled, bid_entered, bid_withdrawn, transfer, approve, or composition_created

only_opensea
boolean

Restrict to events on OpenSea auctions. Can be true or false

offset
int32

Offset for pagination

limit
string

Limit for pagination

Headers

X-API-KEY
string

Your API Key (contact us to request one!)

 

The /events endpoint provides a list of events that occur on the assets that OpenSea tracks. The "event_type" field indicates what type of event it is (transfer, successful auction, etc). The endpoint will return the following fields:

estimated_count

Total number of events returned (estimate)

asset_events

List of Event Object

Suggest Edits

Retrieving accounts

 
gethttps://api.opensea.io/api/v1/accounts
curl --request GET \
  --url https://api.opensea.io/api/v1/accounts/
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[{
    "count": 2332539,
    "accounts": [
        {
            "user": {
                "username": "alex2"
            },
            "profile_img_url": "https://storage.googleapis.com/opensea-static/opensea-profile/11.png",
            "address": "0xe96a1b303a1eb8d04fb973eb2b291b8d591c8f72",
            "config": "affiliate"
        },
        {
            "user": null,
            "profile_img_url": "https://storage.googleapis.com/opensea-static/opensea-profile/18.png",
            "address": "0x0239769a1adf4def9f07da824b80b9c4fcb59593",
            "config": ""
        }
   ]
}

Query Params

address
string

A partial address to search for. Will return accounts with addresses that contain this prefix (case-insensitive).

username
string

A partial username to search for. Will return registered OpenSea accounts with usernames that contain this term (case-insensitive).

addresses
array of strings

An array of addresses to search on (e.g. ?addresses=0x123&addresses=0x456). Will return a list of accounts with addresses matching any of the addresses in this array.

offset
int32

Offset for pagination

limit
string

Limit for pagination

Headers

X-API-KEY
string

Your API Key (contact us to request one!)

 

The /accounts endpoint provides a list of accounts that OpenSea tracks. The endpoint will return the following fields:

accounts

List of Account Object

Suggest Edits

Rinkeby API Overview

 

The Rinkeby API is used for browsing non-fungible assets on the Ethereum Rinkeby test network. Creating and purchasing assets on this network requires Rinkeby ether, which is free. To acquire some, visit https://faucet.rinkeby.io/ and authenticate using your Twitter account.

The API is identical to the OpenSea mainnet API, except the base URL is https://rinkeby-api.opensea.io.

This API is rate-limited. If you'd like to use it in a production environment, contact us to request an API key.