Build Update-Margin Payload

Lighter requires the wallet to be a registered account before any trade/withdraw action.If the EOA has never deposited on Lighter, this endpoint will fail. First-time setup is a two-step prerequisite:

Deposit ≥ 5 USDC via /2/perp/payloads/deposit → Lighter creates an accountIndex on-chain once the bridge settles. (5 USDC is a Lighter requirement, not a Mobula limit.)
Provision API key + auth token via /2/perp/payloads/create-account using that accountIndex.

Read the Build Create-Account Payload page for the full setup flow including how to discover the accountIndex after a deposit.

Adjusts margin on an open position. The exact semantics depend on the DEX:

Lighter — supply usdcAmount and increase to add or remove USDC collateral on the market’s position.
Gains — supply newLeverage to change the trade’s leverage, which effectively adjusts its collateral.

Request Body

dex

string

required

gains or lighter.

chainId

string

required

Chain of the position.

marketId

string

Mobula market identifier.

positionId

string

Gains trade index. Required for Gains.

usdcAmount

number

Lighter only. USDC amount to add or remove (> 0).

increase

boolean

Lighter only. true to add margin, false to remove it.

newLeverage

number

Gains only. New per-trade leverage (> 0).

Authentication

Every /2/perp/payloads/<action> endpoint verifies the caller by requiring two extra fields in the request body alongside the action parameters:

timestamp

number

required

Unix timestamp in milliseconds. Must be within 30 seconds of server time. Older timestamps are rejected to prevent replay.

signature

string

required

Hex signature (EIP-191 personal_sign) of the message `${endpoint}-${timestamp}`, where endpoint is the path of this endpoint without the leading slash (e.g., for this page: api/2/perp/payloads/<this-action>). The recovered signer address becomes the user for the request. Single-use — replay returns 403 signature already used.

// Replace `<action>` with the action of THIS page (e.g. create-account, deposit, …)
const endpoint = 'api/2/perp/payloads/<action>';
const timestamp = Date.now();
const signature = await wallet.signMessage(`${endpoint}-${timestamp}`);

await fetch(`https://api.mobula.io/${endpoint}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp,
    signature,
    // ...action-specific fields below
  }),
});

Authentication errors

Status	`message`
403	`timestamp expired` — timestamp older than 30s
403	`signature already used` — replay attempt
400	`zod validation failed` — `timestamp`/`signature` shape invalid

Response envelope

Every /2/perp/payloads/<action> endpoint returns the same envelope shape. You pass these fields verbatim into POST /2/perp/execute-v2 to execute the action.

data

object

Show data

action

string

Canonical action name — one of withdraw, create-account, deposit, create-order, close-position, cancel-order, update-margin, edit-order.

dex

string

gains or lighter.

chainId

string

Chain where the action lands (e.g., evm:42161, lighter:301).

marketId

string

Mobula market identifier. Present when the action targets a specific market.

transport

string

offchain-api — server submits to the DEX off-chain API on the user’s behalf (Lighter trades, Lighter withdraw, Lighter create-account).
evm-tx — server broadcasts a user-signed EVM transaction (Lighter deposit bridge route, Gains trade actions). The Gains case requires a top-level signedTx on execute-v2; the Lighter deposit case injects signed txs inside payloadStr.

payloadStr

string

JSON-stringified canonical envelope. For most actions you forward this byte-for-byte into /2/perp/execute-v2. Mutations are required for: Lighter deposit (inject payload.signedTxs), Lighter withdraw (sign payload.MessageToSign → payload.L1Sig, delete MessageToSign), Lighter create-account (same as withdraw only if payload.MessageToSign is present). After mutation, re-stringify and sign execute-v2 over the new string. Never alter the envelope metadata (action, dex, chainId, transport, marketId) — execute-v2 cross-checks it.

Endpoint-specific errors

Status	`message`
400	`update-margin payload action failed` — missing position, wrong leg supplied for the DEX, or DEX refusal

Full flow — update margin end-to-end

Single example covering both DEXes (Lighter offchain-api with usdcAmount+increase, Gains evm-tx with newLeverage). The flow branches on data.transport.

import { ethers } from 'ethers';

// 1. Auth-sign + fetch the update-margin payload
const endpoint = 'api/2/perp/payloads/update-margin';
const ts = Date.now();
const authSig = await wallet.signMessage(`${endpoint}-${ts}`);

// Lighter: add 50 USDC of margin to BTC-USD
const lighterBody = {
  timestamp: ts, signature: authSig,
  dex: 'lighter', chainId: 'lighter:301',
  marketId: 'lighter-btc-usd',
  usdcAmount: 50, increase: true,
};

// Gains alternative: lower leverage to 5x on Gains trade #12345
// const gainsBody = {
//   timestamp: ts, signature: authSig,
//   dex: 'gains', chainId: 'evm:42161',
//   marketId: 'gains-btc-usd',
//   positionId: '12345', newLeverage: 5,
// };

const { data } = await fetch(`https://api.mobula.io/${endpoint}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(lighterBody),
}).then(r => r.json());

// 2. Branch on transport
let signedTx;
const finalPayloadStr = data.payloadStr;

if (data.transport === 'evm-tx') {
  // Gains
  const txData = JSON.parse(data.payloadStr).payload.data;
  const provider = new ethers.JsonRpcProvider(rpcUrlFor(txData.chainId));
  const feeData = await provider.getFeeData();

  const baseTx = {
    to: txData.to,
    data: txData.callData,
    value: txData.value ? BigInt(txData.value) : 0n,
    from: wallet.address,
    chainId: txData.chainId,
    nonce: txData.nonce ?? await provider.getTransactionCount(wallet.address),
  };
  const gasLimit = txData.gas ? BigInt(txData.gas) : await provider.estimateGas(baseTx);

  signedTx = await wallet.signTransaction({
    ...baseTx, gasLimit,
    maxFeePerGas: txData.maxFeePerGas ? BigInt(txData.maxFeePerGas) : feeData.maxFeePerGas,
    maxPriorityFeePerGas: txData.maxPriorityFeePerGas ? BigInt(txData.maxPriorityFeePerGas) : feeData.maxPriorityFeePerGas,
    type: 2,
  });
}

// 3. Sign + submit execute-v2
const execTs = Date.now();
const execSig = await wallet.signMessage(
  `api/2/perp/execute-v2-${execTs}-${finalPayloadStr}`,
);

const execRes = await fetch('https://api.mobula.io/api/2/perp/execute-v2', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: data.action,
    dex: data.dex,
    chainId: data.chainId,
    marketId: data.marketId,
    transport: data.transport,
    payloadStr: finalPayloadStr,
    timestamp: execTs,
    signature: execSig,
    ...(signedTx && { signedTx }),
  }),
}).then(r => r.json());

Body

application/json

timestamp

number

required

signature

string

required

dex

enum<string>

required

Available options:

gains,

lighter

chainId

string

required

marketId

string

positionId

string

Gains trade index. Required for Gains.

usdcAmount

number

Lighter only. USDC amount to add or remove (> 0).

increase

boolean

Lighter only. true = add margin, false = remove.

newLeverage

number

Gains only. New per-trade leverage (> 0).

Response

200 - application/json

Canonical payload envelope

success

boolean

required

data

object

required

Show child attributes

Introduction

Data

Execution

Cookbook

Streams

Reference

Build Update-Margin Payload

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Full flow — update margin end-to-end

Body

Response

Introduction

Data

Execution

Cookbook

Streams

Reference

Documentation Index

​Request Body

​Authentication

​Authentication errors

​Response envelope

​Endpoint-specific errors

​Full flow — update margin end-to-end

Body

Response

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Full flow — update margin end-to-end