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

Custody

Hypervolic is non-custodial. Participants' USDC is held by a settlement contract on chain, not by the exchange. On the testnet that is Base Sepolia, and the USDC is the exchange's test token. The exchange matches orders; the contract holds the money and pays it out, and it checks every trade itself before it moves a cent.

What the contract checks

The exchange matches orders off chain and commits each fill to the contract. The contract then executes the fills in order and, for each one, checks:
  • each order's signature, by its maker or a key the maker registered;
  • the maker's nonce floor and the order's expiry;
  • that the quantity is within what was signed;
  • that the price is the resting order's limit;
  • that the fees are within both orders' caps;
  • that every book the fill touches is still fully secured, and no balance goes negative.
A fill that fails any of these does not execute, whatever the exchange said.

Deposits

Approve USDC to the contract and call deposit(amount), or use depositWithPermit to do both in one transaction. A deposit below the contract's MIN_DEPOSIT is refused. The exchange credits the deposit once its block is a few seconds old (the confirmation depth, confirmationSeconds in GET /v1/config). Your first deposit opens your account. See Funding.

Withdrawals

A withdrawal is debited by the exchange first and paid by the contract after:
  1. You sign a withdrawal request and send it to the gateway. The exchange debits your free cash at once.
  2. The debit is a payout record in the exchange's sequence. The contract executes it in order, after every fill before it, and moves the amount from your cash to owed(you).
  3. collect(you) sends what is owed to your own address. Anyone may call it, and the exchange does for every payout it executes.
Only your account's own key can request a withdrawal. A signing key you registered for trading never can.

If the exchange stops answering

You do not need the exchange's cooperation to get your money out.
  1. Forced withdrawal. Call requestForcedWithdrawal(amount) on the contract. The exchange must answer: it cancels your resting orders and debits up to that amount of free cash, as a forced payout record. The request is answered when the contract executes that record, not before.
  2. Freeze. If the request is still unanswered after the contract's FORCE_WINDOW, anyone may call freeze(you). Only your account freezes; everyone else keeps trading.
  3. Escape. Call escapeWithdraw() once your cash is final, and the contract pays it. Your cash is final when no fill of yours is left that the contract could still execute: the contract has executed fills timed past your freeze plus FREEZE_GRACE, or it has executed every fill committed to it and the exchange's commitments reach past that instant (a quiet market). Your open positions stay claimable at expiry.
  4. The second window. If your cash is still not final a further FORCE_WINDOW after the freeze, escapeWithdraw() pays you anyway, and in doing so freezes the whole contract, not only your account. Reaching that point means execution has stopped for everyone, so nothing trades or executes after it. Every account then leaves at its last executed state, and fills the exchange committed but the contract never executed are lost to both sides.
The administrator can also freeze the whole contract. Either way the freeze is final: everyone can then withdraw their cash at once and claim their positions at expiry, and nothing more trades.
Every timing parameter is a public constant of the contract: FORCE_WINDOW, FREEZE_GRACE, USER_ACTION_DELAY, ORACLE_TIMEOUT, ANCHOR_BEHIND and ANCHOR_AHEAD, and so is MIN_DEPOSIT. Read them from the contract; GET /v1/config also serves the first four.

Signing keys and nonce floors

  • setSigningKey(key, expiry) registers a key that may sign your orders and cancels and open your sessions, until expiry (unix seconds; 0 revokes).
  • cancelUpTo(nonce) raises your nonce floor, so no order signed under a lower nonce can ever execute.
Lengthening a key takes effect at once. Shortening or revoking a key, and raising the floor, bind on the contract after USER_ACTION_DELAY, but the exchange cancels the orders they affect as soon as it reads them from the chain. To make sure it has, the gateway refuses new orders from everyone while its chain reader is too far behind (a 503, see Errors).

What you still trust

Beyond the contract's code:
  • the exchange's settler and witness, which together tell the contract the sequence of fills and payouts, and each expiry's settlement price, carried in the same commitments (see Settlement). Every commitment needs both signatures, and the witness's key is on the engine's host, apart from the settler's;
  • the contract's administrators, who can rotate the exchange's keys, pause execution, and freeze the contract;
  • the token's issuer. On the testnet that is the exchange itself: the mock USDC's owner names who may mint it;
  • the chain and its sequencer, to include your transactions: Base Sepolia on the testnet.
The exchange staying up is not on the list.