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
Go Wallet
Pillar Wallet

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, request an API key here.

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)

display_type

How this trait will be displayed (options are number, boost_percentage, boost_number). See the adding metadata section for more details

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

{
    "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

asset_contract_addresses
array of strings

An array of contract addresses to search for (e.g. ?asset_contract_addresses=0x1...&asset_contract_addresses=0x2...). Will return a list of assets with contracts matching any of the addresses in this array. If "token_ids" is also specified, then it will only return assets that match each (address, token_id) pairing, respecting order.

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:

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

{
    "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 all the assets in a bundle. Only works for homogenous bundles, not mixed ones.

asset_contract_addresses
array of strings

An array of contract addresses to search for (e.g. ?asset_contract_addresses=0x1...&asset_contract_addresses=0x2...). Will return a list of bundles with assets having contracts that match ALL of the addresses in this array. Useful for querying for mixed bundles, e.g. ones with CryptoKitties AND CK Talisman statues.

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

{
    "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

[{
        "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": {...}
}]

Query Params

owner
string

If specified, will return contracts where the owner owns at least one asset belonging to each contract.

offset
int32

For pagination. Number of contracts offset from the beginning of the result list.

limit
int32

For pagination. Maximum number of contracts to return.

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

[{
        "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

{
    "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

auction_type
string

Filter by an auction type. Can be english for English Auctions, dutch for fixed-price and declining-price sell orders (Dutch Auctions), or min-price for CryptoPunks bidding auctions.

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

[{
    "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

Suggest Edits

Getting Started with the Orderbook

This page will help you get started with OpenSea Orderbook.

 

You can use this endpoint to query the OpenSea orderbook for buy orders (bids and offers) and sell orders (auctions, listings, and bundles). If you're using JavaScript, you can also use the SDK (https://github.com/ProjectOpenSea/opensea-js#fetching-orders), or fork the starter project, pictured below.

The orderbook follows the Wyvern Protocol schema. Some of the terminology might be new to you. We'll do a brief overview here, but contact us via email or Discord if you'd like additional help.

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

The OpenSea orderbook, in dapp form. https://ships-log.herokuapp.com/

The OpenSea orderbook, in dapp form. https://ships-log.herokuapp.com/

Suggest Edits

Terminology

What are orderbooks and how do they work?

 

An orderbook is just a list of orders that an exchange uses to record the interest of buyers and sellers. On OpenSea, most actions are off-chain, meaning they generate orders that are stored in the orderbook and can be fulfilled by a matching order from another user.

Signatures vs Transactions

On Ethereum, whenever blockchain state is changed (e.g. when an asset moves from one account to another, or funds are traded between accounts), a transaction needs to occur. All transactions require Ether as payment, and in this form the payment is called gas. On many other marketplaces, users have to pay gas to list items for sale or to purchase them, but OpenSea is heavily optimized to prevent users from having to spend gas.

When a user lists an item for sale, they simply sign their intent to exchange the item for payment. This intent is stored in the OpenSea orderbook as a sell order, and does not create a transaction. When a buyer comes along and decides to accept the listing price, the buyer can sign a buy order as a counter-order to be matched with the sell order.

The buyer can pay the gas to create a transaction to match the two orders together, or the buyer can have OpenSea match it for them in the case of English Auctions. In that scenario, no user pays gas, and both orders are stored in the orderbook. In all other scenarios, only the first order (the "maker" order) is stored.

Makers and Takers

All orders have a maker address field and taker address field. A maker is the first mover in a trade. Makers either declare intent to sell an item, or they declare intent to buy by bidding on one. A taker is the counterparty who responds to a maker's order by, respectively, either buying the item or accepting a bid on it.

Another way of putting this is that the maker is the user that is "creating liquidity," and the taker is the user that comes along and clears it away. On OpenSea, orders can be public, where the taker is the null address (0x0000000000000000000000000000000000000000) and anyone can take the order, or private, where the taker is a specific user's account. Private orders can only be fulfilled by a specific account - no other account is allowed by the smart contract.

Timestamps

Orders have three time components on them: created_date, listing_time, and expiration_time. The created_date is the date the order was made. OpenSea.js, along with camel-casing these properties for JavaScript, will auto-convert created_date into a UTC timestamp called createdTime, which is the number of seconds since the UNIX epoch (similar to listingTime and expirationTime).

The listing_time is the timestamp that the order will start to be fulfillable. For most orders this is right when they're made, but for English Auctions it's when the user wants the auction to end (this is added security to make sure it's not matchable until then).

The expiration_time is the timestamp that the order will no longer be fulfillable ever. For most orders this is when the user wants them to expire, but for English Auctions it's set to a point later in the future, just so that OpenSea's servers have enough time to match them with the highest bid.

Suggest Edits

Retrieving orders

How to fetch orders from the OpenSea orderbook

 
gethttps://api.opensea.io/wyvern/v1/orders
curl --request GET \
  --url https://api.opensea.io/wyvern/v1/orders
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.opensea.io/wyvern/v1/orders' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.opensea.io/wyvern/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.opensea.io/wyvern/v1/orders");

xhr.send(data);
import requests

url = "https://api.opensea.io/wyvern/v1/orders"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

asset_contract_address
string

Filter by smart contract address for the asset category

payment_token_address
string

Filter by the address of the smart contract of the payment token that is accepted or offered by the order

maker
string

Filter by the order maker's wallet address

taker
string

Filter by the order taker's wallet address. Orders open for any taker have the null address as their taker.

owner
string

Filter by the asset owner's wallet address

only_english
boolean

Only show English Auction sell orders, which wait for the highest bidder. OpenSea matches the highest bid with these orders when the current time passes listing_time.

bundled
boolean

Only show orders for bundles of assets

include_invalid
boolean

Include orders marked invalid by the orderbook, typically due to makers not owning enough of the token/asset anymore

listed_after
date-time

Only show orders listed after this timestamp. Seconds since the Unix epoch.

listed_before
date-time

Only show orders listed before this timestamp. Seconds since the Unix epoch.

token_id
string

Filter by the token ID of the order's asset

token_ids
array of strings

Filter by a list of token IDs for the order's asset

side
int32

Filter by the side of the order. 0 for buy orders and 1 for sell orders.

sale_kind
int32

Filter by the kind of sell order. 0 for fixed-price sales or min-bid auctions, and 1 for declining-price Dutch Auctions. NOTE: use only_english=true for filtering for only English Auctions

limit
int32

Number of orders to return per page (for pagination)

offset
int32

Number of orders to offset by (for pagination)

order_by
string

How to sort the orders. Can be created_date for when they were made, or eth_price to see the lowest-priced orders first (converted to their ETH values)

order_direction
string

Can be asc or desc for ascending or descending sort. For example, to see the cheapest orders, do order_direction asc and order_by eth_price.

 
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/api/v1/.

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

Suggest Edits

Request an API key

 

This API is rate-limited. You can experiment with it and omit the key, but if you'd like to use it in a production environment, please request a free API key here:

powered by Typeform