Rubin Documentation

Update Leverage

Sets the leverage of one or more perpetual markets for a subaccount (MsgUpdateLeverage). The value is stored on-chain per subaccount and market and caps the leverage of new trades there; see Selected Leverage for how the chain applies it.

Leverage is passed as a custom initial margin fraction in parts per million: customImfPpm = round(1,000,000 / leverage), e.g. 100000 for 10×. Like other order-book messages, the transaction pays no fee. A trading key may sign it for its subaccount.

Method Declaration

TypeScript

async updatePerpetualMarketsLeverage(
    subaccount: SubaccountInfo,
    address: string,
    entries: LeverageEntry[],
    broadcastMode?: BroadcastMode,
): Promise<BroadcastTxAsyncResponse | BroadcastTxSyncResponse | IndexedTx>

Parameters

Parameter	Location	Type	Mandatory	Description
`subaccount`	query	SubaccountInfo	true	Signer and the subaccount whose leverage is set (`subaccountNumber`)
`address`	query	string	true	Address of the account that owns the subaccount
`entries`	query	LeverageEntry	true	One entry per market: clob pair ID and custom IMF in ppm
`broadcastMode`	query	BroadcastMode	false	Mode of broadcast

Example

const leverage = 10;
await client.validatorClient.post.updatePerpetualMarketsLeverage(
  SubaccountInfo.forLocalWallet(wallet, 0),
  wallet.address,
  [{ clobPairId: 0, customImfPpm: Math.round(1_000_000 / leverage) }], // BTC-USD, 10×
);

An isolated position lives on its own subaccount (128, 256, …), so its leverage is set on that subaccount number.

Validation

The chain rejects the message when:

Condition	Error
`customImfPpm` is below the base IMF of the market's liquidity tier	`leverage exceeds maximum allowed`
`customImfPpm` is `0` or above `1,000,000`	`Invalid update leverage: imf ppm … must be between (0, 1,000,000]`
`entries` is empty, or the same clob pair appears twice	`Invalid update leverage`
The clob pair does not exist or is a spot pair	`ClobPair ID does not reference a valid CLOB`
The subaccount belongs to the spot bucket (`number % 128 == 1`)	`Invalid update leverage`
The subaccount's open positions would no longer meet the initial margin requirement	`leverage violates margin requirements`

The maximum is checked against the tier's base IMF; open-interest scaling does not reject a selection, it only applies the higher fraction when margin is computed.

Response

Status	Meaning	Schema
`200`	OK	BroadcastTxAsyncResponse \| BroadcastTxSyncResponse \| IndexedTx
`400`	Bad Request		The request was malformed or invalid.