Liquidations

Liquidations, Price feed stability, Smart contract secuirty

Introduction

When a trader uses leverage, the actual position size is larger than the collateral used to open the position. As a result, there exists a price at which a trader's losses equal the initial collateral used to open the position, at which a trader must be liquidated. However, due to asset volatility (particularly with high leverage), execution time, and potential price feed latency, liquidations must occur before collateral value (- PnL) has declined to zero, instead occurring when collateral value has fallen to 10% of original collateral deposited.

Liquidation Prices

Trades liquidation prices can get closer over time if you pay borrowing fees.

Liquidation Price Distance = Open Price * (Collateral * 0.9 - Borrowing Fees) / Collateral / Leverage.

Liquidation price = If Long: Open Price - Liquidation Price Distance Else (Short): Open Price + Liquidation Price Distance.

For example, let's say that you have opened a long on BTC/USD at 20,000 USD using 100x leverage and 50 USDT collateral, and that you have paid 1 USDT in borrowing fees:

Liquidation Price = 20,000 - 20,000 * (50 * 0.9 - 1) / 50 / 100 = 19,824 USD.

Liquidation Bots

There are certain interactions with the Bitperp protocol which must be automated off-chain, as they cannot be programmed into the smart contracts. These include limit orders, stop losses, take profits, and liquidations. Bitperp lets anyone permissionlessly run a bot for executing these orders. A comprehensive guide and docker container will be available on our github (coming soon). Additionally, we plan on launching a Runes collection soon which if owned by a Liquidation Bot runner will create additional rewards.

Environment Variables for Bitperp Liquidation Bot V1

Name	Description
LOG_LEVEL	Sets the level at which the bot should log. Valid values are: error, warn, info, verbose, debug. Using debug will produce a massive amount of output and is not suggested except for initial setup or problem solving.
ENABLE_CONSOLE_LOGGING	Whether or not log messages should be output to the console.
ENABLE_FS_LOGGING	Whether or not log messages should be output to a log file. This will log into a .logs/<utc-date> directory each time the bot is started.
WSS_URLS	The RPC endpoint URLs that should be used for all blockchain communication.
PRICES_URL	The WSS endpoint where the Gains backend pricing service is running.
PRIVATE_KEY	The private key of your account that should be used to execute transactions. ⚠️ DO NOT PUBLISH THIS ANYWHERE. ⚠️
PUBLIC_KEY	The public key of your account that should be used to execute transactions. IF ORACLE OPERATOR: Make sure this address is either owner() or authorized fulfiller on your oracle address in order to claim rewards.
EVENT_CONFIRMATIONS_SEC	The number of seconds that must pass for an event coming from the blockchain to be considered as confirmed and safe for execution against.
COLLATERAL_PRICE_REFRESH_INTERVAL_SEC	How often collateral prices should be refetched. Defaults to 5s
MIN_PRIORITY_GWEI	The minimum priority gas fee in GWEI that should be used when triggering orders.
MAX_GAS_PRICE_GWEI	The maximum gas price in GWEI that should be used when triggering orders.
MAX_GAS_PER_TRANSACTION
PRIORITY_GWEI_MULTIPLIER	A multiplier that can be applied to the current priority gas fee which was fetched from the polygon gas station.
AUTO_HARVEST_SEC	How frequently the bot will harvest any rewards earned from triggering orders.
FAILED_ORDER_TRIGGER_TIMEOUT_SEC	How long the bot should wait before it will retry an order after it has failed to successfully process on chain.
OPEN_TRADES_REFRESH_SEC	How frequently the bot should fully refresh trade data from the Gains smart contracts on chain. By default, the bot is keeping itself up to date based on delta events it's receiving from the chain so this isn't technically necessary, but it's a good fail safe in case the bot fails to hear about a certain even due to connectivity or other issues. Setting this to 0 will disable explicit refreshing and only ever keep state based on events it receives.
GAS_REFRESH_INTERVAL_SEC	How frequently to get the latest gas prices from the gas station.
FETCH_TRADING_VARIABLES_REFRESH_INTERVAL_SEC	How frequently trading variables should be refreshed from the Gains smart contracts on chain. There are many variables that go into the calculations of triggering order and these variables need to be freshed to ensure the bot is always using the latest numbers. This is always done at start up, but does not need to be done too frequently at runtime.
DRY_RUN	Set to true to enable a "dry run" mode where the bot will do everything except submit the actual transactions to the chain for processing. This is good for initial setup to ensure everything is working as expected and other testing combined with a LOG_LEVEL of debug.
CHAIN_ID	The ID of the block chain the bot is going to be interacting with. This defaults to 137 for Polygon's mainnet and you should only need to change it if you're targeting another chain.
NETWORK_ID	The ID of the network of the block chain the bot is going to be interacting with. This defaults to 137 for Polygon's mainnet and you should only need to change it if you're targeting another chain.
CHAIN	The name of the block chain the bot is going to be interacting with. This defaults to mainnet and you should only change it if you're targeting a different chain.
BASE_CHAIN	The name of the base block chain the bot is going to be interacting with. This only needs to be set if you're testing on a network that is forked from a different chain. (e.g. testing on Polygon's Mumbai you would set this to goerli)
HARDFORK	The ethereum hardfork of the block chain the bot is going to be interacting with. This defaults to london today and you should only need to change it if you're intending to target a different hardfork.
USE_MULTICALL	Whether or not the bot should multicall fetching open orders and other information. Some RPC providers may restrict multicalls. Set to false to use call batching instead. Defaults to true
MAX_RETRIES	How many times the bot should attempt to trigger an order. Set to -1 to disable.
ORACLE_ADDRESS	FOR ORACLE OPERATORS ONLY: The address of your oracle. The PUBLIC_KEY you use to run the bot must either be an authorized fulfiller or the owner of the oracle contract