Execute Perp Action

Execute perp action

curl --request POST \
  --url https://demo-api.mobula.io/api/2/perp/execute-v2 \
  --header 'Content-Type: application/json' \
  --data '
{
  "chainId": "<string>",
  "payloadStr": "<string>",
  "timestamp": 123,
  "signature": "<string>",
  "marketId": "<string>",
  "signedTx": "<string>"
}
'

import requests

url = "https://demo-api.mobula.io/api/2/perp/execute-v2"

payload = {
    "chainId": "<string>",
    "payloadStr": "<string>",
    "timestamp": 123,
    "signature": "<string>",
    "marketId": "<string>",
    "signedTx": "<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({
    chainId: '<string>',
    payloadStr: '<string>',
    timestamp: 123,
    signature: '<string>',
    marketId: '<string>',
    signedTx: '<string>'
  })
};

fetch('https://demo-api.mobula.io/api/2/perp/execute-v2', 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/execute-v2",
  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([
    'chainId' => '<string>',
    'payloadStr' => '<string>',
    'timestamp' => 123,
    'signature' => '<string>',
    'marketId' => '<string>',
    'signedTx' => '<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/execute-v2"

	payload := strings.NewReader("{\n  \"chainId\": \"<string>\",\n  \"payloadStr\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"marketId\": \"<string>\",\n  \"signedTx\": \"<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/execute-v2")
  .header("Content-Type", "application/json")
  .body("{\n  \"chainId\": \"<string>\",\n  \"payloadStr\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"marketId\": \"<string>\",\n  \"signedTx\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"chainId\": \"<string>\",\n  \"payloadStr\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"marketId\": \"<string>\",\n  \"signedTx\": \"<string>\"\n}"

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

{
  "success": true,
  "data": {
    "success": true,
    "executionDetails": [
      {
        "txHash": "<string>",
        "type": "<string>",
        "status": "<string>",
        "orderStatuses": [
          {
            "orderId": "<string>",
            "status": "<string>",
            "type": "<string>"
          }
        ]
      }
    ],
    "processId": "<string>"
  }
}

POST

perp

execute-v2

Execute perp action

curl --request POST \
  --url https://demo-api.mobula.io/api/2/perp/execute-v2 \
  --header 'Content-Type: application/json' \
  --data '
{
  "chainId": "<string>",
  "payloadStr": "<string>",
  "timestamp": 123,
  "signature": "<string>",
  "marketId": "<string>",
  "signedTx": "<string>"
}
'

import requests

url = "https://demo-api.mobula.io/api/2/perp/execute-v2"

payload = {
    "chainId": "<string>",
    "payloadStr": "<string>",
    "timestamp": 123,
    "signature": "<string>",
    "marketId": "<string>",
    "signedTx": "<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({
    chainId: '<string>',
    payloadStr: '<string>',
    timestamp: 123,
    signature: '<string>',
    marketId: '<string>',
    signedTx: '<string>'
  })
};

fetch('https://demo-api.mobula.io/api/2/perp/execute-v2', 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/execute-v2",
  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([
    'chainId' => '<string>',
    'payloadStr' => '<string>',
    'timestamp' => 123,
    'signature' => '<string>',
    'marketId' => '<string>',
    'signedTx' => '<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/execute-v2"

	payload := strings.NewReader("{\n  \"chainId\": \"<string>\",\n  \"payloadStr\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"marketId\": \"<string>\",\n  \"signedTx\": \"<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/execute-v2")
  .header("Content-Type", "application/json")
  .body("{\n  \"chainId\": \"<string>\",\n  \"payloadStr\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"marketId\": \"<string>\",\n  \"signedTx\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"chainId\": \"<string>\",\n  \"payloadStr\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\",\n  \"marketId\": \"<string>\",\n  \"signedTx\": \"<string>\"\n}"

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

{
  "success": true,
  "data": {
    "success": true,
    "executionDetails": [
      {
        "txHash": "<string>",
        "type": "<string>",
        "status": "<string>",
        "orderStatuses": [
          {
            "orderId": "<string>",
            "status": "<string>",
            "type": "<string>"
          }
        ]
      }
    ],
    "processId": "<string>"
  }
}

Single unified execution endpoint for every perp action. You forward the exact envelope returned by the matching /2/perp/payloads/<action> call plus a signature that proves the caller approved this specific payload at this specific timestamp.

The /2/perp/execute (v1) endpoint is deprecated. All new integrations must use /2/perp/execute-v2.

Flow

Call POST /2/perp/payloads/<action> (see left-hand nav) → receive { action, dex, chainId, marketId?, transport, payloadStr }.
For Gains transport: "evm-tx" only: parse payloadStr, extract payload.data, sign the EVM transaction locally → obtain signedTx.
Sign the execute-v2 authentication message (see Authentication below).
POST /2/perp/execute-v2 with the envelope fields, signature, timestamp, and (when required) signedTx.

Request Body

string

required

Canonical action name. One of withdraw, create-account, deposit, create-order, close-position, cancel-order, update-margin, edit-order. Must match the action inside payloadStr.

string

required

gains or lighter. Must match payloadStr.

string

required

Chain of the action. Must match payloadStr.

string

Mobula market identifier. If provided, must match payloadStr.marketId.

string

required

offchain-api — server submits to the DEX off-chain API using the user’s signature.
evm-tx — server broadcasts the user-signed EVM transaction supplied in signedTx. Must match payloadStr.

string

required

JSON-stringified canonical envelope returned by /2/perp/payloads/<action>.Envelope metadata (action, dex, chainId, transport, marketId) must be forwarded unchanged — it is cross-checked against the request fields.payload sub-fields are action-specific and some flows require mutating them before signing execute-v2:

deposit (Lighter route with EVM bridge steps) — sign every tx in payload.steps[].items[].data and write the hex results into payload.signedTxs as an array of strings.
withdraw on Lighter — sign payload.MessageToSign, set the hex result on payload.L1Sig, then delete payload.MessageToSign.

In those cases you re-stringify the envelope and use the new string everywhere: as this field, and in the execute-v2 signed message below.

number

required

Unix timestamp in milliseconds, within 30 seconds of server time.

string

required

Hex signature of the message api/2/perp/execute-v2-{timestamp}-{payloadStr}. The recovered signer address must match the payload.data.from address for actions that carry a from (e.g., create-order, close-position). Single-use: a second call with the same signature is rejected.

string

Hex-encoded single signed EVM transaction. Used for Gains single-tx actions (create-order, close-position, cancel-order, edit-order, update-margin) whose response has transport: "evm-tx". The server broadcasts it via eth_sendRawTransaction on chainId.Do not use this field for multi-tx flows (Lighter deposit bridge route) — those inject signed txs into payloadStr under payload.signedTxs instead.

Response

object

Show data

boolean

Always true on success.

array

Per-leg execution details.

Show executionDetails[]

string

Transaction hash (EVM) or DEX-side identifier.

string

Execution kind (e.g., evm-tx, lighter-order).

string

DEX-reported status (e.g., submitted, filled).

array

DEX-reported order-level statuses, when applicable.

Show orderStatuses[]

string

Order id (numeric string).

string

Order status.

string

Order type (order, tp, sl, …).

string

UUID of the async tracking process. Present for long-running actions (typically deposit). Poll /2/perp/check-process?processId=<id> until it reports terminal status.

Errors

Status	`message`	Cause
400	`payloadStr is not valid JSON`	`payloadStr` is not parseable
400	`invalid payloadStr`	envelope fails schema validation (see `errors`)
400	`payloadStr metadata does not match request metadata`	`action`/`dex`/`transport`/`chainId` mismatch between envelope and request
400	`payloadStr marketId does not match request marketId`	`marketId` mismatch
400	`signedTx execution requires an EVM chainId, received "<chainId>"`	`transport: "evm-tx"` with a non-EVM chain
403	`timestamp expired`	`timestamp` more than 30s from server clock
403	`signature already used`	Replay of an earlier request
403	`signature signer does not match payload.from`	Signer address ≠ `payload.data.from` for actions that carry a `from`
500	`Failed to broadcast signed transaction on <chainId>`	RPC rejected `signedTx` (see `errors` list for details)
500	DEX-specific reason	Adapter-level failure returned by the DEX

Authentication

The execute-v2 signature binds the exact payloadStr to the exact timestamp:

const timestamp = Date.now();
const message = `api/2/perp/execute-v2-${timestamp}-${payloadStr}`;
const signature = await wallet.signMessage(message);

Rules:

payloadStr in the signed message is the same string you put in the request body. If the flow requires injecting fields (deposit signedTxs, Lighter withdraw L1Sig), do the injection + re-stringify before signing — sign the final string, not the original.
For actions whose envelope carries payload.data.from (Gains EVM txs, Lighter orders), the signer must equal from. Deposit/withdraw envelopes that don’t expose a from skip this check.
Signatures are single-use for 30 seconds after the timestamp.

Transport & signing matrix

The transport returned by /2/perp/payloads/<action> is authoritative — forward it as-is. What the client must sign depends on both the DEX and the action:

DEX	Action	Transport	Client signing
Lighter	`create-order`, `close-position`, `cancel-order`, `edit-order`, `update-margin`	`offchain-api`	execute-v2 signature only — forward `payloadStr` byte-for-byte
Lighter	`create-account`	`offchain-api`	If the response carries `payload.MessageToSign`: sign it, set `payload.L1Sig`, delete `payload.MessageToSign`, re-stringify. Otherwise no mutation.
Lighter	`deposit`	`evm-tx`	Sign each tx in `payload.steps[].items[].data` (each item’s `data` is a tx object: `to`, `data`, `value`, `chainId`, `gas?`, fee fields). Inject results into `payload.signedTxs: string[]`, re-stringify, then sign execute-v2 over the new string. Do not send top-level `signedTx`.
Lighter	`withdraw`	`offchain-api`	Sign `payload.MessageToSign`, set `payload.L1Sig`, delete `payload.MessageToSign`, re-stringify, then sign execute-v2 over the new string.
Gains	`create-order`, `close-position`, `cancel-order`, `edit-order`, `update-margin`	`evm-tx`	Read the tx object at `payload.data` (fields: `to`, `callData` (not `data`), `value`, `chainId`, `nonce?`, `gas?`, fee fields). Sign as a type-2 EVM tx → submit as top-level `signedTx`. `payloadStr` is forwarded unchanged.

Body

application/json

action

enum<string>

required

Available options:

withdraw,

create-account,

deposit,

create-order,

close-position,

cancel-order,

update-margin,

edit-order

dex

enum<string>

required

Available options:

gains,

lighter

chainId

string

required

transport

enum<string>

required

Available options:

offchain-api,

evm-tx

payloadStr

string

required

JSON-stringified canonical envelope. Envelope metadata must match the request fields.

timestamp

number

required

signature

string

required

Hex signature of api/2/perp/execute-v2-{timestamp}-{payloadStr}.

marketId

string

signedTx

string

Hex-encoded single signed EVM transaction (Gains single-tx actions with transport evm-tx).

Response

200 - application/json

Perp execute response

success

boolean

required

data

object

required

Show child attributes

Build Update-Margin Payload Check Perp Process

⌘I

Introduction

Data

Execution

Cookbook

Streams

Reference

Flow

Request Body

Response

Errors

Authentication

Transport & signing matrix

Body

Response

​Flow

​Request Body

​Response

​Errors

​Authentication

​Transport & signing matrix

Body

Response

Flow

Request Body

Response

Errors

Authentication

Transport & signing matrix