Build Edit-Order 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.

Edits the take-profit and/or stop-loss attached to a position or pending order. Pass 0 on Gains to remove a leg.

Request Body

dex

string

required

gains or lighter.

chainId

string

required

Chain of the position/order.

marketId

string

Mobula market identifier.

positionId

string

Gains trade index (regex ^\d+$). Required for Gains.

newTp

number

New take-profit price (≥ 0). On Gains, pass 0 to clear the TP.

newSl

number

New stop-loss price (≥ 0). On Gains, pass 0 to clear the SL.

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	`edit-order payload action failed` — invalid TP/SL direction, missing position, or DEX refusal

Full flow — edit TP/SL end-to-end

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

import { ethers } from 'ethers';

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

const { data } = await fetch(`https://api.mobula.io/${endpoint}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp: ts,
    signature: authSig,
    dex: 'gains',                    // or 'lighter'
    chainId: 'evm:42161',            // or 'lighter:301'
    marketId: 'gains-btc-usd',
    positionId: '12345',             // Gains trade index — required for Gains
    newTp: 75000,                    // pass 0 on Gains to clear the TP
    newSl: 0,                        // pass 0 on Gains to clear the SL
  }),
}).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 (regex ^\d+$). Required for Gains.

newTp

number

newSl

number

Response

200 - application/json

Canonical payload envelope

success

boolean

required

data

object

required

Show child attributes

Introduction

Swap API

Bridge (Alpha Preview)

Perps Execution

Prediction Markets Execution

Agentic Payments

Build Edit-Order Payload

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Full flow — edit TP/SL end-to-end

Body

Response

Introduction

Swap API

Bridge (Alpha Preview)

Perps Execution

Prediction Markets Execution

Agentic Payments

Documentation Index

​Request Body

​Authentication

​Authentication errors

​Response envelope

​Endpoint-specific errors

​Full flow — edit TP/SL end-to-end

Body

Response

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Full flow — edit TP/SL end-to-end