Skip to main content
Custom Oracle lets qualified Builders bring additional Index Price sources into Permissionless Listing. It is designed for markets that need pricing beyond Orderly’s standard CEX feeds and platform oracle sources. There are two Custom Oracle modes:
ModeBest forHow prices reach Orderly
Builder OracleBuilders with their own pricing model, index service, or aggregation backend.The Builder pushes prices to Orderly over WebSocket.
Bring Your Own Key (BYOK) OracleBuilders that want to use their own provider account for a supported oracle provider such as Pyth or Stork.Orderly uses the Builder’s provider credentials to pull prices from the oracle provider.
Both modes can be selected as Index Price sources during Permissionless Listing. They can also be combined with CEX feeds and platform oracle sources, with each selected source assigned a weight.

​
Builder Oracle

Builder Oracle is the push-based Custom Oracle mode. The Builder owns the price calculation and pushes the resulting Index Price to Orderly. Use Builder Oracle when you have your own pricing infrastructure, for example:
  • an internal index service;
  • an exchange aggregation service;
  • a pricing model for a long-tail asset;
  • an RWA data provider integration.

​
How Builder Oracle works

  1. The Builder registers a feed for a base_ccy, such as BTC, AAPL, or another supported asset.
  2. Orderly creates the Builder Oracle source for that Builder. The source is identified as ORACLE_<broker_id>.
  3. The Builder connects to Orderly’s oracle WebSocket and publishes indexpricefeed messages.
  4. The feed can be selected as an Index Price source when listing a market.
Builder Oracle feeds are created as active and private by default. This lets the Builder test the feed privately before making it available to other Builders.

​
Visibility

Builder Oracle visibility is controlled per feed:
  • Private feeds are visible only to the Builder that owns the feed.
  • Public feeds can be selected by other Builders when they list markets.
If another Builder selects a public Builder Oracle feed, that Builder is responsible for understanding the availability and quality risk of the third-party feed.

​
Builder responsibilities

With Builder Oracle, the Builder is responsible for operating the price feed:
  • keep the WebSocket connection active during the relevant market session;
  • publish valid prices at the required frequency;
  • monitor stale data, skipped prices, and feed availability;
  • use multiple sources where possible to reduce single-source risk.
If a Builder Oracle feed becomes unhealthy, the affected market can be restricted or placed into reduce-only mode according to the Permissionless Listing risk rules.

​
Bring Your Own Key (BYOK) Oracle

Bring Your Own Key (BYOK) Oracle is the provider-key mode. Instead of building and operating a WebSocket price publisher, the Builder connects a supported oracle provider account to Orderly. Use BYOK Oracle when you want to rely on a supported oracle provider, but use your own provider credentials and account relationship. Initial BYOK provider support includes Pyth and Stork. Chainlink support is planned for a future rollout.

​
How BYOK Oracle works

  1. The Builder selects a supported BYOK provider, such as Pyth or Stork.
  2. The Builder submits the provider credentials through Orderly’s private API.
  3. Orderly validates the provider credentials and creates a provider-specific source, such as PYTH_<broker_id> or STORK_<broker_id>.
  4. The Builder registers feeds under that BYOK provider.
  5. Orderly pulls prices from the provider and makes the feed available for listing source selection.
BYOK feeds have their own status and health model. The Builder controls whether the feed is active or inactive, while Orderly reports provider-side health such as missing symbols, pull failures, invalid keys, or quota issues.

​
BYOK responsibilities

With BYOK Oracle, the Builder does not need to run a WebSocket publisher, but still needs to manage the provider relationship:
  • keep provider credentials valid;
  • monitor key status and provider health;
  • manage which BYOK feeds are active;
  • understand provider quota, coverage, and availability constraints.

​
Custom Oracle and RWA markets

Both Builder Oracle and BYOK Oracle can be used with supported real-world asset (RWA) markets. RWA support currently covers US markets only, including regular US stock hours, extended US stock hours, and US futures hours. Support for additional RWA market sessions, including Hong Kong (HK), China (CN), and Korea (KR), is planned to be added gradually. RWA trading sessions are configured at the listed market level through market_session; they are not configured on the oracle feed itself.

​
Integration flow

For the API sequence, feed setup, source selection, RWA market_session, and listing submit example, see Permissionless Listing with Custom Oracle.