Stream API Overview

Overview

The Element Stream API is a websocket-based service that enables developers to receive events as they occur, ensuring that your service has the most up-to-date details without the need to continuously poll for updates. Currently Stream API, your service can subscribe to receive different types of order events, you can subscribe according to the chain and the market.

The Stream API currently supports the following set of events:

• Item minted - item created
• Item listed - an item listed for sale on the Element marketplace
• Item sold - sale of an item on the Element marketplace
• Item cancel - cancellation of an ask order on the Element marketplace
• Item bid cancel - cancellation of an offer order on the Element marketplace
• Item received offer - offer received on an item in the Element marketplace
• Collection offer - offer on a collection
• Item transferred - transfer of an item between wallets
• Item metadata updated - update detected on the metadata provided in token name, imgUrl for an item
• Pending transfer - item is in transferring

The Stream API is available for both Mainnet and Testnet networks:

Network	Endpoint	Supported Blockchains
Mainnet	wss://feeds.element.market/websocket	Ethereum, Polygon mainnet, Bsc mainnet, Avalanche mainnet
Testnet	wss://feeds-test.element.market/websocket	Goerli, Polygon testnet (Mumbai), Bsc testnet, Avalanche testnet

Subscription message format

   
   {"method": "SUBSCRIBE","topic":"collection:*","events":[],"payload":{"chains":["ethereum","bsc"],"markets":["element"]}}

• Method：
  - SUBSCRIBE
  - UNSUBSCRIBE
• Topic：
  - collection:
  - collection:* subscribe all collections.
• Events:
  - Such as: "events":["item_sold"]
  - [] means to subscribe to all events
• payload.chains: filter chains,
  - When subscribing to all collections, chain information is required
  - Currently supported values ethereum, polygon, bsc, avalanche
  - When the collection slug is specified, the chain information is invalid
• payload.markets: filter markets,
  - Currently supported values element, opensea, looksrare
• Subscription is based on topic, sending subscription information of the same topic will overwrite the previous subscription

FAQs

Do I need an API key for Mainnet and Testnet to use the Stream API?

If you want to use the API in Mainnet, an API key is required. If you don’t have an API key, Please submit a request here.

Do the events received from my subscriptions count towards any rate limits on my API key?

No, events are not counted towards any API rate limits.

What is the typical streaming rate that I should expect from the Stream API?

The streaming rate depends on a range of factors - from the amount of collections that you’re monitoring to the type and amount of events that you’re subscribed to. For instance, if you’re subscribed to receive bid events across all collections on Element, you’ll be receiving messages at a significantly higher rate than you will for a subscription to order cancellations on a small collection.

Should I expect that some events can be received out of order?

You should be prepared to handle receipt of events out of order as we don’t guarantee delivery of events in the order that they occur.

Is it possible for some events to be missing?

The Stream API is a best-effort delivery messaging system and messages that are not received due to connection errors will not be re-sent. So it’s possible that there can be missing messages if the socket connection is unstable.

What blockchains does the Stream API support?

The following blockchains are supported on Mainnet networks:

Ethereum
Polygon mainnet
Bsc mainnet
Avalanche mainnet
Arbitrum mainnet
Zksync mainnet
Linea mainnet
Linea mainnet
Starknet mainnet
Opbnb mainnet
Base mainnet

The following blockchains are supported on Testnet networks:

Goerli
Polygon testnet (Mumbai)
Bsc testnet
Avalanche testnet

The following market are supported on Mainnet networks:

Element
Opensea
Looksrare