> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/user-guide/merge-split).

### 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](/api-reference/markets/get-market). 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)

```bash theme={null}
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.

<Info>
  **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](/user-guide/smart-contracts) for the deployed addresses.
</Info>