Build Create-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.

Builds the canonical order payload used by /2/perp/execute-v2. The signer recovered from the signature field becomes the order’s user.

Request Body

baseToken

string

required

Base token address, symbol, or Mobula asset id.

quote

string

required

Quote/collateral token (typically USDC).

leverage

number

required

Leverage multiplier (e.g., 10).

long

boolean

required

true for long, false for short.

reduceOnly

boolean

required

true if the order must only reduce an existing position.

collateralAmount

number

required

Collateral in quote units (e.g., USDC).

orderType

string

One of market, limit, stop_limit. Default market.

openPrice

number

Trigger/limit price. Required for limit and stop_limit.

number

Take-profit price.

number

Stop-loss price.

amountRaw

number

Raw position size in base-token units. If omitted, derived from collateralAmount * leverage.

maxSlippageP

number

Max slippage in percent.

chainIds

string[]

Restrict routing to specific chains.

dexes

string[]

Restrict routing to gains and/or lighter.

marginMode

number

0 = cross, 1 = isolated (DEX-specific).

referrer

string

Referrer wallet address for fee sharing.

marketId

string

Force a specific Mobula market instead of routing.

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`
500	`could not build create-order payload` — no DEX could build a payload for the given parameters

Full flow — open a position 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 create-order payload
const endpoint = 'api/2/perp/payloads/create-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,
    baseToken: 'BTC',
    quote: 'USDC',
    long: true,
    reduceOnly: false,
    leverage: 10,
    collateralAmount: 100,           // 100 USDC of collateral
    orderType: 'market',
    maxSlippageP: 0.5,
    dexes: ['lighter'],              // or ['gains'], or omit to let routing pick
  }),
}).then(r => r.json());

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

if (data.transport === 'evm-tx') {
  // Gains: sign the single EVM tx and pass as top-level signedTx
  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,           // Gains → calldata field is `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,
  });
}
// Lighter offchain-api: nothing to sign here

// 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

baseToken

string

required

quote

string

required

leverage

number

required

long

boolean

required

reduceOnly

boolean

required

collateralAmount

number

required

orderType

enum<string>

Available options:

market,

limit,

stop_limit

openPrice

number

amountRaw

number

maxSlippageP

number

chainIds

string[]

dexes

enum<string>[]

Available options:

gains,

lighter

marginMode

number

referrer

string

marketId

string

Response

200 - application/json

Canonical payload envelope

success

boolean

required

data

object

required

Show child attributes

Introduction

Data

Execution

Cookbook

Streams

Reference

Build Create-Order Payload

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Full flow — open a position 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 — open a position end-to-end

Body

Response

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Full flow — open a position end-to-end