Hedging the house's position

Admin → Convert → Hedges (/admin/convert/hedge). Viewing needs view.convert.hedge; resolving a hedge in review, unfreezing a currency and reopening quoting need manage.convert.hedge, which no role holds until you grant it.

After a user converts BTC into ETH, the house holds more BTC and less ETH than it meant to. Hedging sells the BTC and buys the ETH back on your exchange, with the house's own Spot balances, so the house returns to its targets and keeps the spread. It is off by default and needs an exchange provider.

Exposure

Exposure is recomputed from balances every time, never accumulated, so it survives crashes, restarts and missed events. For each currency:

E = house Spot balance (balance + in order)
  + what open hedges have yet to deliver
  + what house movements have in flight
  − target

A positive E means the house is long and the hedger sells; a negative E means it is short and the hedger buys back. USDT is the currency every hedge trades against, so it is measured and reported, never hedged itself. A hedge in review counts as if it had filled until someone says otherwise, because that is the side that never hedges the same exposure twice.

Where hedging is enabled on both a currency's Spot and Ecosystem asset rows, its Ecosystem balance is folded in: the hedger trades the whole position on the exchange, and house movements carry coins between the two sides. Otherwise the Ecosystem side stays its own row, is never hedged out of Spot inventory (that would empty the Spot side with nothing to refill it) and is only capped.

The three modes

Pause hedging (convertHedgePause) stops every new hedge order, and every new house movement, without changing the mode. Orders already sent are still followed and booked.

The mode, the pause and the house-movement switch are edited in one place only: the core house page, Instant Convert house, which the House inventory button on Finance → Transaction Management → Pool Backing opens. It needs the Super Admin role and a fresh two-factor code, and works while the addon is disabled or unlicensed. The Convert settings page and the Controls tab here show them read-only with a link there. The limits beside them (threshold, caps, slippage, failures) are edited on the Convert settings page.

When and how much

The hedge job beats every 15 seconds and measures exposure on every beat (the dashboard, the unhedged caps and the disable check read that measurement). It goes on to plan and send only every convertHedgeIntervalSeconds (default 15, so every beat; accepted 15 to 3600 seconds): after a run that planned, the next beats only measure until the interval has passed. An exposure over the threshold is therefore hedged at the next such run, never sooner. The job's own beat is the shortest interval possible.

Each planning run, per currency, in Automatic mode:

• Whether. Only when |E| is worth at least convertHedgeThresholdUsd (default $50). Smaller positions carry forward, which saves venue fees on dust. In drain mode the threshold does not apply: a drain runs until flat.
• Which way. Always against USDT, never a direct pair: one direct order would move two currencies at once past a lock that only guards one.
• How much. Exactly |E|, never more, cut to the per-order cap, to what is left of the hourly cap, to the market's maximum and to what the house actually holds to spend, then truncated to the market's amount step. Below the market's minimum amount or cost, it waits.
• Reduce only. In every mode an order that would not shrink |E| is refused, so a stale plan or a sign that flipped under a convert can never grow the position.

What stops a dispatch: another cycle still running, the mode, a core below Convert level 2 and the hedge interval not yet passed; then, per currency, its asset's Hedging switch, a freeze, an auto-pause and the threshold; then the pause, an exchange ban or Convert's breaker, and a venue that charged a fee in a third currency the house cannot pay; and last, per currency, the caps and another hedge of it or of USDT in flight.

Sending an order, and never sending it twice

Booking a fill

The booking job (every 15 seconds, and it keeps running while the addon is disabled) books each fill exactly once, in the transaction that marks the row Filled or Partly filled (FILLED, PARTIAL): the hold is settled, the proceeds are credited to the house, the fee is taken, the locks are released.

• The fee comes from the fills in the order's own answer, else from the order's trades, never from the fetched order alone, which on Binance carries no fee. A fill whose fee is unknown on a venue that charges fees is never booked: it goes to review.
• A fee in the base or quote currency is netted. A fee in a third currency (BNB) is debited from the house's own Spot BNB wallet, and that debit is recorded as a house cost in the Profit & loss (no admin_profit row: the house's wallet paid it). If the house holds no BNB, the fill goes to review and new hedges on that venue stop until it does.
• Partly filled (PARTIAL) is written only once the venue reports the order finished (closed, cancelled, expired, rejected). The booking job does not wait for ever: a market order still open 5 minutes after it was sent is cancelled and read back, and what filled is booked; one that still does not read as finished goes to review. An order the venue still cannot be asked about 30 minutes after it was sent goes to review, as does one sent to a venue that is no longer the platform's exchange. An order that ended with nothing filled is marked failed, its hold returned, and it counts towards the failures in a row. A hedge left Planned because its dispatcher stopped before stamping it Sent is marked failed after 2 minutes, its hold returned: nothing was ordered.
• Hedges write no exchange-order rows, so the nightly venue-fee job never books their fee a second time.

Review, freeze and unfreeze

A hedge in Needs review keeps its currency frozen: nothing new is sent for it on any venue until a person decides. The review dialog shows the venue's recorded answer and offers three decisions:

Once no hedge of a currency is in review, Unfreeze it on the Exposure tab. That clears the freeze, any auto-pause, the failure count and any quoting closure; the next cycle may send an order for it. Unfreeze is refused while any hedge of the currency is still in review (for USDT, while any hedge at all is).

Automatic stops

• Failures in a row. After convertHedgeMaxFailures (default 3) failed hedges in a row (a definite refusal by the venue, a trading-account top-up that failed before any order was sent, or an order that ended with nothing filled), hedging of that currency pauses for one hour and lifts on its own, or when someone unfreezes it. A booked fill resets the count; the count survives the pause, so one more failure pauses it again at once.
• Slippage. A fill whose average is worse than the mid captured at dispatch by more than convertHedgeMaxSlippageBps (default 100 bps) pauses hedging of that currency for an hour and closes quoting of it: the book the house prices from is not the market it trades in. A fill better than the mid never trips it.
• Quoting closed (the Exposure tab's Converts closed badge) also follows unacknowledged pool-backing drift on the currency: a quote or a convert finds it at once, and the quote-cleanup job every five minutes. A closure is a latch: it stays until someone uses Reopen quoting on the Exposure tab, or Unfreeze where the currency's hedging is also frozen or paused (Unfreeze lifts the closure with the freeze). Reopen quoting is refused until the drift is acknowledged under Finance → Transaction Management → Pool Backing; Unfreeze is not, but while the drift is still unacknowledged the currency closes again at the next quote or cleanup run. Acknowledging the drift does not reopen quoting by itself.

Caps

A convert refused by an exposure cap reads Convert to ETH is temporarily unavailable, the same sentence as an empty inventory, so the refusal tells a user nothing about your position. Size the unhedged cap above your largest single convert, with room for a cycle's worth of flow.

What your exchange must support

• It must be the platform's active exchange provider. Hedges trade on the same account and connection Spot trading uses.
• Market orders on each hedged currency against USDT, and the ability to read an order and its trades back.
• Adoption by client order ID works on KuCoin, Binance and OKX only. On any other venue an ambiguous answer to an order goes straight to review and freezes the currency until someone checks the venue by hand. Hedging still works there; it needs a person more often.
• A fee paid in a third currency needs the house to hold that currency on Spot.
• There is no sandbox. Start in Monitor only for a day. Then switch to Automatic with a small convertMaxHedgeUsdPerOrder and watch the journal for an hour of real converts before raising it.

Draining before you switch off

Mode → Drain (Settings, General tab) closes quoting and lets the hedger run until every currency is flat, ignoring the threshold and only ever reducing exposure. Run it before disabling the addon, so it is not switched off holding a position nobody is watching. The Hedges page carries a notice while drain is on.