Derive API

Derive.xyz decentralised perpetuals and options exchange integration with session key authentication.

Preface

Derive.xyz (formerly Lyra) is a self-custodial, high-performance trading platform for perpetuals and options, built on Derive Chain (OP Stack L2).

Supported products:

  • Perpetual futures

  • Options trading

  • Spot trading (coming soon)

Supported collateral:

  • USDC

  • wETH (Wrapped Ethereum)

  • wstETH (Wrapped Liquid Staked Ethereum)

  • wBTC (Wrapped Bitcoin)

Bridging

Derive Chain is an OP Stack L2. To trade on Derive, you need to bridge collateral from other networks to Derive Chain. Derive uses a custom bridge built on Socket smart contracts and L1-L2 messaging infrastructure.

There is only one way and it is very painful way.

Use Rabby wallet. You need to a custom network Lyra mainnet.

Supported source networks:

  • Ethereum

  • Arbitrum

  • Optimism

  • Base

  • HyperEVM

Supported collateral assets (via Socket bridges):

Each asset has dedicated bridge contract addresses on the source chain. For example, USDC from Ethereum mainnet routes through 0x6D303CEE7959f814042D31E0624fB88Ec6fbcC1d.

Mainnet bridging:

The easiest way to deposit is through the Derive web interface. For manual on-chain deposits:

  1. Approve the bridge contract to spend your tokens

  2. Call the deposit function through the bridge contract (e.g. via Etherscan write contract interface)

  3. Wait for cross-chain message relaying to confirm the deposit on Derive Chain

Native ETH deposits:

Native ETH on Derive Chain is needed for transactions that require direct smart contract interaction. Do not use the native bridge for wETH collateral deposits — use Socket bridges for that instead.

Option 1: Superbridge interface (recommended)

Use the Superbridge interface for a user-friendly bridging experience (direct link for Ethereum → Derive Chain ETH bridging).

Option 2: OP Stack native bridge via Etherscan

The native bridge contract is at 0x61e44dc0dae6888b5a301887732217d5725b0bff on Ethereum mainnet.

  1. Go to the bridge contract write proxy on Etherscan

  2. Connect your wallet

  3. Call the deposit function with the amount of ETH you want to bridge

  4. Deposits are confirmed in 5-10 minutes

  5. Withdrawals use the standard OP Stack 7-day challenge period

See this example transaction for reference.

USDC deposits

If you use Derive web interface to deposit USDC, it does not show up on Lyra mainnet. It goes directly to Derive hot wallet.

The best option is to use [Arbirum bridge 0x5e027ad442e031424b5a2c0ad6f656662be32882](https://arbiscan.io/address/0x5e027ad442e031424b5a2c0ad6f656662be32882).

Let’s do transfer for 250 USDC.

  1. Have USDC and ETH (gas) on Arbitrum in a wallet

  2. Go to [USDC contract, write as proxy](https://arbiscan.io/token/0xaf88d065e77c8cc2239327c5edb3a432268e5831#writeProxyContract). Approve 250000000 on 0x5e027ad442e031424b5a2c0ad6f656662be32882.

  3. Go to [bridge contract, write contract](https://arbiscan.io/address/0x5e027ad442e031424b5a2c0ad6f656662be32882#writeContract).

  • receiver: <your wallet addres>

  • payableAmount: 0.000005690851070718 (see getMinFees below)

  • amount: 25000000 - USDC

  • msgGasLimit: 100000 - gas

  • connector: 0x17Fc4c7ea8267044b6D0ACC17a6C049Bed6F8B21

Bridging should happen almost instantly. USDC address on Derive (Lyra mainnet): 0x6879287835A86F50f784313dBEd5E5cCC5bb8481. Add it to your wallet.

After you have bridged over, send the USDC to the Gnosis Safe driving the vault.

getMinFees: this is the ETH amount we need to pay payableAmount for the bridge contract. Above payableAmount is a test figure tripled. To get a real number:

Bridge timing:

  • From Layer 2 networks (Arbitrum, Optimism, Base): 2-5 minutes

  • From Ethereum mainnet: 5-10 minutes

Delays result from cross-chain message relaying required to securely confirm deposits on Derive Chain.

Daily limits:

Global daily limits apply to deposits and withdrawals. For example, the USDC mainnet fast connector enforces $10M in deposits and $1M in withdrawals per day.

Fast withdrawals:

Derive supports fast withdrawals that bypass the standard 7-day OP Stack challenge period. Global daily limits apply to fast withdrawals to maintain self-custody protections inherent to the fraud proof system.

For more details, see the Derive deposit documentation, bridging FAQ, and supported networks.

Depositing from Safe

After you have a session key created from Safe, you can log in to the Derive UI with this session.

  1. Cleear site data for derive.xyz in your browser if needed (to restart)

  2. Import session key to your Rabby wallet

  3. Connect to Derive

  4. On the first connect dialog, choose Session key

Now you can move the USDC from the vault’s Safe wallet to the subaccount for trading.

  • In left-nav, after login ,you see “Recover ⚠️”

  • You should see the USDC that was deposited in [step 3](#step-3-make-a-test-deposit-usdc)

  • Click “Recover”

  • The “Recover Balance” dialog should default to the subaccount from step 4.b. and the full amount of USDC.

  • Click “Recover USDC” and sign the signature request in your wallet

Authentication

Derive uses a three-tier wallet system:

  1. Owner EOA - Your original Ethereum wallet

  2. Derive Wallet - LightAccount smart contract wallet on Derive Chain (ERC-4337)

  3. Session Keys - Temporary wallets for API access

Session keys must be registered by the owner and support three permission levels:

  • read_only - View account data only

  • account - Manage orders and settings

  • admin - Full access including trading and withdrawals

Authentication headers use EIP-191 personal-sign (encode_defunct) with uppercase header names (X-LYRAWALLET, X-LYRATIMESTAMP, X-LYRASIGNATURE).

Account creation

Important

Account creation requires the Derive web interface. The web UI deploys an ERC-4337 LightAccount via a gas-sponsored UserOperation. This step cannot be automated due to bot detection on the SIWE endpoint and paymaster access controls.

  1. Visit https://testnet.derive.xyz/ (testnet) or https://derive.xyz/ (mainnet)

  2. Connect your Ethereum wallet (MetaMask, etc.)

  3. The interface will deploy your LightAccount and register the initial session key

  4. Find your Derive Wallet address: Home → Developers → “Derive Wallet”

Getting started

Once your account exists via the web interface, use the session key from the developer page to authenticate API requests:

from eth_account import Account
from eth_defi.derive.authentication import DeriveApiClient
from eth_defi.derive.account import fetch_account_collaterals

# Use credentials from the Derive web interface developer page
client = DeriveApiClient(
    owner_account=Account.from_key("0x..."),        # Owner wallet private key
    derive_wallet_address="0x...",                    # From developer page
    session_key_private="0x...",                      # From developer page
    is_testnet=True,
)

# Fetch account data
collaterals = fetch_account_collaterals(client)
for col in collaterals:
    print(f"{col.token}: {col.available}")

Environment variables

For testing, set these environment variables:

# Owner wallet private key (from web UI wallet)
DERIVE_OWNER_PRIVATE_KEY=0x...

# Session key private key (from testnet developer page)
DERIVE_SESSION_PRIVATE_KEY=0x...

# Derive wallet address (from testnet developer page)
DERIVE_WALLET_ADDRESS=0x...

Finding your private key

DERIVE_OWNER_PRIVATE_KEY is the private key of the Ethereum wallet you used to connect to the Derive web interface. To export it:

  • MetaMask: Account menu → “Account details” → “Show private key” → enter password

  • Rabby: Account address → three-dot menu → “Export Private Key” → enter password

  • Other wallets: Look for “Export private key” in account/security settings

DERIVE_SESSION_PRIVATE_KEY and DERIVE_WALLET_ADDRESS are found on the Derive web interface under Home → Developers.

API modules

eth_defi.derive.api

Derive.xyz public API functions.

eth_defi.derive.historical

DuckDB persistence for Derive funding rate and open interest history.

eth_defi.derive.onboarding

Derive.xyz account onboarding and session key management.

eth_defi.derive.session

HTTP session management for Derive API.

eth_defi.derive.authentication

Derive API client with session key authentication.

eth_defi.derive.account

Derive account balance and collateral reading functions.

eth_defi.derive.constants

Derive.xyz API constants and configuration.