Integration Guide

Overview

Hypersurface is an on-chain options protocol for covered calls and cash-secured puts. You sell options to the protocol and receive premium. The trade lifecycle is:

1. Price    →  GET /optionsPrices (indicative pricing + Greeks)
2. Quote    →  POST /quote (protocol co-signs the order)
3. Approve  →  ERC-20 approve on TradeExecutor (one-time per token)
4. Trade    →  HedgedPool.trade() (on-chain, collateral pulled automatically)
5. Hold     →  Position locked until 08:00 UTC expiry
6. Settle   →  Controller.operate() (unlock collateral after expiry)
7. Withdraw →  HedgedPool.withdrawVaultCollateral() (get your tokens back)

You can also close early at any time by buying back the option (step 4 with positive amount).

Key Terms

Term	Description
HedgedPool	Entry point contract for trading
TradeExecutor	Handles collateral transfers (you approve this, never call it directly)
Controller	Gamma protocol vault operations (settlement, reads)
oToken	ERC-20 representing a specific option series
Vault	Gamma margin vault holding your collateral and short position
Premium	Payment received when selling an option (in USD₮0/USDC)
Covered Call	Sell upside on an asset you hold as collateral
Cash-Secured Put	Sell downside protection, backed by stablecoin collateral

---

Setup

Chain Configuration

HyperEVM

Property	Value
Chain ID	999
RPC URL	https://rpc.hyperliquid.xyz/evm
Block Explorer	https://explorer.hyperliquid.xyz
Native Currency	HYPE (18 decimals)
API Base URL	https://market-api-sh.hypersurface.io

Base

Property	Value
Chain ID	8453
RPC URL	https://mainnet.base.org
Block Explorer	https://basescan.org
Native Currency	ETH (18 decimals)
API Base URL	https://market-api-base.hypersurface.io

Contract Addresses

HyperEVM (Chain 999)

Contract	Address	Purpose
HedgedPool	0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F	Entry point for trade(), buy-back premium approval target
TradeExecutor	0x25dD9EAae2e0b118a2CefdD229233654840BA7A0	Collateral approval target for sell trades
Controller	0x7730e6bfbfCE8Ff0b7a50b72D0601c209Eb818C4	Vault settlement via operate(), vault state reads
MarginPool	0x7D2e4b4d7ba55C423F5CCe194ae8194eFD1C6e35	Holds collateral and oTokens
Auction	0xf077393F8d2e6fB8151a53c5209686544a0E3749	Dutch IV-auction venue for takers

Base (Chain 8453)

Contract	Address	Purpose
HedgedPool	0x68893915f202e5DA2Ef01493463c50B2f68Df56d	Entry point for trade(), buy-back premium approval target
Controller	0x037F16e360db0053BAAcD78cDCfe735Af05f39bF	Vault settlement via operate(), vault state reads

Token Addresses

HyperEVM (Chain 999) -- Underlyings

Asset	Symbol	Address	Decimals
HYPE	wHYPE	0x5555555555555555555555555555555555555555	18
BTC	UBTC	0x9fdbda0a5e284c32744d2f17ee5c74b284993463	8
ETH	UETH	0xbe6727b535545c67d5caa73dea54865b92cf7907	18
SOL	USOL	0x068f321fa8fb9f0d135f290ef6a3e2813e1c8a29	9
XPL	UXPL	0x33af3c2540ba72054e044efe504867b39ae421f5	18
PUMP	UPUMP	0x27ec642013bcb3d80ca3706599d3cda04f6f4452	6
ENA	UENA	0x58538e6a46e07434d7e7375bc268d3cb839c0133	18
KNTQ	KNTQ	0x000000000000780555bd0bca3791f89f9542c2d6	18
kHYPE	kHYPE	0xfd739d4e423301ce9385c1fb8850539d657c296d	18

Premium token: USD₮0 at 0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb (6 decimals)

Base (Chain 8453) -- Underlyings

Asset	Symbol	Address	Decimals
ETH	WETH	0x4200000000000000000000000000000000000006	18
BTC	cbBTC	0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf	8

Premium token: USDC at 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (6 decimals)

Note: Strike increments are set on-chain and may change. To discover current active strikes and expiries, query the subgraph:

{
  otokens(where: { expiryTimestamp_gt: "CURRENT_UNIX_TIMESTAMP" }) {
    strikePrice
    expiryTimestamp
    isPut
    underlyingAsset { symbol }
  }
}

Or test strikes via the API — GET /optionsPrices?symbol=BTC-03APR26-65500-C will return pricing if that strike exists.

---

API Reference

No authentication required. Trades are authenticated by the EIP-712 signature embedded in the order itself.

Base URLs

Chain	Base URL
HyperEVM	https://market-api-sh.hypersurface.io
Base	https://market-api-base.hypersurface.io

Endpoints

Method	Path	Description
GET	/optionsPrices	Indicative pricing for an option symbol
POST	/quote	Co-signed order ready for on-chain submission
GET	/underlyingPrices	Spot prices for underlying assets
GET	/health	Vol surface and price feed health status

Use symbol (singular) as the query parameter, not symbols.

Symbol Format

{UNDERLYING}-{DDMMMYY}-{STRIKE}-{C|P}

Part	Description	Examples
UNDERLYING	Asset symbol	HYPE, ETH, BTC, SOL, XPL, PUMP, ENA, KNTQ, kHYPE
DDMMMYY	Expiry date (08:00 UTC)	Use an available expiry date
STRIKE	Strike price in USD	25, 3000, 100000
C|P	Call or Put	C, P

Build-your-own URL guide:

1. Pick the base URL for your chain.

2. Pick your asset, an available expiry date, an available strike (query the subgraph or test via the API), and C or P.

3. Assemble: https://market-api-sh.hypersurface.io/optionsPrices?symbol=HYPE-28MAR26-25-C

Strikes are set on-chain. Query the subgraph or test via the API to confirm availability. HYPE-28MAR26-25.50-C is invalid if that strike does not exist.

Note: To discover available expiry dates, query the subgraph for active oTokens:

{
  otokens(first: 100, where: { expiryTimestamp_gt: "CURRENT_UNIX_TIMESTAMP" }) {
    expiryTimestamp
  }
}

Or try dates programmatically — the API returns an error for invalid expiries.

GET /optionsPrices

curl "https://market-api-sh.hypersurface.io/optionsPrices?symbol=HYPE-28MAR26-25-C"

Try it live

Response:

{
  "result": {
    "HYPE-28MAR26-25-C": {
      "ask": 3.45,
      "bid": 2.81,
      "premium": 3.10,
      "probability_otm": 0.72
    }
  }
}

Field	Type	Description
ask	float	Ask price in USD (cost to buy back)
bid	float	Bid price in USD (premium you receive when selling)
premium	float	Mid/mark premium in USD
probability_otm	float	Probability of expiring out-of-the-money (0 to 1)

Add &greeks=true for delta, gamma, theta, vega, and implied volatility:

curl "https://market-api-sh.hypersurface.io/optionsPrices?symbol=HYPE-28MAR26-25-C&greeks=true"

Try it live

POST /quote

POST /quote returns a co-signed order ready for on-chain execution.

Covered call request:

curl -X POST "https://market-api-sh.hypersurface.io/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "sign": true,
    "order": {
      "account": "0xYourWalletAddress",
      "poolAddress": "0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F",
      "underlying": "0x5555555555555555555555555555555555555555",
      "collateral": "0x5555555555555555555555555555555555555555",
      "referrer": "0x0000000000000000000000000000000000000000",
      "legs": [
        {
          "symbol": "HYPE-28MAR26-25-C",
          "amount": -100000000
        }
      ]
    }
  }'

Request Fields:

Field	Type	Required	Description
sign	boolean	Yes	Must be true to receive a co-signed order
order.account	address	Yes	Your wallet address (EOA) or your contract address
order.poolAddress	address	Yes	HedgedPool address for the target chain
order.underlying	address	Yes	Underlying token contract address
order.collateral	address	Yes	Collateral token address (underlying for calls, stablecoin for puts)
order.referrer	address	Yes	Referral address, or 0x0000000000000000000000000000000000000000
order.legs[0].symbol	string	Yes	Option symbol in UNDERLYING-DDMMMYY-STRIKE-C/P format
order.legs[0].amount	integer	Yes	Quantity scaled by 1e8. Negative = sell to protocol, Positive = buy back

The legs array must contain exactly 1 element. Multi-leg trades are not supported.

Response:

{
  "result": {
    "order": {
      "account": "0xYourWalletAddress",
      "poolAddress": "0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F",
      "underlying": "0x5555555555555555555555555555555555555555",
      "collateral": "0x5555555555555555555555555555555555555555",
      "referrer": "0x0000000000000000000000000000000000000000",
      "validUntil": 1711612500,
      "nonce": "72800786012994460315784275982664160146348565358057253425559922099161226915767",
      "legs": [
        {
          "strike": "2500000000",
          "expiration": 1711612800,
          "isPut": false,
          "amount": "-100000000",
          "premium": "-3100000",
          "fee": "0"
        }
      ],
      "signature": { "r": "0x...", "s": "0x...", "v": "0x1b" },
      "coSignatures": []
    }
  }
}

Response Fields:

Field	Scale	Description
strike	1e8	Strike price. "2500000000" = $25.00
expiration	unix	Expiry timestamp (08:00 UTC)
isPut	boolean	true = put, false = call
amount	1e8	Signed quantity. "-100000000" = selling 1 option
premium	1e6	Signed premium. "-3100000" = you receive $3.10
fee	1e6	Protocol fee in premium token units
validUntil	unix	Quote expiry. Request a fresh quote immediately before your on-chain tx
nonce	uint256	Unique nonce for replay protection
signature	-	Protocol's EIP-712 co-signature

Put request -- set collateral to the stablecoin address:

{
  "sign": true,
  "order": {
    "account": "0xYourWalletAddress",
    "poolAddress": "0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F",
    "underlying": "0x5555555555555555555555555555555555555555",
    "collateral": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
    "referrer": "0x0000000000000000000000000000000000000000",
    "legs": [
      {
        "symbol": "HYPE-28MAR26-25-P",
        "amount": -100000000
      }
    ]
  }
}

GET /health

curl "https://market-api-sh.hypersurface.io/health?symbol=HYPE"

Try it live

{
  "HYPE": {
    "model": { "status": "OK", "timestamp": 1774634618 },
    "underlyingPrice": { "status": "OK", "timestamp": 1774634578 }
  },
  "currentTimestamp": 1774634622
}

If a model or price feed status is not "OK", pricing for that asset may be unavailable. Wait for recovery before trading.

GET /underlyingPrices

curl "https://market-api-sh.hypersurface.io/underlyingPrices?symbol=HYPE&symbol=ETH&symbol=BTC"

Try it live

{
  "result": {
    "HYPE": { "price": 38.21, "timestamp": 1774634639 },
    "ETH": { "price": 1978.00, "timestamp": 1774634639 },
    "BTC": { "price": 65666.93, "timestamp": 1774634639 }
  }
}

---

EOA Trading Guide

Complete start-to-finish guide for wallet users. See the Full Python Example for a copy-paste-ready version with all ABIs inline.

1

Approval Targets

Action	Token to Approve	Approve To	HyperEVM Address
Sell covered call	Underlying (e.g. wHYPE)	TradeExecutor	0x25dD9EAae2e0b118a2CefdD229233654840BA7A0
Sell cash-secured put	Stablecoin (USD₮0)	TradeExecutor	0x25dD9EAae2e0b118a2CefdD229233654840BA7A0
Buy back (close position)	Premium token (USD₮0)	HedgedPool	0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F

Collateral approvals go to TradeExecutor. Buy-back premium approvals go to HedgedPool. Approving the wrong contract will revert your transaction.

2

Get a Signed Quote

import requests
from web3 import Web3

API_URL = "https://market-api-sh.hypersurface.io"
HEDGED_POOL = "0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F"
WHYPE = "0x5555555555555555555555555555555555555555"
TRADE_EXECUTOR = "0x25dD9EAae2e0b118a2CefdD229233654840BA7A0"
ADDRESS_ZERO = "0x0000000000000000000000000000000000000000"

w3 = Web3(Web3.HTTPProvider("https://rpc.hyperliquid.xyz/evm"))
account = w3.eth.account.from_key("YOUR_PRIVATE_KEY")

quote_resp = requests.post(f"{API_URL}/quote", json={
    "sign": True,
    "order": {
        "account": account.address,
        "poolAddress": HEDGED_POOL,
        "underlying": WHYPE,
        "collateral": WHYPE,
        "referrer": ADDRESS_ZERO,
        "legs": [{"symbol": "HYPE-28MAR26-25-C", "amount": -100000000}],
    },
})
quote_resp.raise_for_status()
api_order = quote_resp.json()["result"]["order"]

3

Approve Collateral

ERC20_ABI = [
    {
        "inputs": [
            {"name": "spender", "type": "address"},
            {"name": "amount", "type": "uint256"},
        ],
        "name": "approve",
        "outputs": [{"name": "", "type": "bool"}],
        "stateMutability": "nonpayable",
        "type": "function",
    }
]

token = w3.eth.contract(address=Web3.to_checksum_address(WHYPE), abi=ERC20_ABI)

tx = token.functions.approve(
    Web3.to_checksum_address(TRADE_EXECUTOR),
    10 * 10**18,  # 10 wHYPE
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": 999,
})

signed = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
w3.eth.wait_for_transaction_receipt(tx_hash)

4

Execute Trade

trade() function signature:

function trade(
    IOrderUtil.Order calldata order,
    uint256 traderVaultId,
    bool autoCreateVault
) external nonReentrant returns (address oToken);

trade() returns the address of the oToken that was traded. An eth_call simulation returns it directly; from a sent transaction, read it from the emitted events.

Parameter	Type	Description
order	Order	Complete signed order from /quote response
traderVaultId	uint256	Your vault ID. Use 0 on first trade
autoCreateVault	bool	true on first trade to auto-create a vault

contract_order = format_order_for_contract(api_order)  # See Reference section

HEDGED_POOL_ABI = [
    {
        "inputs": [
            {
                "components": [
                    {"name": "account", "type": "address"},
                    {"name": "poolAddress", "type": "address"},
                    {"name": "underlying", "type": "address"},
                    {"name": "collateral", "type": "address"},
                    {"name": "referrer", "type": "address"},
                    {"name": "validUntil", "type": "uint256"},
                    {"name": "nonce", "type": "uint256"},
                    {
                        "name": "legs",
                        "type": "tuple[]",
                        "components": [
                            {"name": "strike", "type": "uint256"},
                            {"name": "expiration", "type": "uint256"},
                            {"name": "isPut", "type": "bool"},
                            {"name": "amount", "type": "int256"},
                            {"name": "premium", "type": "int256"},
                            {"name": "fee", "type": "uint256"},
                        ],
                    },
                    {
                        "name": "signature",
                        "type": "tuple",
                        "components": [
                            {"name": "v", "type": "uint8"},
                            {"name": "r", "type": "bytes32"},
                            {"name": "s", "type": "bytes32"},
                        ],
                    },
                    {
                        "name": "coSignatures",
                        "type": "tuple[]",
                        "components": [
                            {"name": "v", "type": "uint8"},
                            {"name": "r", "type": "bytes32"},
                            {"name": "s", "type": "bytes32"},
                        ],
                    },
                ],
                "name": "order",
                "type": "tuple",
            },
            {"name": "traderVaultId", "type": "uint256"},
            {"name": "autoCreateVault", "type": "bool"},
        ],
        "name": "trade",
        "outputs": [{"name": "", "type": "address"}],
        "stateMutability": "nonpayable",
        "type": "function",
    },
]

hedged_pool = w3.eth.contract(
    address=Web3.to_checksum_address(HEDGED_POOL),
    abi=HEDGED_POOL_ABI,
)

tx = hedged_pool.functions.trade(
    contract_order,
    0,     # traderVaultId (0 = auto-create)
    True,  # autoCreateVault
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": 999,
    "gas": 1_500_000,
})

signed = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
print(f"Trade tx: {tx_hash.hex()}")

5

Parse Vault ID from Receipt

trade_executor = w3.eth.contract(
    address=Web3.to_checksum_address(TRADE_EXECUTOR),
    abi=[{
        "anonymous": False,
        "inputs": [
            {"indexed": True, "name": "trader", "type": "address"},
            {"indexed": False, "name": "vaultId", "type": "uint256"},
        ],
        "name": "MarginVaultOpened",
        "type": "event",
    }],
)
events = trade_executor.events.MarginVaultOpened().process_receipt(receipt)
vault_id = events[0]["args"]["vaultId"]
print(f"Vault ID: {vault_id}")

6

Buy Back (Close Early)

Buy back your option using trade() with a positive amount. You pay the current premium to close, then withdraw your collateral.

Approve HedgedPool for premium payment:

USDT0 = "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"

premium_token = w3.eth.contract(
    address=Web3.to_checksum_address(USDT0), abi=ERC20_ABI,
)

tx = premium_token.functions.approve(
    Web3.to_checksum_address(HEDGED_POOL),
    100 * 10**6,  # 100 USD₮0
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": 999,
})

signed = account.sign_transaction(tx)
w3.eth.send_raw_transaction(signed.raw_transaction)

Request a buy-back quote (positive amount):

quote_resp = requests.post(f"{API_URL}/quote", json={
    "sign": True,
    "order": {
        "account": account.address,
        "poolAddress": HEDGED_POOL,
        "underlying": WHYPE,
        "collateral": WHYPE,
        "referrer": ADDRESS_ZERO,
        "legs": [{"symbol": "HYPE-28MAR26-25-C", "amount": 100000000}],  # positive = buy back
    },
})
api_order = quote_resp.json()["result"]["order"]
contract_order = format_order_for_contract(api_order)

Execute the buy-back:

tx = hedged_pool.functions.trade(
    contract_order,
    vault_id,  # your existing vault ID
    False,     # do NOT auto-create
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": 999,
    "gas": 500_000,
})

signed = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
w3.eth.wait_for_transaction_receipt(tx_hash)

Then withdraw your collateral.

7

Settlement After Expiry

Options expire at 08:00 UTC on their expiry date. After expiry, you must settle your vault before you can withdraw collateral.

Settlement uses Controller.operate() with the SettleVault action type (7).

CONTROLLER = "0x7730e6bfbfCE8Ff0b7a50b72D0601c209Eb818C4"
ADDRESS_ZERO = "0x0000000000000000000000000000000000000000"

CONTROLLER_ABI = [
    {
        "inputs": [
            {
                "components": [
                    {"name": "actionType", "type": "uint8"},
                    {"name": "owner", "type": "address"},
                    {"name": "secondAddress", "type": "address"},
                    {"name": "asset", "type": "address"},
                    {"name": "vaultId", "type": "uint256"},
                    {"name": "amount", "type": "uint256"},
                    {"name": "index", "type": "uint256"},
                    {"name": "data", "type": "bytes"},
                ],
                "name": "actions",
                "type": "tuple[]",
            }
        ],
        "name": "operate",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function",
    }
]

controller = w3.eth.contract(
    address=Web3.to_checksum_address(CONTROLLER),
    abi=CONTROLLER_ABI,
)

# Settle one or more vaults in a single transaction
actions = [
    {
        "actionType": 7,  # SettleVault
        "owner": account.address,
        "secondAddress": account.address,  # payout destination
        "asset": Web3.to_checksum_address(ADDRESS_ZERO),
        "vaultId": vault_id,
        "amount": 0,
        "index": 0,
        "data": b"",
    }
    # Add more entries to batch-settle multiple vaults
]

tx = controller.functions.operate(actions).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": 999,
})

signed = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
w3.eth.wait_for_transaction_receipt(tx_hash)

8

Settlement Payout

Option Type	Condition	You Receive
Covered Call	OTM (spot < strike)	Your underlying collateral returned
Covered Call	ITM (spot > strike)	Strike price in stablecoin (you delivered the underlying)
Cash-Secured Put	OTM (spot > strike)	Your stablecoin collateral returned
Cash-Secured Put	ITM (spot < strike)	Underlying asset (you bought at the strike price)

9

Withdraw Collateral

After settlement or a buy-back, withdraw collateral from your vault.

# Read vault state to get collateral info
CONTROLLER_READ_ABI = [
    {
        "inputs": [
            {"name": "owner", "type": "address"},
            {"name": "vaultId", "type": "uint256"},
        ],
        "name": "getVault",
        "outputs": [
            {
                "components": [
                    {"name": "shortOtokens", "type": "address[]"},
                    {"name": "longOtokens", "type": "address[]"},
                    {"name": "collateralAssets", "type": "address[]"},
                    {"name": "shortAmounts", "type": "uint256[]"},
                    {"name": "longAmounts", "type": "uint256[]"},
                    {"name": "collateralAmounts", "type": "uint256[]"},
                ],
                "name": "vault",
                "type": "tuple",
            }
        ],
        "stateMutability": "view",
        "type": "function",
    }
]

controller = w3.eth.contract(
    address=Web3.to_checksum_address(CONTROLLER),
    abi=CONTROLLER_READ_ABI,
)

vault = controller.functions.getVault(account.address, vault_id).call()
collateral_asset = vault[2][0]   # collateralAssets[0]
collateral_amount = vault[5][0]  # collateralAmounts[0]

# Withdraw
WITHDRAW_ABI = [
    {
        "inputs": [
            {"name": "vaultId", "type": "uint256"},
            {"name": "collateralAsset", "type": "address"},
            {"name": "withdrawalAmount", "type": "uint256"},
        ],
        "name": "withdrawVaultCollateral",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function",
    }
]

pool = w3.eth.contract(
    address=Web3.to_checksum_address(HEDGED_POOL),
    abi=WITHDRAW_ABI,
)

tx = pool.functions.withdrawVaultCollateral(
    vault_id,
    collateral_asset,
    collateral_amount,
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": 999,
})

signed = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
w3.eth.wait_for_transaction_receipt(tx_hash)

10

Position Tracking

Get vault state:

Controller.getVault(address owner, uint256 vaultId) returns (Vault memory)

struct Vault {
    address[] shortOtokens;
    address[] longOtokens;
    address[] collateralAssets;
    uint256[] shortAmounts;
    uint256[] longAmounts;
    uint256[] collateralAmounts;
}

All fields are arrays, but in practice each contains 0 or 1 element.

Vault ID discovery:

• First trade: Use autoCreateVault=true and parse MarginVaultOpened event from the receipt.

• After the fact: Call Controller.getAccountVaultCounter(yourAddress). Vault IDs are sequential starting from 1.

Vault status check:

import time

OTOKEN_ABI = [
    {
        "inputs": [],
        "name": "expiryTimestamp",
        "outputs": [{"type": "uint256"}],
        "stateMutability": "view",
        "type": "function",
    },
]

vault = controller.functions.getVault(account.address, vault_id).call()
has_short = len(vault[3]) > 0 and vault[3][0] > 0
has_collateral = any(a > 0 for a in vault[5])

if has_short:
    otoken = w3.eth.contract(address=vault[0][0], abi=OTOKEN_ABI)
    expiry = otoken.functions.expiryTimestamp().call()
    if expiry < int(time.time()):
        print("Expired -- needs settlement")
    else:
        print("Open position -- not yet expired")
elif has_collateral:
    print("Settled -- ready to withdraw collateral")
else:
    print("Fully settled and withdrawn")

Contract Integration Guide

Complete guide for smart contracts and vaults. See the Full Solidity Example for a compilable contract with all interfaces inlined.

How It Works

1. Your backend calls POST /quote with account = your contract address (the API co-signs the order for that address).

2. Your keeper/owner calls your contract, passing in the signed order.

3. Your contract calls HedgedPool.trade(order, vaultId, autoCreateVault).

4. The TradeExecutor pulls collateral from msg.sender (your contract), not from the original caller.

Your contract must hold the collateral tokens and have approved TradeExecutor before the trade call. The /quote API co-signs the order -- your contract does not need to produce its own signature.

Setup (One-Time)

1. Your contract approves TradeExecutor to spend its collateral tokens.

2. Your contract calls Controller.setOperator(hedgedPoolAddress, true) so the protocol can manage vaults on its behalf.

Trading from a Contract

// Your contract calls this -- the order comes from your backend via /quote API
function executeTrade(
    IOrderUtil.Order calldata order,
    uint256 vaultId,
    bool autoCreateVault
) external onlyOwner {
    IHedgedPool(HEDGED_POOL).trade(order, vaultId, autoCreateVault);
}

Buy Back from a Contract

Your backend gets a buy-back quote (positive amount) from /quote, and your contract forwards it to HedgedPool.trade().

Your contract must have approved HedgedPool for the premium token (USD₮0 or USDC) before the buy-back call.

function executeBuyBack(
    IOrderUtil.Order calldata order,
    uint256 vaultId
) external onlyOwner {
    IHedgedPool(HEDGED_POOL).trade(order, vaultId, false);
}

Settlement from a Contract

Your contract calls Controller.operate() directly.

function settleVault(uint256 vaultId) external onlyOwner {
    IController.ActionArgs[] memory actions = new IController.ActionArgs[](1);
    actions[0] = IController.ActionArgs(
        IController.ActionType.SettleVault,
        address(this),  // owner
        address(this),  // payout destination
        address(0),     // not used
        vaultId,
        0,              // not used
        0,              // not used
        ""              // not used
    );
    IController(CONTROLLER).operate(actions);
}

Collateral Withdrawal from a Contract

function withdrawCollateral(
    uint256 vaultId,
    address collateralAsset,
    uint256 amount
) external onlyOwner {
    IHedgedPool(HEDGED_POOL).withdrawVaultCollateral(vaultId, collateralAsset, amount);
}

---

Auctions

The guide above covers selling options to the protocol. Hypersurface also runs auctions, where the protocol sells option inventory back to the market and any address can buy it.

The format is a Dutch auction priced in implied volatility: the offered price descends over a short window. A take is a single transaction: you pay premium in USDT0 and receive the oTokens. Access is permissionless, with no whitelist or sign-up. See Auctions for the user-facing overview.

Integration paths

• On-chain. The Auction contract on HyperEVM is permissionless. Any address can read the current price and submit a take directly. The address is listed under Contract Addresses.

• API. The same API that powers the auctions page is available to programmatic takers. The full auction API specification is provided on request while it is being finalized, and will be added to this guide after initial production use.

A take can revert even on a live auction. The most common case is NoEligibleHolders, which fires when the option series has no short holders to receive the surplus. Programmatic takers should simulate or handle reverts rather than assume a take always succeeds.

To request the auction API specification, or to discuss pricing and settlement, contact the team through Community & Support.

---

Subgraph (Goldsky)

Public GraphQL endpoints, no authentication required.

Chain	Endpoint
HyperEVM	https://api.goldsky.com/api/public/project_clysuc3c7f21y01ub6hd66nmp/subgraphs/hypersurface-sh-subgraph/latest/gn
Base	https://api.goldsky.com/api/public/project_clysuc3c7f21y01ub6hd66nmp/subgraphs/hypersurface-base-subgraph/latest/gn

Sample trades query (HyperEVM):

curl -X POST \
  "https://api.goldsky.com/api/public/project_clysuc3c7f21y01ub6hd66nmp/subgraphs/hypersurface-sh-subgraph/latest/gn" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ trades(first: 10, orderBy: timestamp, orderDirection: desc) { id account totalPremium totalFee totalNotional underlyingPrice timestamp legs { oToken amount premium fee } } }"
  }'

---

Reference

Order Struct (Solidity)

These are the Solidity structs passed to HedgedPool.trade(). The /quote API returns these fields as JSON strings which you convert before submitting on-chain.

struct Order {
    address account;            // Your wallet or contract address
    address poolAddress;        // HedgedPool address
    address underlying;         // Underlying token contract address
    address collateral;         // Collateral token contract address
    address referrer;           // Referral address (address(0) if none)
    uint256 validUntil;         // Unix timestamp -- order expires after this
    uint256 nonce;              // Unique nonce for replay protection
    OptionLeg[] legs;           // Must contain exactly 1 element
    Signature signature;        // Protocol's EIP-712 co-signature
    Signature[] coSignatures;   // Additional co-signer signatures (usually empty)
}

struct OptionLeg {
    uint256 strike;             // Strike price, 1e8 scaled ($25 = 2500000000)
    uint256 expiration;         // Expiry timestamp (08:00 UTC)
    bool isPut;                 // true = put, false = call
    int256 amount;              // Signed, 1e8 scaled. Negative = selling
    int256 premium;             // Signed, 1e6 scaled. Negative = you receive
    uint256 fee;                // Protocol fee, 1e6 scaled
}

struct Signature {
    uint8 v;
    bytes32 r;
    bytes32 s;
}

Collateral Requirements

The contract automatically calculates and pulls collateral from msg.sender during trade(). You do not pass a collateral amount.

Option Type	Collateral Token	Amount Required	Example
Covered Call	Underlying asset (e.g. wHYPE)	1:1 with option quantity	Sell 1 HYPE call = deposit 1 wHYPE (1e18 units)
Cash-Secured Put	Stablecoin (USD₮0 or USDC)	Strike price x quantity, minus premium	Sell 1 put at $25 strike = deposit up to 25 USD₮0 (25e6 units)

For puts, the premium is netted against the collateral requirement. If you sell a $25 put and receive $3.10 premium, the protocol pulls approximately $21.90 from your wallet as collateral (the exact amount depends on the margin calculator).

Decimal Conventions

Data Type	Scale	Example	Meaning
Strike (on-chain)	1e8	2500000000	$25.00
Premium (/quote)	1e6	"-3100000"	-$3.10 (you receive $3.10)
Premium (/optionsPrices)	float USD	3.10	$3.10
Amount (quantity)	1e8	-100000000	Sell 1 option
HYPE / ETH / ENA / XPL / KNTQ / kHYPE	1e18	1000000000000000000	1.0 token
BTC (UBTC / cbBTC)	1e8	100000000	1.0 BTC
SOL (USOL)	1e9	1000000000	1.0 SOL
PUMP (UPUMP)	1e6	1000000	1.0 PUMP
USD₮0 / USDC	1e6	1000000	$1.00

On-Chain Errors

Error	Description
SignatureInvalid()	Order signature verification failed
NonceAlreadyUsed(uint256)	Nonce has already been consumed (stale quote)
TooCloseToExpiration()	Trade rejected -- within 24h of expiry
InventoryCapExceeded(uint256, uint256)	Pool inventory cap reached. Args: (cap, inventoryBalance)
InvalidOrder()	Invalid amount/premium combination
InvalidUnderlying()	Underlying token not supported by the pool
InvalidPoolAddress()	Order's poolAddress does not match the contract
InvalidAccount()	order.account does not match msg.sender
Unauthorized()	Signer is not a registered quote provider
SeriesExpired()	Option expiry is in the past
InvalidLegsCount()	legs array must contain exactly 1 element
InsufficientBalance()	Insufficient token balance
ZeroValue()	Zero amount not allowed

API Errors

HTTP Code	Scenario	Description
400	Invalid symbol	Symbol format is malformed or unrecognized
400	Invalid parameters	Missing or incorrect query/body parameters
400	Expired option	The requested expiry date is in the past
400	No oToken	No oToken contract exists for this option series
403	Access restricted	The requested action is not permitted for this wallet
404	Asset not found	The underlying asset is not supported on this chain
422	ITM rejection	Selling in-the-money options is not allowed
500	Internal error	API encountered an unexpected error
503	Unhealthy feed	Vol surface or price feed is stale or unavailable

Error response format:

{
  "error": {
    "code": 400,
    "message": "Invalid symbol format"
  }
}

format_order_for_contract() Python Helper

Converts the /quote API response into the format expected by HedgedPool.trade().

def format_order_for_contract(api_order: dict) -> dict:
    """
    Convert the /quote API response order into the format expected
    by HedgedPool.trade() on-chain.

    Key transformations:
    - KEEP 'account' field (it IS part of the Solidity struct)
    - Convert string numbers to int (strike, amount, premium, fee, nonce, validUntil)
    - Convert signature v from hex string to int, r/s from hex to bytes
    """
    legs = []
    for leg in api_order["legs"]:
        legs.append({
            "strike": int(leg["strike"]),
            "expiration": int(leg["expiration"]),
            "isPut": leg["isPut"],
            "amount": int(leg["amount"]),
            "premium": int(leg["premium"]),
            "fee": int(leg["fee"]),
        })

    signature = api_order.get("signature", {})
    formatted_sig = {
        "v": int(signature["v"], 16) if isinstance(signature["v"], str) else signature["v"],
        "r": bytes.fromhex(signature["r"][2:]) if isinstance(signature["r"], str) else signature["r"],
        "s": bytes.fromhex(signature["s"][2:]) if isinstance(signature["s"], str) else signature["s"],
    }

    co_sigs = []
    for cs in api_order.get("coSignatures", []):
        co_sigs.append({
            "v": int(cs["v"], 16) if isinstance(cs["v"], str) else cs["v"],
            "r": bytes.fromhex(cs["r"][2:]) if isinstance(cs["r"], str) else cs["r"],
            "s": bytes.fromhex(cs["s"][2:]) if isinstance(cs["s"], str) else cs["s"],
        })

    return {
        "account": api_order["account"],
        "poolAddress": api_order["poolAddress"],
        "underlying": api_order["underlying"],
        "collateral": api_order["collateral"],
        "referrer": api_order["referrer"],
        "validUntil": int(api_order["validUntil"]),
        "nonce": int(api_order["nonce"]),
        "legs": legs,
        "signature": formatted_sig,
        "coSignatures": co_sigs,
    }

ActionArgs Struct

struct ActionArgs {
    ActionType actionType;  // enum: 0=OpenVault, 6=WithdrawCollateral, 7=SettleVault, etc.
    address owner;          // vault owner address
    address secondAddress;  // payout destination
    address asset;          // not used for SettleVault (set to address(0))
    uint256 vaultId;        // vault to settle
    uint256 amount;         // not used for SettleVault (set to 0)
    uint256 index;          // not used for SettleVault (set to 0)
    bytes data;             // not used for SettleVault (set to empty)
}

Action type reference:

Action	Type	Purpose
OpenVault	0	Open a new margin vault
MintShortOption	1	Mint (write) an option
BurnShortOption	2	Burn (close) an option
DepositCollateral	5	Deposit collateral into a vault
WithdrawCollateral	6	Withdraw collateral from a vault
SettleVault	7	Settle an expired vault
Redeem	8	Redeem expired long oTokens

Full Example: Python Trading Bot

HypersurfaceClient class with all ABIs inline. pip install web3 requests then run.

"""
Hypersurface Protocol -- Python Trading Bot
Covers: pricing, quoting, sell, buy-back, settlement, withdrawal.
Target: HyperEVM (Chain 999)

Dependencies:
    pip install web3 requests
"""

import time
import requests
from datetime import datetime, timezone
from web3 import Web3

# ── Configuration ─────────────────────────────────────────────────
HYPERSURFACE_API = "https://market-api-sh.hypersurface.io"
RPC_URL = "https://rpc.hyperliquid.xyz/evm"
CHAIN_ID = 999

HEDGED_POOL = "0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F"
TRADE_EXECUTOR = "0x25dD9EAae2e0b118a2CefdD229233654840BA7A0"
CONTROLLER = "0x7730e6bfbfCE8Ff0b7a50b72D0601c209Eb818C4"
PREMIUM_TOKEN = "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"  # USD₮0
ADDRESS_ZERO = "0x0000000000000000000000000000000000000000"

SETTLE_VAULT = 7

TOKENS = {
    "HYPE":  "0x5555555555555555555555555555555555555555",  # wHYPE, 18 decimals
    "BTC":   "0x9fdbda0a5e284c32744d2f17ee5c74b284993463",  # UBTC, 8 decimals
    "ETH":   "0xbe6727b535545c67d5caa73dea54865b92cf7907",  # UETH, 18 decimals
    "SOL":   "0x068f321fa8fb9f0d135f290ef6a3e2813e1c8a29",  # USOL, 9 decimals
    "XPL":   "0x33af3c2540ba72054e044efe504867b39ae421f5",  # UXPL, 18 decimals
    "PUMP":  "0x27ec642013bcb3d80ca3706599d3cda04f6f4452",  # UPUMP, 6 decimals
    "ENA":   "0x58538e6a46e07434d7e7375bc268d3cb839c0133",  # UENA, 18 decimals
    "KNTQ":  "0x000000000000780555bd0bca3791f89f9542c2d6",  # KNTQ, 18 decimals
    "kHYPE": "0xfd739d4e423301ce9385c1fb8850539d657c296d",  # kHYPE, 18 decimals
}

# ── ABIs ──────────────────────────────────────────────────────────

HEDGED_POOL_ABI = [
    {
        "inputs": [
            {
                "components": [
                    {"name": "account", "type": "address"},
                    {"name": "poolAddress", "type": "address"},
                    {"name": "underlying", "type": "address"},
                    {"name": "collateral", "type": "address"},
                    {"name": "referrer", "type": "address"},
                    {"name": "validUntil", "type": "uint256"},
                    {"name": "nonce", "type": "uint256"},
                    {
                        "name": "legs",
                        "type": "tuple[]",
                        "components": [
                            {"name": "strike", "type": "uint256"},
                            {"name": "expiration", "type": "uint256"},
                            {"name": "isPut", "type": "bool"},
                            {"name": "amount", "type": "int256"},
                            {"name": "premium", "type": "int256"},
                            {"name": "fee", "type": "uint256"},
                        ],
                    },
                    {
                        "name": "signature",
                        "type": "tuple",
                        "components": [
                            {"name": "v", "type": "uint8"},
                            {"name": "r", "type": "bytes32"},
                            {"name": "s", "type": "bytes32"},
                        ],
                    },
                    {
                        "name": "coSignatures",
                        "type": "tuple[]",
                        "components": [
                            {"name": "v", "type": "uint8"},
                            {"name": "r", "type": "bytes32"},
                            {"name": "s", "type": "bytes32"},
                        ],
                    },
                ],
                "name": "order",
                "type": "tuple",
            },
            {"name": "traderVaultId", "type": "uint256"},
            {"name": "autoCreateVault", "type": "bool"},
        ],
        "name": "trade",
        "outputs": [{"name": "", "type": "address"}],
        "stateMutability": "nonpayable",
        "type": "function",
    },
    {
        "inputs": [
            {"name": "vaultId", "type": "uint256"},
            {"name": "collateralAsset", "type": "address"},
            {"name": "withdrawalAmount", "type": "uint256"},
        ],
        "name": "withdrawVaultCollateral",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function",
    },
]

CONTROLLER_ABI = [
    {
        "inputs": [
            {
                "components": [
                    {"name": "actionType", "type": "uint8"},
                    {"name": "owner", "type": "address"},
                    {"name": "secondAddress", "type": "address"},
                    {"name": "asset", "type": "address"},
                    {"name": "vaultId", "type": "uint256"},
                    {"name": "amount", "type": "uint256"},
                    {"name": "index", "type": "uint256"},
                    {"name": "data", "type": "bytes"},
                ],
                "name": "actions",
                "type": "tuple[]",
            }
        ],
        "name": "operate",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function",
    },
    {
        "inputs": [
            {"name": "owner", "type": "address"},
            {"name": "vaultId", "type": "uint256"},
        ],
        "name": "getVault",
        "outputs": [
            {
                "components": [
                    {"name": "shortOtokens", "type": "address[]"},
                    {"name": "longOtokens", "type": "address[]"},
                    {"name": "collateralAssets", "type": "address[]"},
                    {"name": "shortAmounts", "type": "uint256[]"},
                    {"name": "longAmounts", "type": "uint256[]"},
                    {"name": "collateralAmounts", "type": "uint256[]"},
                ],
                "name": "vault",
                "type": "tuple",
            }
        ],
        "stateMutability": "view",
        "type": "function",
    },
    {
        "inputs": [{"name": "owner", "type": "address"}],
        "name": "getAccountVaultCounter",
        "outputs": [{"name": "", "type": "uint256"}],
        "stateMutability": "view",
        "type": "function",
    },
]

ERC20_ABI = [
    {
        "inputs": [
            {"name": "spender", "type": "address"},
            {"name": "amount", "type": "uint256"},
        ],
        "name": "approve",
        "outputs": [{"name": "", "type": "bool"}],
        "stateMutability": "nonpayable",
        "type": "function",
    },
    {
        "inputs": [
            {"name": "owner", "type": "address"},
            {"name": "spender", "type": "address"},
        ],
        "name": "allowance",
        "outputs": [{"name": "", "type": "uint256"}],
        "stateMutability": "view",
        "type": "function",
    },
    {
        "inputs": [{"name": "account", "type": "address"}],
        "name": "balanceOf",
        "outputs": [{"name": "", "type": "uint256"}],
        "stateMutability": "view",
        "type": "function",
    },
]

TRADE_EXECUTOR_ABI = [
    {
        "anonymous": False,
        "inputs": [
            {"indexed": True, "name": "trader", "type": "address"},
            {"indexed": False, "name": "vaultId", "type": "uint256"},
        ],
        "name": "MarginVaultOpened",
        "type": "event",
    },
]

OTOKEN_ABI = [
    {
        "inputs": [],
        "name": "expiryTimestamp",
        "outputs": [{"type": "uint256"}],
        "stateMutability": "view",
        "type": "function",
    },
]

# ── Helpers ───────────────────────────────────────────────────────

def format_expiry_code(expiry: datetime) -> str:
    """Format a supported expiry datetime as DDMMMYY. Expiries occur at 08:00 UTC."""
    return expiry.astimezone(timezone.utc).strftime("%d%b%y").upper()


def format_order_for_contract(api_order: dict) -> dict:
    """
    Convert /quote API response into the format expected by
    HedgedPool.trade() on-chain.
    """
    legs = []
    for leg in api_order["legs"]:
        legs.append(
            {
                "strike": int(leg["strike"]),
                "expiration": int(leg["expiration"]),
                "isPut": leg["isPut"],
                "amount": int(leg["amount"]),
                "premium": int(leg["premium"]),
                "fee": int(leg["fee"]),
            }
        )

    signature = api_order.get("signature", {})
    formatted_sig = {
        "v": int(signature["v"], 16)
        if isinstance(signature["v"], str)
        else signature["v"],
        "r": bytes.fromhex(signature["r"][2:])
        if isinstance(signature["r"], str)
        else signature["r"],
        "s": bytes.fromhex(signature["s"][2:])
        if isinstance(signature["s"], str)
        else signature["s"],
    }

    co_sigs = []
    for cs in api_order.get("coSignatures", []):
        co_sigs.append(
            {
                "v": int(cs["v"], 16)
                if isinstance(cs["v"], str)
                else cs["v"],
                "r": bytes.fromhex(cs["r"][2:])
                if isinstance(cs["r"], str)
                else cs["r"],
                "s": bytes.fromhex(cs["s"][2:])
                if isinstance(cs["s"], str)
                else cs["s"],
            }
        )

    return {
        "account": api_order["account"],
        "poolAddress": api_order["poolAddress"],
        "underlying": api_order["underlying"],
        "collateral": api_order["collateral"],
        "referrer": api_order["referrer"],
        "validUntil": int(api_order["validUntil"]),
        "nonce": int(api_order["nonce"]),
        "legs": legs,
        "signature": formatted_sig,
        "coSignatures": co_sigs,
    }


# ── Client Class ──────────────────────────────────────────────────

class HypersurfaceClient:
    """Full trade lifecycle client for Hypersurface Protocol on HyperEVM."""

    def __init__(self, private_key: str):
        self.w3 = Web3(Web3.HTTPProvider(RPC_URL))
        self.account = self.w3.eth.account.from_key(private_key)

        self.hedged_pool = self.w3.eth.contract(
            address=Web3.to_checksum_address(HEDGED_POOL),
            abi=HEDGED_POOL_ABI,
        )
        self.controller = self.w3.eth.contract(
            address=Web3.to_checksum_address(CONTROLLER),
            abi=CONTROLLER_ABI,
        )
        self.trade_executor = self.w3.eth.contract(
            address=Web3.to_checksum_address(TRADE_EXECUTOR),
            abi=TRADE_EXECUTOR_ABI,
        )

    # ── Pricing ───────────────────────────────────────────────────

    def get_option_price(self, symbol: str) -> dict:
        """Fetch option pricing. Returns dict with ask, bid, premium, probability_otm."""
        resp = requests.get(
            f"{HYPERSURFACE_API}/optionsPrices",
            params={"symbol": symbol},
        )
        resp.raise_for_status()
        return resp.json()["result"][symbol]

    def get_option_chain(
        self, underlying: str, expiry: str, strikes: list[float]
    ) -> list[dict]:
        """Scan calls and puts across multiple strikes for a given expiry."""
        chain = []
        for strike in strikes:
            strike_str = f"{strike:g}"
            for opt_type in ["C", "P"]:
                symbol = f"{underlying}-{expiry}-{strike_str}-{opt_type}"
                try:
                    price = self.get_option_price(symbol)
                    chain.append(
                        {
                            "symbol": symbol,
                            "ask": price["ask"],
                            "bid": price["bid"],
                            "premium": price["premium"],
                            "type": "call" if opt_type == "C" else "put",
                        }
                    )
                except requests.HTTPError:
                    continue
        return chain

    # ── Quoting ───────────────────────────────────────────────────

    def get_quote(
        self,
        symbol: str,
        amount: int,
        underlying: str,
        collateral: str,
        is_sell: bool,
    ) -> dict:
        """
        Request a signed quote from the API.

        Args:
            symbol: e.g. "HYPE-28MAR26-25-C"
            amount: Number of options (positive integer, e.g. 1)
            underlying: Underlying token address
            collateral: Collateral token address (underlying for calls, stablecoin for puts)
            is_sell: True to sell (open), False to buy back (close)
        """
        scaled_amount = amount * 100_000_000
        if is_sell:
            scaled_amount = -scaled_amount

        payload = {
            "sign": True,
            "order": {
                "account": self.account.address,
                "poolAddress": HEDGED_POOL,
                "underlying": Web3.to_checksum_address(underlying),
                "collateral": Web3.to_checksum_address(collateral),
                "referrer": ADDRESS_ZERO,
                "legs": [{"symbol": symbol, "amount": scaled_amount}],
            },
        }

        resp = requests.post(f"{HYPERSURFACE_API}/quote", json=payload)
        resp.raise_for_status()
        return resp.json()

    # ── Approvals ─────────────────────────────────────────────────

    def _ensure_allowance(self, token_address: str, spender: str, required: int):
        """Approve spender if current allowance is insufficient."""
        token = self.w3.eth.contract(
            address=Web3.to_checksum_address(token_address),
            abi=ERC20_ABI,
        )
        current = token.functions.allowance(
            self.account.address, Web3.to_checksum_address(spender)
        ).call()
        if current < required:
            tx = token.functions.approve(
                Web3.to_checksum_address(spender), 2**128
            ).build_transaction(
                {
                    "from": self.account.address,
                    "nonce": self.w3.eth.get_transaction_count(self.account.address),
                    "chainId": CHAIN_ID,
                }
            )
            signed = self.account.sign_transaction(tx)
            tx_hash = self.w3.eth.send_raw_transaction(signed.raw_transaction)
            self.w3.eth.wait_for_transaction_receipt(tx_hash)

    # ── Trade Execution ───────────────────────────────────────────

    def execute_trade(self, quote: dict, vault_id: int = 0) -> dict:
        """
        Execute a sell trade on-chain. Returns dict with tx_hash and vault_id.

        Args:
            quote: Full API response from get_quote()
            vault_id: Existing vault ID, or 0 to auto-create
        """
        api_order = quote["result"]["order"]
        auto_create = vault_id == 0

        # Approve TradeExecutor for collateral
        self._ensure_allowance(api_order["collateral"], TRADE_EXECUTOR, 2**128)

        contract_order = format_order_for_contract(api_order)

        tx = self.hedged_pool.functions.trade(
            contract_order, vault_id, auto_create
        ).build_transaction(
            {
                "from": self.account.address,
                "nonce": self.w3.eth.get_transaction_count(self.account.address),
                "chainId": CHAIN_ID,
                "gas": 1_500_000,
            }
        )

        signed = self.account.sign_transaction(tx)
        tx_hash = self.w3.eth.send_raw_transaction(signed.raw_transaction)
        receipt = self.w3.eth.wait_for_transaction_receipt(tx_hash)

        result_vault_id = vault_id
        if auto_create:
            events = self.trade_executor.events.MarginVaultOpened().process_receipt(
                receipt
            )
            if events:
                result_vault_id = events[0]["args"]["vaultId"]

        return {"tx_hash": tx_hash.hex(), "vault_id": result_vault_id}

    # ── Buy Back ──────────────────────────────────────────────────

    def buy_back(
        self,
        symbol: str,
        underlying: str,
        collateral: str,
        amount: int = 1,
        vault_id: int = 0,
    ) -> dict:
        """Buy back (close) an existing short position. Returns dict with tx_hash."""
        quote = self.get_quote(symbol, amount, underlying, collateral, is_sell=False)
        api_order = quote["result"]["order"]

        # Approve HedgedPool for premium token (buy-back costs premium)
        self._ensure_allowance(PREMIUM_TOKEN, HEDGED_POOL, 2**128)

        contract_order = format_order_for_contract(api_order)

        tx = self.hedged_pool.functions.trade(
            contract_order, vault_id, False
        ).build_transaction(
            {
                "from": self.account.address,
                "nonce": self.w3.eth.get_transaction_count(self.account.address),
                "chainId": CHAIN_ID,
                "gas": 500_000,
            }
        )

        signed = self.account.sign_transaction(tx)
        tx_hash = self.w3.eth.send_raw_transaction(signed.raw_transaction)
        self.w3.eth.wait_for_transaction_receipt(tx_hash)

        return {"tx_hash": tx_hash.hex()}

    # ── Vault Reads ───────────────────────────────────────────────

    def get_vault_state(self, vault_id: int) -> dict:
        """Read a vault's current state from the Controller."""
        vault = self.controller.functions.getVault(
            self.account.address, vault_id
        ).call()
        return {
            "short_otokens": vault[0],
            "long_otokens": vault[1],
            "collateral_assets": vault[2],
            "short_amounts": vault[3],
            "long_amounts": vault[4],
            "collateral_amounts": vault[5],
        }

    def get_vault_count(self) -> int:
        """Return the total number of vaults owned by this wallet."""
        return self.controller.functions.getAccountVaultCounter(
            self.account.address
        ).call()

    # ── Withdrawal ────────────────────────────────────────────────

    def withdraw_collateral(self, vault_id: int, asset: str, amount: int) -> str:
        """Withdraw collateral from a vault. Returns tx hash."""
        tx = self.hedged_pool.functions.withdrawVaultCollateral(
            vault_id,
            Web3.to_checksum_address(asset),
            amount,
        ).build_transaction(
            {
                "from": self.account.address,
                "nonce": self.w3.eth.get_transaction_count(self.account.address),
                "chainId": CHAIN_ID,
            }
        )

        signed = self.account.sign_transaction(tx)
        tx_hash = self.w3.eth.send_raw_transaction(signed.raw_transaction)
        self.w3.eth.wait_for_transaction_receipt(tx_hash)
        return tx_hash.hex()

    # ── Settlement ────────────────────────────────────────────────

    def settle_vaults(self, vault_ids: list[int]) -> str:
        """Settle one or more expired vaults. Returns tx hash."""
        actions = [
            {
                "actionType": SETTLE_VAULT,
                "owner": self.account.address,
                "secondAddress": self.account.address,
                "asset": Web3.to_checksum_address(ADDRESS_ZERO),
                "vaultId": vid,
                "amount": 0,
                "index": 0,
                "data": b"",
            }
            for vid in vault_ids
        ]

        tx = self.controller.functions.operate(actions).build_transaction(
            {
                "from": self.account.address,
                "nonce": self.w3.eth.get_transaction_count(self.account.address),
                "chainId": CHAIN_ID,
            }
        )

        signed = self.account.sign_transaction(tx)
        tx_hash = self.w3.eth.send_raw_transaction(signed.raw_transaction)
        self.w3.eth.wait_for_transaction_receipt(tx_hash)
        return tx_hash.hex()

    # ── Full Post-Expiry Sweep ────────────────────────────────────

    def settle_and_withdraw_all(self):
        """Find all vaults, settle expired ones, withdraw all available collateral."""
        vault_count = self.get_vault_count()
        print(f"You have {vault_count} vault(s)")

        expired_vaults = []
        withdrawable_vaults = []

        for vid in range(1, vault_count + 1):
            state = self.get_vault_state(vid)
            has_short = len(state["short_amounts"]) > 0 and state["short_amounts"][0] > 0
            has_collateral = any(a > 0 for a in state["collateral_amounts"])

            if has_short:
                otoken_addr = state["short_otokens"][0]
                otoken = self.w3.eth.contract(address=otoken_addr, abi=OTOKEN_ABI)
                expiry = otoken.functions.expiryTimestamp().call()
                if expiry < int(time.time()):
                    expired_vaults.append(vid)
                    print(f"  Vault {vid}: expired, needs settlement")
                else:
                    print(f"  Vault {vid}: still active (expires {expiry})")
            elif has_collateral:
                withdrawable_vaults.append((vid, state))
                print(f"  Vault {vid}: settled, ready to withdraw")
            else:
                print(f"  Vault {vid}: empty")

        # Step 1: Settle expired vaults in a single transaction
        if expired_vaults:
            print(f"\nSettling {len(expired_vaults)} vault(s)...")
            tx = self.settle_vaults(expired_vaults)
            print(f"Settlement tx: {tx}")

            for vid in expired_vaults:
                state = self.get_vault_state(vid)
                if any(a > 0 for a in state["collateral_amounts"]):
                    withdrawable_vaults.append((vid, state))

        # Step 2: Withdraw collateral from each vault
        for vid, state in withdrawable_vaults:
            for asset, amount in zip(
                state["collateral_assets"], state["collateral_amounts"]
            ):
                if amount > 0:
                    print(f"\nWithdrawing from vault {vid} (asset: {asset})...")
                    tx = self.withdraw_collateral(vid, asset, amount)
                    print(f"Withdrawal tx: {tx}")

        print("\nDone.")


# ── Usage ─────────────────────────────────────────────────────────

if __name__ == "__main__":
    client = HypersurfaceClient("YOUR_PRIVATE_KEY")

    # 1. Check prices
    price = client.get_option_price("HYPE-28MAR26-25-C")
    print(f"Ask: ${price['ask']:.2f}, Bid: ${price['bid']:.2f}")

    # 2. Scan an option chain
    chain = client.get_option_chain("HYPE", "28MAR26", [23, 24, 25, 26, 27])
    for opt in chain:
        print(f"  {opt['symbol']}: ask={opt['ask']:.4f}, bid={opt['bid']:.4f}")

    # 3. Get a quote for selling 1 covered call
    quote = client.get_quote(
        symbol="HYPE-28MAR26-25-C",
        amount=1,
        underlying=TOKENS["HYPE"],
        collateral=TOKENS["HYPE"],
        is_sell=True,
    )
    premium = quote["result"]["order"]["legs"][0]["premium"]
    print(f"Premium (1e6 scaled): {premium}")

    # 4. Execute the trade (uncomment when ready)
    # result = client.execute_trade(quote)
    # print(f"Trade tx: {result['tx_hash']}, Vault ID: {result['vault_id']}")

    # 5. Format a supported expiry date
    example_expiry = datetime(2026, 3, 28, 8, 0, tzinfo=timezone.utc)
    print("Example expiry code:", format_expiry_code(example_expiry))

    # 6. After expiry, settle and withdraw all
    # client.settle_and_withdraw_all()

---

Full Example: Solidity Vault Contract

Solidity vault that trades options via Hypersurface. All interfaces inlined -- only needs OpenZeppelin.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.18; // Requires OpenZeppelin v4.x

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

// ── Interfaces (inlined) ─────────────────────────────────────────

interface IOrderUtil {
    struct Order {
        address account;
        address poolAddress;
        address underlying;
        address collateral;
        address referrer;
        uint256 validUntil;
        uint256 nonce;
        OptionLeg[] legs;
        Signature signature;
        Signature[] coSignatures;
    }

    struct OptionLeg {
        uint256 strike;
        uint256 expiration;
        bool isPut;
        int256 amount;
        int256 premium;
        uint256 fee;
    }

    struct Signature {
        uint8 v;
        bytes32 r;
        bytes32 s;
    }

    function cancel(uint256[] calldata nonces) external;
    function cancelUpTo(uint256 minimumNonce) external;
    function nonceUsed(address, uint256) external view returns (bool);
}

interface IHedgedPool {
    function trade(
        IOrderUtil.Order calldata order,
        uint256 traderVaultId,
        bool autoCreateVault
    ) external returns (address);

    function withdrawVaultCollateral(
        uint256 vaultId,
        address collateralAsset,
        uint256 withdrawalAmount
    ) external;
}

interface IController {
    enum ActionType {
        OpenVault,
        MintShortOption,
        BurnShortOption,
        DepositLongOption,
        WithdrawLongOption,
        DepositCollateral,
        WithdrawCollateral,
        SettleVault,
        Redeem,
        Call,
        Liquidate
    }

    struct ActionArgs {
        ActionType actionType;
        address owner;
        address secondAddress;
        address asset;
        uint256 vaultId;
        uint256 amount;
        uint256 index;
        bytes data;
    }

    function operate(ActionArgs[] calldata _actions) external;
    function getAccountVaultCounter(address owner) external view returns (uint256);
    function setOperator(address _operator, bool _isOperator) external;
}

// ── Vault Contract ───────────────────────────────────────────────

contract MinimalOptionsVault is Ownable {
    using SafeERC20 for IERC20;

    // HyperEVM addresses
    address public constant HEDGED_POOL = 0x0095aCDD705Cfcc11eAfFb6c19A28C0153ad196F;
    address public constant TRADE_EXECUTOR = 0x25dD9EAae2e0b118a2CefdD229233654840BA7A0;
    address public constant CONTROLLER = 0x7730e6bfbfCE8Ff0b7a50b72D0601c209Eb818C4;
    address public constant PREMIUM_TOKEN = 0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb;

    uint256 public currentVaultId;

    constructor() {
        // Allow HedgedPool to manage vaults on behalf of this contract
        IController(CONTROLLER).setOperator(HEDGED_POOL, true);
    }

    /// @notice Approve TradeExecutor to spend a collateral token (call once per token)
    function approveCollateral(address token, uint256 amount) external onlyOwner {
        IERC20(token).safeApprove(TRADE_EXECUTOR, amount);
    }

    /// @notice Approve HedgedPool to spend the premium token (for buy-backs)
    function approvePremium(uint256 amount) external onlyOwner {
        IERC20(PREMIUM_TOKEN).safeApprove(HEDGED_POOL, amount);
    }

    /// @notice Deposit collateral tokens into this contract
    function deposit(address token, uint256 amount) external onlyOwner {
        IERC20(token).safeTransferFrom(msg.sender, address(this), amount);
    }

    /// @notice Execute a sell trade. The order comes from your backend via POST /quote.
    /// @param order The signed order from the Hypersurface API
    /// @param autoCreateVault True on the first trade to auto-create a margin vault
    function executeTrade(
        IOrderUtil.Order calldata order,
        bool autoCreateVault
    ) external onlyOwner {
        IHedgedPool(HEDGED_POOL).trade(order, currentVaultId, autoCreateVault);

        // On first trade, discover the vault ID
        if (autoCreateVault) {
            currentVaultId = IController(CONTROLLER).getAccountVaultCounter(address(this));
        }
    }

    /// @notice Buy back (close) a position before expiry
    function executeBuyBack(
        IOrderUtil.Order calldata order
    ) external onlyOwner {
        IHedgedPool(HEDGED_POOL).trade(order, currentVaultId, false);
    }

    /// @notice Settle an expired vault
    function settleVault(uint256 vaultId) external onlyOwner {
        IController.ActionArgs[] memory actions = new IController.ActionArgs[](1);
        actions[0] = IController.ActionArgs(
            IController.ActionType.SettleVault,
            address(this),  // owner
            address(this),  // payout destination
            address(0),
            vaultId,
            0,
            0,
            ""
        );
        IController(CONTROLLER).operate(actions);
    }

    /// @notice Withdraw collateral from a settled vault
    function withdrawCollateral(
        uint256 vaultId,
        address collateralAsset,
        uint256 amount
    ) external onlyOwner {
        IHedgedPool(HEDGED_POOL).withdrawVaultCollateral(vaultId, collateralAsset, amount);
    }

    /// @notice Withdraw any ERC-20 token from this contract to the owner
    function sweep(address token, uint256 amount) external onlyOwner {
        IERC20(token).safeTransfer(owner(), amount);
    }

    /// @notice Accept native currency
    receive() external payable {}
}

Deployment and usage:

1. Deploy MinimalOptionsVault on HyperEVM.

2. Call approveCollateral(wHYPE_address, type(uint256).max) for each collateral token.

3. Call approvePremium(type(uint256).max) for buy-backs.

4. Call deposit(wHYPE_address, amount) to fund the contract with collateral.

5. Your backend calls POST /quote with account = your contract address.

6. Call executeTrade(order, true) for the first trade, executeTrade(order, false) for subsequent trades into the same vault.

7. After expiry, call settleVault(vaultId), then withdrawCollateral(...), then sweep(token, amount).