Getting liquidity onto a futures book

Creating a futures market creates a row, not a market. The contract goes live the moment you submit the wizard — status: true — and its order book is empty. Nothing in this addon fills it, and nothing else in the platform fills it either.

Until something rests in that book, the contract is not merely quiet. It is unusable in a specific, mechanical way, and the failures point at the trader rather than at you.

What an empty book actually does

The book lives in ScyllaDB, keyed by symbol, and it is written only by orders that rest. A market order is priced by walking it, so with nothing to walk it cannot be priced at all.

Both futures messages come from the sweep in futures/utils/queries/orderbook.ts; the third is the connector refusing to forward an order it cannot price. None of them is a bug to suppress — they are the guard that stops a market order filling at an arbitrary price.

Two consequences are easy to miss:

• A limit order is the only thing that can be placed first. It does not need a counterparty; it becomes the book. Every market order needs one that is already there.
• A market that has never printed has no mark, so the two-second mark sweep skips it entirely. Nothing is stopped out and nothing is liquidated on a symbol with no last price, and a manual close settles at the entry price for zero PnL. See Funding and the mark price.

So a market with no depth is not a market that trades badly. It is a market where market orders fail, positions cannot be opened by taking, and the risk engine has nothing to mark against.

The AI Market Maker does not do this

The same goes for the Algo Trading Bots addon and the copy-trading addon: neither places futures orders. Only two things in the whole platform write a futures order — the user-facing POST /api/futures/order route, and the liquidation engine.

The two routes that do work

Hand-placed limit orders

Every futures order, whoever places it, goes through POST /api/futures/order. That includes yours. An account you control can quote both sides of a new contract from the ordinary trading screen.

This is the right way to bootstrap and the wrong way to run a book. Hand-placed quotes do not follow the price, do not re-quote after a fill, and do not pull themselves when the market moves.

The Hummingbot Connector's perpetual API

The supported way to run a continuous maker on a futures book is the Hummingbot Connector addon and its bicrypto_perpetual connector. It is a bridge, not an engine: everything it places is an ordinary order on your own book, through the same route the trading screen uses, settling through the same FUTURES wallet.

Scope checks are AND, never OR: the amend route requires both of its scopes, so a key minted with hb:trade:perp alone can place orders but answers 403 — Insufficient API key scope on every amend. Signed calls carry X-API-Key, X-Timestamp, X-Nonce and X-Signature; the Perp trading key preset at /hb/keys grants every scope in the table above plus hb:read:market, so a key minted from the preset satisfies all of them.

Signed calls are metered in two buckets — 600 a minute for trading calls (place, cancel, amend) and 240 for account calls (order lookup, positions, leverage) — and both apply the addon defaults in Admin → Hummingbot → Settings and then a key's own rateLimitOverride. The public market-data routes are throttled per IP at 1200 requests a minute, and that figure is fixed in code: the public path consumes the literal budget without consulting either the admin setting or an override. There is no key on an unsigned request, so raising a key's read budget does nothing for a market-data client — an integrator who needs more than 1200 a minute of orderbook has to sign the calls.

The perp side of the connector needs the Futures addon installed on the same server. Without it every perp call answers 503 — The Futures extension is not installed on this server.

Two ways to run the bot:

• Someone else's machine — a user, or you, running Hummingbot with the connector kit. The flow is on Connecting a bot.
• Your own server — Admin → Hummingbot → Bot Instances, which supervises a Hummingbot process on the platform box. Its market picker lists your active futures markets against the bicrypto_perpetual connector, so a perpetual instance is registered the same way a spot one is. See Bot Instances.

A perpetual PMM preset is a pmm strategy in the Strategy Studio with its market set to perp; the generator then emits connector_name: bicrypto_perpetual and a leverage: line into the controller YAML. Strategies and presets covers the parameters.

What the perpetual API tells a bot that is not true of this desk

The endpoints are Binance-Futures-shaped so an off-the-shelf connector parses them. Three fields in that shape mean less here than a bot will assume, and all three read from the market's metadata JSON — which the market wizard never writes.

Funding is a number you typed, or zero. GET /api/hb/perpetual/funding-rate/… returns lastFundingRate straight from metadata.fundingRate, defaults it to 0, and computes nextFundingTime as the next 8-hour UTC boundary. The engine accrues no funding at all — no cron, no ledger entry, no schedule. The countdown is arithmetic on the clock, not a settlement. An external maker pricing inventory on expected funding cashflows will be pricing a cashflow that never happens; tell them, or leave the field absent.

markPrice and indexPrice are 0 unless somebody hand-edits the metadata. Nothing on the platform writes either field. The positions endpoint falls back to reporting markPrice equal to the position's own entry price when it is absent. The mark the engine actually liquidates against is a different number entirely — the in-memory ticker's last traded price on your own book.

maxLeverage and the rungs you publish are two different checks. Exchange-info reports defaultLeverage: 10 and maxLeverage: 100 when the metadata does not carry them, and POST /api/hb/perpetual/leverage validates only against maxLeverage (defaulting to 125). So on a market whose limits.leverage is "1,5,10", a bot's set_leverage 25 succeeds, and then every order it places is refused:

Leverage 25x is not offered on BTC/USDT. Available: 1, 5, 10.

That looks like an exchange fault from the bot's side. It is the discrete rung list doing its job — see Futures markets. Note that the refusal names the market in the platform's internal BTC/USDT form, not the BTC-USDT the bot sent, so grep the logs for the slash.

What quoting this book actually costs

Making a market here is not a neutral activity, and the arithmetic differs from a spot book in one way that dominates everything else.

Inventory is gross, not net. A fill looks its position up by user, symbol and side. Buys accumulate a long; sells accumulate a short; the two coexist and never offset. A maker that quotes both sides and gets hit on both ends up with two open positions, two lots of isolated margin posted, and two independent liquidation prices. Margin usage grows with turnover until somebody closes a leg.

Every fill is a real position with real margin. At leverage L, a ladder carrying total notional N on one side locks N ÷ L of the FUTURES wallet plus the fee, before anything is filled. Cancel releases it; a fill converts it into position margin.

Fees are charged on notional and taken immediately. The maker rate applies to an order that rests, the taker rate to one that crosses — decided from the book at placement, not from the side. At 20x a 0.05% fee is 1% of the margin posted.

Positions the maker holds can be liquidated. They are ordinary positions on your own book, marked against your own last traded price. A maker running at a high rung on a thin contract is exposed to exactly the wash-print problem described in Funding and the mark price.

Reconcile what the bot thinks it holds against GET /api/hb/perpetual/positions and Admin → Futures → Positions (/admin/futures/position, permission access.futures.position) rather than against the bot's own view.

Liquidations trade against the same book

This is why depth is a solvency question and not a UX one.

A liquidation is not a mark-price settlement with a flag flip. The engine submits a reduce-only order on the opposite side, priced at the bankruptcy price, and whatever the book does not absorb is retired immediately — it is never left resting. The trim at 70% of margin lost and the full close at 90% both work this way. Liquidation has the full mechanics.

So the order has a floor it will not trade past. For a long at leverage L it fires at 0.9 ÷ L adverse and is priced at 1 ÷ L adverse, which leaves a window of 0.1 ÷ L of the entry price for the book to absorb it in:

The partial trim fires earlier, at 0.7 ÷ L, so it has a wider window (0.3 ÷ L) — but it only takes 80% of the size, and a trim the book cannot absorb is abandoned rather than settled, because settling it would pay both sides for the same exposure.

What the book cannot absorb on a full liquidation is settled against the mark and the difference is written to the log:

FUTURES_SHORTFALL  The book could not absorb a liquidation; 0.4 of BTC/USDT BUY was
settled against the mark instead. … shortfall=812.34 USDT

There is no insurance fund. That number is yours.

Before you open a market to customers

Depth is not on the futures dashboard: /admin/futures reports open interest, side skew, the at-risk queue and leverage bands, but no book. Read the book from one of these instead:

• The order book panel on /trade?symbol=BTC-USDT&type=futures, fed by the orderbook stream on the futures market WebSocket — top 50 levels a side.
• GET /api/hb/perpetual/orderbook/{currency}/{pair}?limit=50, if the Hummingbot Connector addon is enabled. It is public, so curl works, and it answers 404 for a market that is disabled or does not exist.

Then check the following, on the market's own numbers:

• There is resting depth on both sides. A book with only bids cannot absorb a short's liquidation, which has to buy
• The total resting size inside 0.1 ÷ L of the mark, for the highest rung you offer, is at least the largest position the market permits — that is limits.amount.max, or limits.cost.max ÷ price where you set a cost cap
• limits.amount.max and limits.cost.max are set to real numbers, so one position cannot exceed what the book can take
• limits.leverage lists only rungs whose window the depth above covers
• The market has printed at least once, so the mark sweep is marking it
• If a bot is your only maker, it is running, its API key is not expired or IP-blocked, and hbKillSwitch / hbReadOnly are off
• FUTURES_SHORTFALL is in whatever you monitor logs with

If the depth is not there, the honest options are the same three every time: lower the top rung, cap position size, or leave the market switched off until it has a maker. Deleting the market is not one of them — see Futures markets.

Related

• Futures markets — the wizard, the metadata fields, and retiring a contract safely.
• Liquidation — thresholds, the bankruptcy price and what a shortfall is.
• Risk console — reading open interest and the at-risk queue.
• Troubleshooting — the order rejections, one by one.