Skip to main content

​
Request Body

​
timestamp
number
required
Unix timestamp in milliseconds. Must be within 30 seconds of the current time. Used to prevent replay attacks.
​
signature
string
required
Signature of the message api/2/perp/lighter/update-margin-{timestamp} signed with your wallet’s private key. The signature is used to verify your identity and associate with your Lighter account.
​
marketId
number
required
The market ID where the position exists. This can be found in your open positions from the /2/wallet/positions/perp/open endpoint.
​
usdcAmount
number
required
The amount of USDC to add or remove from the margin. Must be a positive number.
​
increase
boolean
required
Set to true to add margin (increase collateral), false to remove margin (decrease collateral). When set to false, the leverage will be automatically updated to the maximum allowed leverage for the market.

​
Response

​
ok
boolean
Always true on successful margin update.
​
executionDetails
array
Array of transaction execution details (optional). Each object contains:

​
Error Responses

​
400 Bad Request

​
message
string
Error message (e.g. “validation failed”)
​
errors
array
Array of validation errors (Zod issues) if validation fails.

​
403 Forbidden

​
message
string
Error message
Possible messages:
  • "timestamp expired" - The timestamp is more than 30 seconds old
  • "no lighter account associated with the signer address" - The signature doesn’t match a registered Lighter account

​
500 Internal Server Error

​
message
string
Error message (e.g. “error updating margin”)
This error occurs when:
  • The margin update fails on Lighter
  • The position doesn’t exist or cannot be updated
  • Market details cannot be retrieved (when decreasing margin)
  • Other internal errors occur

​
Authentication

  1. Generate a current Unix timestamp in milliseconds
  2. Create the message string: api/2/perp/lighter/update-margin-{timestamp}
  3. Sign this message with your wallet’s private key
  4. Include both the timestamp and signature in the request body
  5. The signature must be from a wallet address that has a registered Lighter account
Important: The timestamp must be within 30 seconds of the current time. Older timestamps will be rejected to prevent replay attacks.

​
Behavior

  • When increase: true: Adds USDC to the position’s margin, increasing the collateral available.
  • When increase: false: Removes USDC from the position’s margin and automatically updates the leverage to the maximum allowed leverage for the market. This ensures the position remains within acceptable risk parameters after margin reduction.

​
Example

const timestamp = Date.now();
const message = `api/2/perp/lighter/update-margin-${timestamp}`;
const signature = await wallet.signMessage(message);

// Add 100 USDC to margin
const response = await fetch('https://api.mobula.io/api/2/perp/lighter/update-margin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp,
    signature,
    marketId: 1,
    usdcAmount: 100,
    increase: true
  })
});

// Remove 50 USDC from margin (leverage will be auto-updated to max)
const response2 = await fetch('https://api.mobula.io/api/2/perp/lighter/update-margin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp: Date.now(),
    signature: await wallet.signMessage(`api/2/perp/lighter/update-margin-${Date.now()}`),
    marketId: 1,
    usdcAmount: 50,
    increase: false
  })
});