4657-derive

name	@4657/derive
version	1.0.0
description	derive

Derive Skill

Derive is a self-custodial onchain options & perpetuals DEX built on the OP Stack (Derive Chain / Lyra Finance). It supports options, perpetuals, and spot across BTC, ETH, SOL, and more.

API Endpoints

	REST	WebSocket
Mainnet	https://api.lyra.finance	wss://api.lyra.finance/ws
Testnet	https://api-demo.lyra.finance	wss://api-demo.lyra.finance/ws

All endpoints speak JSON-RPC 2.0. Public endpoints need no auth. Private endpoints require a signed login.

⚠️ Geo-restriction (US block)

The Lyra/Derive API blocks Region US. Starchild containers exit the US by default, so every request must be routed through sc-vpn (Malaysia or other non-US region).

PROXY_R = {"http": "http://my:[e-mail]:8080", "https": "http://my:[e-mail]:8080"}
PROXY_W = dict(http_proxy_host="sc-vpn.internal", http_proxy_port=8080,
               http_proxy_auth=("my","x"), proxy_type="http")

requests.post(URL, json=..., proxies=PROXY_R)           # REST
websocket.create_connection(WS_URL, **PROXY_W)          # WebSocket

Without the proxy you get code 403 "You are in a restricted region that violates our terms of service."

Protocol Constants

⚠️ WARNING: The official derive_action_signing example ships with TESTNET constants. Using testnet values on mainnet returns code 14014 "Signature does not match data" with no other hint.

MAINNET (verified from on-chain Matching contract 0xeB8d770ec18DB98Db922E9D83260A585b9F0DeAD)

DOMAIN_SEPARATOR     = "0xd96e5f90797da7ec8dc4e276260c7f3f87fedf68775fbe1ef116e996fc60441b"
ACTION_TYPEHASH      = "0x4d7a9f27c403ff9c0f19bce61d76d82f9aa29f8d6d4b0c5474607d9770d1af17"
TRADE_MODULE_ADDRESS = "0xB8D20c2B7a1Ad2EE33Bc50eF10876eD3035b5e7b"
MATCHING_ADDRESS     = "0xeB8d770ec18DB98Db922E9D83260A585b9F0DeAD"
DEPOSIT_MODULE       = "0x9B3FE5E5a3bcEa5df4E08c41Ce89C4e3Ff01Ace3"
WITHDRAW_MODULE      = ""  # query via explorer when needed

TESTNET (from official example, do NOT use on mainnet)

DOMAIN_SEPARATOR     = "0x9bcf4dc06df5d8bf23af818d5716491b995020f377d3b7b64c29ed14e3dd1105"
ACTION_TYPEHASH      = "0x4d7a9f27c403ff9c0f19bce61d76d82f9aa29f8d6d4b0c5474607d9770d1af17"
TRADE_MODULE_ADDRESS = "0x87F2863866D85E3192a35A73b388BD625D83f2be"

How to re-derive any mainnet contract

import requests
# Find by name on the Lyra explorer
r = requests.get("https://explorer.lyra.finance/api/v2/search?q=TradeModule")
# Pull DOMAIN_SEPARATOR via JSON-RPC eth_call (selector for `domainSeparator()` = 0xf698da25)
import requests
payload = {"jsonrpc":"2.0","method":"eth_call","id":1,
  "params":[{"to":"0xeB8d770ec18DB98Db922E9D83260A585b9F0DeAD","data":"0xf698da25"},"latest"]}
r = requests.post("https://rpc.lyra.finance", json=payload)
print(r.json()["result"])  # the canonical mainnet DOMAIN_SEPARATOR

Authentication Flow

1. Smart contract wallet (NOT your EOA): In the Derive UI go to Home → Developers → "Derive Wallet" to find it
2. Session key: A temporary EOA you authorize to sign on your behalf
3. WS login: Sign a timestamp with your session key private key, send as public/login

from derive_action_signing import utils
from web3 import Web3

web3 = Web3()
login_params = utils.sign_ws_login(web3, DERIVE_WALLET, SESSION_KEY_PRIVATE_KEY)
# sends: { timestamp, wallet, signature }

Execution: cost of crossing spread on illiquid options

Derive options often have very wide bid/ask spreads (30%+ of mark) because the book is mostly market-maker quotes, not organic flow. Crossing the spread (taking the ask on a buy) eats the full MM markup PLUS the taker fee.

Rule of thumb for any order with premium > $5:

1. Default: ALO (post-only) limit at MID price ((bid + ask) / 2 or near mark). Pays maker fee (0.0001) instead of taker (0.0003). Won't fill instantly but saves real money on illiquid strikes.
2. Only cross the spread when you need the fill NOW — e.g. urgent hedge with hours to expiry, or thesis needs immediate protection.
3. Estimate cost before you submit: spread cost = (ask - mark) × contracts. If that's >5% of premium, post mid instead.

Example post-only order:

payload = {
    "instrument_name": "ETH-20260521-2000-P",
    "direction": "buy",
    "order_type": "limit",
    "mmp": False,
    "time_in_force": "gtc",
    "is_atomic_signing": False,
    # Note: post-only is controlled via order params, check Derive docs for current field name
    **action.to_json(),
}

Instrument Naming

Options:  {CURRENCY}-{YYYYMMDD}-{STRIKE}-{C|P}   e.g. ETH-20250131-3000-C
Perps:    {CURRENCY}-PERP                          e.g. BTC-PERP
Spot/ERC: {SYMBOL}                                 e.g. ETH

Key Public Endpoints (no auth)

import requests, json

BASE = "https://api.lyra.finance"

# All live options for ETH
r = requests.post(f"{BASE}/public/get_instruments",
    json={"expired": False, "instrument_type": "option", "currency": "ETH"},
    headers={"accept": "application/json", "content-type": "application/json"})

# Ticker with Greeks
r = requests.post(f"{BASE}/public/get_ticker",
    json={"instrument_name": "ETH-PERP"},
    headers={"accept": "application/json", "content-type": "application/json"})

# Order book
r = requests.post(f"{BASE}/public/get_orderbook",
    json={"instrument_name": "ETH-20250131-3000-C", "depth": 10},
    headers={"accept": "application/json", "content-type": "application/json"})

# All tickers for a currency
r = requests.post(f"{BASE}/public/get_tickers",
    json={"currency": "ETH", "instrument_type": "option"},
    headers={"accept": "application/json", "content-type": "application/json"})

Key Private Endpoints (auth required via WS)

After public/login over WebSocket:

# Positions
{"method": "private/get_positions", "params": {"subaccount_id": <id>, "currency": "ETH"}}

# Collaterals
{"method": "private/get_collaterals", "params": {"subaccount_id": <id>}}

# Open orders
{"method": "private/get_open_orders", "params": {"subaccount_id": <id>}}

# Order history
{"method": "private/get_order_history", "params": {"subaccount_id": <id>}}

# My trades
{"method": "private/get_trades", "params": {"subaccount_id": <id>}}

# Subaccounts
{"method": "private/get_subaccounts", "params": {"wallet": DERIVE_WALLET}}

Placing an Order (Full Flow)

Requires: derive_action_signing, web3, websocket-client (pip install derive_action_signing web3 websocket-client)

import json, requests
from decimal import Decimal
from websocket import create_connection
from web3 import Web3
from derive_action_signing import SignedAction, TradeModuleData, utils

# --- Config ---
DERIVE_WALLET       = "0xYOUR_SMART_CONTRACT_WALLET"
SESSION_KEY_PRIV    = "0xYOUR_SESSION_KEY_PRIVATE_KEY"
SUBACCOUNT_ID       = 12345

# --- Protocol constants (MAINNET — verified on-chain) ---
DOMAIN_SEPARATOR    = "0xd96e5f90797da7ec8dc4e276260c7f3f87fedf68775fbe1ef116e996fc60441b"
ACTION_TYPEHASH     = "0x4d7a9f27c403ff9c0f19bce61d76d82f9aa29f8d6d4b0c5474607d9770d1af17"
TRADE_MODULE_ADDRESS = "0xB8D20c2B7a1Ad2EE33Bc50eF10876eD3035b5e7b"
WS_URL              = "wss://api.lyra.finance/ws"
REST                = "https://api.lyra.finance"

web3 = Web3()
session_wallet = web3.eth.account.from_key(SESSION_KEY_PRIV)

# 1. Get instrument details
resp = requests.post(f"{REST}/public/get_instruments",
    json={"expired": False, "instrument_type": "option", "currency": "ETH"},
    headers={"content-type": "application/json"})
instrument = resp.json()["result"][0]   # pick the first live option

# 2. Build + sign action
action = SignedAction(
    subaccount_id=SUBACCOUNT_ID,
    owner=DERIVE_WALLET,
    signer=session_wallet.address,
    signature_expiry_sec=utils.MAX_INT_32,
    nonce=utils.get_action_nonce(),
    module_address=TRADE_MODULE_ADDRESS,
    module_data=TradeModuleData(
        asset_address=instrument["base_asset_address"],
        sub_id=int(instrument["base_asset_sub_id"]),
        limit_price=Decimal("100"),    # USD price for option
        amount=Decimal("1"),           # contracts
        max_fee=Decimal("1000"),
        recipient_id=SUBACCOUNT_ID,
        is_bid=True,                   # True=buy, False=sell
    ),
    DOMAIN_SEPARATOR=DOMAIN_SEPARATOR,
    ACTION_TYPEHASH=ACTION_TYPEHASH,
)
action.sign(session_wallet.key)

# 3. Connect, login, submit
ws = create_connection(WS_URL)

def ws_rpc(ws, method, params, id_str):
    ws.send(json.dumps({"method": method, "params": params, "id": id_str}))
    while True:
        msg = json.loads(ws.recv())
        if msg["id"] == id_str:
            return msg

login_resp = ws_rpc(ws, "public/login",
    utils.sign_ws_login(web3, DERIVE_WALLET, SESSION_KEY_PRIV),
    "login")
assert "result" in login_resp, f"Login failed: {login_resp}"

order_resp = ws_rpc(ws, "private/order", {
    "instrument_name": instrument["instrument_name"],
    "direction": "buy",
    "order_type": "limit",
    "mmp": False,
    "time_in_force": "gtc",
    **action.to_json(),
}, "order1")
print(json.dumps(order_resp["result"]["order"], indent=2))
ws.close()

Required Credentials (save to workspace/.env)

DERIVE_WALLET=0x...          # Smart contract wallet on Derive Chain (NOT your EOA)
DERIVE_SESSION_KEY=0x...     # Private key of your session key EOA
DERIVE_SUBACCOUNT_ID=12345   # Integer subaccount ID

To find your wallet: derive.xyz → Home → Developers → "Derive Wallet" To create a session key: derive.xyz → Settings → Session Keys → Create

Env Check Pattern

import os
from dotenv import load_dotenv
load_dotenv("/data/workspace/.env")

DERIVE_WALLET    = os.environ["DERIVE_WALLET"]
SESSION_KEY_PRIV = os.environ["DERIVE_SESSION_KEY"]
SUBACCOUNT_ID    = int(os.environ["DERIVE_SUBACCOUNT_ID"])

Available Currencies

BTC, ETH, SOL, HYPE, and others. Use public/get_currencies to get the live list.

Greeks (Options)

The get_ticker and get_tickers responses include for options:

• delta, gamma, vega, theta, rho — standard BSM Greeks
• iv — implied volatility
• mark_price, index_price, best_bid_price, best_ask_price

Rate Limits

Per account TPS limits — check with private/get_account. WebSocket is preferred for trading; REST for reading.

Testnet Setup

Use https://api-demo.lyra.finance (REST) and wss://api-demo.lyra.finance/ws (WS) for testing. The testnet has different protocol constants — look them up at docs.derive.xyz/reference/protocol-constants.

Scripts Location

Working scripts go in skills/derive/scripts/. Share output in output/derive/.