Build close-position payload
Execution
Build Close-Position Payload
Build a signed canonical payload to close (fully or partially) an open perpetual position on Gains Network or Lighter.
POST
Build close-position payload
Builds the payload for closing an existing position. Close size is either explicit (
amountRaw) or percentage-based (closePercentage).
Request Body
gains or lighter.Chain of the position (e.g.,
evm:42161, lighter:301).Mobula market identifier (e.g.,
lighter-btc-usd).Gains only — required. The Gains trade index, sent as a string that parses as a non-negative integer (e.g.
"0", "919").Not used for Lighter.Portion of the position to close, in percent (
0 < value ≤ 100). Use 100 for a full close. Mutually exclusive with amountRaw.Raw base-token amount to close. Mutually exclusive with
closePercentage.Additional DEX-specific parameters. For Gains partial closes, the API transparently injects
currentCollateralRaw from the position cache when available, so you do not need to supply it.Authentication
Every/2/perp/payloads/<action> endpoint verifies the caller by requiring two extra fields in the request body alongside the action parameters:
Unix timestamp in milliseconds. Must be within 30 seconds of server time. Older timestamps are rejected to prevent replay.
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.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).Endpoint-specific errors
| Status | message |
|---|---|
| 400 | close-position payload generation failed — position not found, invalid close size, or DEX refusal |
Full flow — close a position end-to-end
Single example covering both DEXes (Lighter offchain-api, Gains evm-tx). The flow branches ondata.transport.
Body
application/json
Available options:
gains, lighter Gains trade index. Required for Gains.
Portion to close (0 < value ≤ 100). Mutually exclusive with amountRaw.
Raw base-token amount to close. Mutually exclusive with closePercentage.