fetch_open_interest_onchain

Documentation for eth_defi.derive.api.fetch_open_interest_onchain function.

fetch_open_interest_onchain(w3, contract_address, block_number, sub_id=0)

Fetch open interest for a Derive perp from on-chain state.

Calls openInterest(uint256 subId) on the perp asset contract at the specified historical block. The Derive Chain RPC endpoint (https://rpc.derive.xyz) is an archive node that supports historical eth_call going back to chain genesis.

This is the only way to retrieve historical open interest data — the public /public/statistics REST endpoint always returns the current live value regardless of any end_time parameter.

The returned value is in the instrument’s base currency with 18 decimal places (e.g. ETH for ETH-PERP, BTC for BTC-PERP).

Example:

from web3 import Web3
from eth_defi.derive.api import fetch_open_interest_onchain
from eth_defi.derive.constants import DERIVE_MAINNET_RPC_URL

w3 = Web3(Web3.HTTPProvider(DERIVE_MAINNET_RPC_URL))
# ETH-PERP contract on Derive Mainnet
oi = fetch_open_interest_onchain(
    w3,
    "0xAf65752C4643E25C02F693f9D4FE19cF23a095E3",
    block_number=36000000,
)
print(oi)  # e.g. Decimal('3186.42')
Parameters

  • w3 (web3.main.Web3) – Web3 instance connected to Derive Chain (https://rpc.derive.xyz, chain ID 957).

  • contract_address (str) – The base_asset_address for the instrument, as returned by the /public/get_all_instruments endpoint.

  • block_number (int) – Block number at which to read state. Use estimate_block_at_timestamp() to convert a UTC timestamp to a block number.

  • sub_id (int) – Sub-asset identifier. Always 0 for perpetuals.

Returns

Open interest in the base currency as a Decimal, or None if zero (instrument not yet active at that block).

Raises

Exception – Transient RPC errors (connection failures, timeouts, rate limits) propagate to the caller so the sync loop can abort before advancing the watermark past a hole. Only ContractLogicError (contract revert — meaning the block predates contract deployment) is caught and treated as zero OI.

Return type

decimal.Decimal | None