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.

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:

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:

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:

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.

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:

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:

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.

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.

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:

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

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.

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.

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.

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.

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: