Skip to main content
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.
​
tp
number
Take-profit price.
​
sl
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.

​
Endpoint-specific errors

Statusmessage
500could not build create-order payload — no DEX could build a payload for the given parameters

​
Example

Open a 10x long on BTC/USD with 100 USDC of collateral on Lighter, then execute: 
const endpoint = 'api/2/perp/payloads/create-order';
const timestamp = Date.now();
const authSig = await wallet.signMessage(`${endpoint}-${timestamp}`);

const payloadRes = await fetch(`https://api.mobula.io/${endpoint}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp,
    signature: authSig,
    baseToken: 'BTC',
    quote: 'USDC',
    long: true,
    reduceOnly: false,
    leverage: 10,
    collateralAmount: 100,
    orderType: 'market',
    maxSlippageP: 0.5,
    dexes: ['lighter'],
  }),
}).then(r => r.json());

const { action, dex, chainId, marketId, transport, payloadStr } = payloadRes.data;

// Step 2 — submit via execute-v2
const execTs = Date.now();
const execSig = await wallet.signMessage(
  `api/2/perp/execute-v2-${execTs}-${payloadStr}`,
);

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