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

The testnet

Hypervolic runs as a public testnet on Base Sepolia. Everything works as it will with real money: orders are signed, the settlement contract checks every fill, your money stays in the contract. But the money is not real.
Nothing here is money. The USDC is a test token the exchange mints, worth nothing, and it cannot be exchanged for anything. Do not send real assets to any address you see here.
  • Trades are final. The exchange does not cancel or reprice a trade.
  • The testnet may be reset. A fix to the engine can start the testnet over on a new settlement contract. Always read the contract's address from GET /v1/config, never from a copy.

One host

The testnet is served from one public name, the web client's address:
PathWhat
/The web client
/v1, /v1/wsThe gateway's HTTP API and WebSocket
/faucetThe test-funds faucet
FIX is on the same name, on its own port. These pages are on their own subdomain, docs. and that name; ← Back to Markets at the top leads to the client.

The chain

NetworkBase Sepolia
Chain id84532
RPChttps://sepolia.base.org, falling back to https://base-sepolia-rpc.publicnode.com
Explorerhttps://sepolia.basescan.org
GasBase Sepolia ETH
These are what GET /v1/config serves as chainId, chainName, rpcUrl, rpcFallback and explorerUrl. Read them from there.

Adding it to Rabby

The web client asks your wallet to switch to Base Sepolia when you connect, and to add it if the wallet does not know it. Approve the prompt in Rabby.
To add it by hand, open More in Rabby, then Custom Network, then Add Custom Network, and enter:
FieldValue
Chain ID84532
Network nameBase Sepolia
RPC URLhttps://sepolia.base.org
Currency symbolETH
Block explorer URLhttps://sepolia.basescan.org

Gas

Every transaction on Base Sepolia, a deposit or a withdrawal, pays gas in Base Sepolia ETH. The faucet below sends a little with each grant. You can also get it from any public Base Sepolia faucet, such as the one on Coinbase's developer platform.

Test funds

The faucet

The client's deposit step offers GET TEST FUNDS when your wallet holds too little USDC to deposit. It asks the faucet, which mints test USDC to your address and tops up its ETH for gas. Your wallet signs the faucet's message for the address first: the signature is free, and it moves no funds. Try it now, in the client's connect dialog, does all of this for a testnet account made in the browser (see Start trading).
The faucet's API is on the same host:
RouteDoes
GET /faucet/statusWhat a grant is now: grantUsdc (micro-USDC, a decimal string), grantEth (wei), windowHours, perAddress, available, and signature (whether a claim must be signed)
GET /faucet/challenge?address=0x…The text to sign for that address (message) and when it stops being accepted (expires, unix seconds), ten minutes on
POST /faucet/grant{"address", "message", "signature"}, the signature a personal_sign of the text by the address: mints the grant and sends the ETH, and answers with usdc, eth, the transactions (txs), and nextAt, when the address may ask again (unix seconds)
On the testnet a grant is 1,000 USDC, and tops your address up to 0.0005 ETH where it holds less than half of that. Each address gets one grant a day, and each network (an IPv4 address, or an IPv6 /56) three. The faucet also has a daily ceiling for everyone together. A refusal says when to ask again, and sets Retry-After. GET /faucet/status is the current word on all of this.

Mock USDC

The testnet's USDC is the exchange's own mock USDC, not Circle's. It has six decimals and an EIP-2612 permit, like USDC, so everything that handles USDC handles it. Only the exchange's named minters can mint it: the faucet for everyone else. Its address is usdc in GET /v1/config.

The smallest deposit

The settlement contract refuses a deposit below its MIN_DEPOSIT, a constant fixed when the contract was deployed. On the testnet it is 10 USDC (10000000 micro-USDC), published as minDeposit in GET /v1/config. The authoritative value is the contract's own: MIN_DEPOSIT() on the settlement contract at settlement. A faucet grant is always at least that.
Funding has the deposit itself.

Account classes

Every account is in one of two classes, ordinary or premium. Every account starts ordinary. Premium is for market makers and is granted by the operator. Your account's class is engine.premium on GET /v1/account/{addr}.
The class sets how much an account may do. It decides no price, no fee, no priority and no security: a premium account's orders match, pay and are secured exactly as anyone's.
LimitOrdinaryPremiumPublished at
Resting orders25619,456GET /v1/status: engine.OpenOrderCap, engine.OpenOrderCapPremium
Books (one underlying at one expiry)16128GET /v1/status: engine.BookCap, engine.BookCapPremium
Signed requests, per address20 a second, burst 40200 a second, burst 400GET /v1/config: classes.<class>.signed
Fills as the taker, per address5 a second, burst 100200 a second, burst 4,000GET /v1/config: classes.<class>.fills
Quote requests, per address1 a second, burst 510 a second, burst 50GET /v1/config: classes.<class>.quote
Private reads, per session200 a second, burst 2001,000 a second, burst 1,000GET /v1/config: classes.<class>.reads
Per-IP limit on signed requests and private readsappliesdoes not apply
History page100 rows1,000 rows
The numbers are the testnet's today; the published values are the ones that count. What each limit means:
  • Resting orders. An order that could rest, when the account already has its class's cap resting, is refused whole with OPEN_ORDER_LIMIT before it matches. An order that cannot rest (a zero lifetime) is not counted.
  • Books. An order that would open a new book for the account past its cap is refused with BOOK_LIMIT. A book counts from the account's first order on it until its last order and position on it are gone, which for a position is its contract's settlement.
  • Signed requests. An order costs one, a cancel an eighth. A batch costs the sum of its members, and a batch that costs more than the whole burst is refused.
  • Fills as the taker. An order is admitted only if its size fits the fill bucket, since each fill is at least one contract. What it did not fill as the taker is given back. So an ordinary account's largest order, or batch of orders summed, is 100 contracts; a larger one is refused by name.
  • History page. The most rows one page of fills, settlements, prints or reference prices holds. See History pages.
Rate limits has what a refusal looks like.

FIX

FIX 4.4 order entry is open on the testnet:
Hostthe testnet's public name: the web client's address
Port9878
TransportTLS only, with the host's public certificate. There is no plaintext listener.
TargetCompIDHYPERVOLIC
FIX has the logon, the messages and the custom tags. Orders over FIX are signed exactly as over HTTP.