Merge Outcome Set Into Collateral

Submits an on-chain mergePositions transaction that converts a full set of outcome tokens (1 Yes share + 1 No share → 1 USDC) back into collateral from a server-wallet sub-account.

Route: POST /portfolio/merge
Auth: apiToken, Privy, or session auth
Scope: trading when using apiToken

For what merging is and when to use it, see Merging & Splitting Shares.

Request body

Field	Type	Required	Description
`conditionId`	`string`	Yes	CTF condition id (`bytes32` hex string) of the market.
`amount`	`string`	Yes	Number of complete sets to convert back, in collateral base units (USDC = 6 decimals, so `1000000` = 1 full set).
`venue`	`object`	Yes	Venue object from the market response. Pass `venue.exchange` for simple/CLOB markets and `venue.adapter` for NegRisk markets. When `adapter` is present, the operation routes through the NegRiskAdapter; otherwise it routes through ConditionalTokens.
`onBehalfOf`	`number`	No	Managed sub-account profile id (partner flow). Must be a child of the authenticated partner profile.

Example (HMAC)

curl -X POST "https://api.limitless.exchange/portfolio/merge" \
  -H "content-type: application/json" \
  -H "lmts-api-key: <tokenId>" \
  -H "lmts-signature: <base64_hmac_sha256_signature>" \
  -H "lmts-timestamp: <iso_8601_timestamp>" \
  -d '{
    "conditionId": "0xa0ba8fd0acc2b86585734c07eb3bef4133f584d5abde78a558a6b8bfc3bbdec0",
    "amount": "1000000",
    "venue": { "exchange": "0xe3E00BA3a9888d1DE4834269f62ac008b4BB5C47" }
  }'

Response

Returns the submitted transaction: conditionId, operation (MERGE), route (clob or negrisk), walletAddress, and, when available, transactionId and userOperationHash. Sponsored 4337 user operations return no synchronous transaction hash, so track the operation via userOperationHash and transactionId.

Errors

Status	Meaning
`400`	Invalid `amount`, `conditionId`, or adapter address.
`401`	Unauthorized.
`403`	No server wallet on the target profile, or insufficient token scopes.
`409`	A split or merge for this profile is already in progress.

Notes

The execute path is a single on-chain transaction. Limitless provisions the NegRiskAdapter ERC-1155 approval on the server wallet ahead of time, so no approval transaction is submitted here.
Merging burns the wallet’s own outcome tokens, so simple/CLOB merges need no allowance at all.
Validation is minimal by design: on-chain failures pass through to the caller, who retries if needed.
Legacy API keys are not supported on server-wallet operations.

Why this endpoint is server-wallet only. Merging outcome tokens is an on-chain transaction that must be signed by the wallet holding the shares. This endpoint can only sign for wallets Limitless manages (Privy-backed server-wallet sub-accounts). EOA and user-owned smart-wallet users merge through the Merge/Split option on the market page in the Limitless UI, or by calling mergePositions on the Conditional Tokens Framework contract directly. See Smart Contracts for the deployed addresses.

Overview

System

Authentication

Markets

Trading

Portfolio

Market Pages & Navigation

API Tokens

Partner Accounts

Public Portfolio

Referral

Leaderboard

Merge Outcome Set Into Collateral

Request body

Example (HMAC)

Response

Errors

Notes

​Request body

​Example (HMAC)

​Response

​Errors

​Notes

Request body

Example (HMAC)

Response

Errors

Notes