Build Withdraw Payload

Build withdraw payload

curl --request POST \
  --url https://demo-api.mobula.io/api/2/perp/payloads/withdraw \
  --header 'Content-Type: application/json' \
  --data '
{
  "timestamp": 123,
  "signature": "<string>",
  "dex": "lighter",
  "chainId": "<string>",
  "amountUsdc": "<string>"
}
'

import requests

url = "https://demo-api.mobula.io/api/2/perp/payloads/withdraw"

payload = {
    "timestamp": 123,
    "signature": "<string>",
    "dex": "lighter",
    "chainId": "<string>",
    "amountUsdc": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    timestamp: 123,
    signature: '<string>',
    dex: 'lighter',
    chainId: '<string>',
    amountUsdc: '<string>'
  })
};

fetch('https://demo-api.mobula.io/api/2/perp/payloads/withdraw', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://demo-api.mobula.io/api/2/perp/payloads/withdraw",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'timestamp' => 123,
    'signature' => '<string>',
    'dex' => 'lighter',
    'chainId' => '<string>',
    'amountUsdc' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://demo-api.mobula.io/api/2/perp/payloads/withdraw"

	payload := strings.NewReader("{\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"dex\": \"lighter\",\n  \"chainId\": \"<string>\",\n  \"amountUsdc\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://demo-api.mobula.io/api/2/perp/payloads/withdraw")
  .header("Content-Type", "application/json")
  .body("{\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"dex\": \"lighter\",\n  \"chainId\": \"<string>\",\n  \"amountUsdc\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://demo-api.mobula.io/api/2/perp/payloads/withdraw")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"dex\": \"lighter\",\n  \"chainId\": \"<string>\",\n  \"amountUsdc\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "action": "<string>",
    "dex": "<string>",
    "chainId": "<string>",
    "payloadStr": "<string>",
    "marketId": "<string>"
  }
}

POST

perp

payloads

withdraw

Build withdraw payload

curl --request POST \
  --url https://demo-api.mobula.io/api/2/perp/payloads/withdraw \
  --header 'Content-Type: application/json' \
  --data '
{
  "timestamp": 123,
  "signature": "<string>",
  "dex": "lighter",
  "chainId": "<string>",
  "amountUsdc": "<string>"
}
'

import requests

url = "https://demo-api.mobula.io/api/2/perp/payloads/withdraw"

payload = {
    "timestamp": 123,
    "signature": "<string>",
    "dex": "lighter",
    "chainId": "<string>",
    "amountUsdc": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    timestamp: 123,
    signature: '<string>',
    dex: 'lighter',
    chainId: '<string>',
    amountUsdc: '<string>'
  })
};

fetch('https://demo-api.mobula.io/api/2/perp/payloads/withdraw', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://demo-api.mobula.io/api/2/perp/payloads/withdraw",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'timestamp' => 123,
    'signature' => '<string>',
    'dex' => 'lighter',
    'chainId' => '<string>',
    'amountUsdc' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://demo-api.mobula.io/api/2/perp/payloads/withdraw"

	payload := strings.NewReader("{\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"dex\": \"lighter\",\n  \"chainId\": \"<string>\",\n  \"amountUsdc\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://demo-api.mobula.io/api/2/perp/payloads/withdraw")
  .header("Content-Type", "application/json")
  .body("{\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"dex\": \"lighter\",\n  \"chainId\": \"<string>\",\n  \"amountUsdc\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://demo-api.mobula.io/api/2/perp/payloads/withdraw")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"dex\": \"lighter\",\n  \"chainId\": \"<string>\",\n  \"amountUsdc\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "action": "<string>",
    "dex": "<string>",
    "chainId": "<string>",
    "payloadStr": "<string>",
    "marketId": "<string>"
  }
}

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.

Lighter-only. Gains withdraws collateral by closing positions — there is no separate withdraw endpoint. Skip this for Gains.

Moves free USDC from the user’s Lighter account back to their wallet. Only free margin (not locked by open positions/orders) can be withdrawn.

Lighter withdraw payload shape

The response’s payloadStr is an envelope whose payload includes an L1 authorization challenge:

{
  "action": "withdraw",
  "dex": "lighter",
  "chainId": "lighter:301",
  "transport": "offchain-api",
  "payload": {
    "MessageToSign": "Lighter withdraw ... <server-generated challenge>",
    // other Lighter-native fields
  }
}

Client workflow (Lighter):

Parse payloadStr.
Sign payload.MessageToSign with the user’s wallet (standard EIP-191 personal_sign).
Set the resulting hex on payload.L1Sig and delete payload.MessageToSign.
Re-stringify the envelope → finalPayloadStr.
Sign `api/2/perp/execute-v2-${timestamp}-${finalPayloadStr}` and call /2/perp/execute-v2 with that payloadStr (no top-level signedTx).

Request Body

dex

string

required

Must be lighter.

chainId

string

required

Lighter chain (e.g., lighter:301).

amountUsdc

string

required

USDC amount as a decimal string (e.g., "100"). Must be positive.

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.

Top-level shape. Successful (2xx) responses return { data: { ... } }. A success: true flag is only present inside the body of execute-v2’s response, not on the payload-build endpoints. Parse defensively: read body.data, then check for the action-specific fields you need (e.g. data.payloadStr).

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	`withdraw payload generation failed` — insufficient free margin or DEX refusal

Example — Lighter withdraw 100 USDC

const endpoint = 'api/2/perp/payloads/withdraw';
const timestamp = Date.now();
const signature = 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,
    dex: 'lighter',
    chainId: 'lighter:301',
    amountUsdc: '100',
  }),
}).then(r => r.json());

const { data } = payloadRes;
const envelope = JSON.parse(data.payloadStr);

// Lighter L1 sig dance
const l1Sig = await wallet.signMessage(envelope.payload.MessageToSign);
envelope.payload.L1Sig = l1Sig;
delete envelope.payload.MessageToSign;

const finalPayloadStr = JSON.stringify(envelope);

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

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,
    transport: data.transport,
    payloadStr: finalPayloadStr,
    timestamp: execTs,
    signature: execSig,
  }),
});

Body

application/json

timestamp

number

required

signature

string

required

dex

enum<string>

required

Available options:

lighter

chainId

string

required

Lighter chain (e.g., lighter:301).

amountUsdc

string

required

USDC amount as a decimal string. Must be positive.

Response

200 - application/json

Canonical payload envelope

success

boolean

required

data

object

required

Show child attributes

Build Deposit Payload Build Create-Order Payload

⌘I

​Lighter withdraw payload shape

​Request Body

​Authentication

​Authentication errors

​Response envelope

​Endpoint-specific errors

​Example — Lighter withdraw 100 USDC

Body

Response

Lighter withdraw payload shape

Request Body

Authentication

Authentication errors

Response envelope

Endpoint-specific errors

Example — Lighter withdraw 100 USDC