Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Signing

Orders, cancels, quote requests and withdrawal requests are EIP-712 typed data, signed by your account's key or by a key you registered on chain. The gateway checks the signature before anything is sequenced, and for an order the settlement contract checks it again before the fill pays out.

Domain

{ "name": "Hypervolic", "version": "1", "chainId": <the chain's id>, "verifyingContract": "<the settlement contract's address>" }
There is no salt. Read both values from GET /v1/config (chainId and settlement): on the testnet the chain id is 84532, and a reset of the testnet is a new contract address.

Types

Order(address maker,uint64 underlyingKey,uint64 optionSpecifier,uint8 side,uint64 size,uint64 limitPrice,uint64 nonce,uint64 expiresAt,uint8 maxFeePerMille) Cancel(address maker,uint64 nonce,uint64 orderNonce) QuoteRequest(address maker,uint64 underlyingKey,uint64 optionSpecifier,uint8 side,uint64 size,uint64 nonce) WithdrawalRequest(address user,uint128 amount,uint64 nonce)
The field meanings are on Place an order, Cancel, Request a quote and Withdraw. The signer is not a field: the gateway and the contract recover it.
TypeMay be signed byside
OrderThe account, or a key it registered0 buy, 1 sell
CancelThe account, or a key it registered
QuoteRequestThe account, or a key it registered0 buy, 1 sell, 2 no side
WithdrawalRequestThe account only
A session's sign-in message is not typed data: it is a personal message (personal_sign), and the account or a key it registered may sign it. See Sessions.

Signature format

65 bytes, r‖s‖v, 0x-prefixed hex, with v of 27 or 28. This is what eth_signTypedData_v4, viem and eth-account produce. A signature with a high s is refused.

Nonces

Every order, cancel, quote request and withdrawal request carries a nonce chosen by you. For an order it is also the order's identifier: you cancel it by its nonce, and GET /v1/orders/{maker}/{nonce} looks it up.
  • It must be in [1, 2^62), with bits 54–61 zero, so in practice below 254.
  • Orders, cancels, quote requests and withdrawal requests share one space per account. Each nonce is used once, and one the engine refuses for another reason is still spent.
  • The exchange remembers the 4096 nonces below the highest you have used. A nonce further below that is refused as NONCE_BELOW_WINDOW.
So keep nonces increasing. A counter you persist works, and so does the time in microseconds (time.time_ns() // 1000 in Python, about 250 today), as long as everything that signs for one account draws from the same sequence.

The fee cap

maxFeePerMille is one byte counting tens of basis points: 5 permits fees up to 50 bps, and 255, the most, 25.5%. The gateway refuses an order whose cap times ten is below either of the instrument's rates, so sign ceil(max(makerFeeBps, takerFeeBps) / 10). See The fee cap.

Signing keys

A trading bot need not hold the key that owns your money. Register a separate key on the settlement contract:
setSigningKey(address key, uint64 expiry) // expiry in unix seconds; 0 revokes
That key may sign orders, cancels and quote requests, and open sessions, until expiry. It can never withdraw. An order it signs must expire before the key does, or the gateway refuses it. An account holds up to six registered keys.
The exchange learns of a key from the chain once the block that registered it is a few seconds old (confirmationSeconds in GET /v1/config): until then an order the key signs is refused as signed by a key not registered for the maker. The key appears in keys on GET /v1/account/{addr} when it is usable. Revoking a key (expiry 0) or shortening it ends the sessions it opened and cancels the orders it signed that would outlive it.

Example

from eth_account import Account DOMAIN = {"name": "Hypervolic", "version": "1", "chainId": CHAIN_ID, "verifyingContract": CONTRACT} ORDER = {"Order": [ {"name": "maker", "type": "address"}, {"name": "underlyingKey", "type": "uint64"}, {"name": "optionSpecifier", "type": "uint64"}, {"name": "side", "type": "uint8"}, {"name": "size", "type": "uint64"}, {"name": "limitPrice", "type": "uint64"}, {"name": "nonce", "type": "uint64"}, {"name": "expiresAt", "type": "uint64"}, {"name": "maxFeePerMille", "type": "uint8"}, ]} def sign(private_key, types, message) -> str: signed = Account.sign_typed_data(private_key, DOMAIN, types, message) return "0x" + bytes(signed.signature).hex() order = { "maker": MAKER, "underlyingKey": 7, "optionSpecifier": 859008923130267914, "side": 0, "size": 25, "limitPrice": 20000, "nonce": 42, "expiresAt": 200003600000, "maxFeePerMille": 10, } body = {"order": order, "signature": sign(PRIVATE_KEY, ORDER, order)}
A cancel, a quote request and a withdrawal request are signed the same way, with their own types and primaryType. In Python:
CANCEL = {"Cancel": [ {"name": "maker", "type": "address"}, {"name": "nonce", "type": "uint64"}, {"name": "orderNonce", "type": "uint64"}, ]} QUOTE_REQUEST = {"QuoteRequest": [ {"name": "maker", "type": "address"}, {"name": "underlyingKey", "type": "uint64"}, {"name": "optionSpecifier", "type": "uint64"}, {"name": "side", "type": "uint8"}, {"name": "size", "type": "uint64"}, {"name": "nonce", "type": "uint64"}, ]} WITHDRAWAL_REQUEST = {"WithdrawalRequest": [ {"name": "user", "type": "address"}, {"name": "amount", "type": "uint128"}, {"name": "nonce", "type": "uint64"}, ]} quote = {"maker": MAKER, "underlyingKey": 7, "optionSpecifier": 859008923130267914, "side": 2, "size": 20, "nonce": 43} body = {**quote, "signature": sign(PRIVATE_KEY, QUOTE_REQUEST, quote)} # POST /v1/quote-request
Note the bodies differ: an order is sent as {"order": {...}, "signature"}, while a cancel, a quote request and a withdrawal request put their fields at the top level beside signature.

Test vector

To check an implementation, this order, under chain id 31337 and contract 0x000000000000000000000000000000000000cafE:
{ "maker": "0x1111111111111111111111111111111111111111", "underlyingKey": 7, "optionSpecifier": 859008923130267914, "side": 0, "size": 25, "limitPrice": 20000, "nonce": 42, "expiresAt": 200000100000, "maxFeePerMille": 10 }
has the EIP-712 digest 0xe929252df78454a415a15548b8975cb7fd6f8cf78aba2a4010a55b276b7f38d0.