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, request an API key here.
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:
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 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 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
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.
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:
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.
Retrieving assets
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
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.
Retrieving a single asset
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.
Retrieving contracts
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
.
Retrieving events
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
Retrieving accounts
The /accounts endpoint provides a list of accounts that OpenSea tracks. The endpoint will return the following fields:
accounts
List of Account Object
Getting Started
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/
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.
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.
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.
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.
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: