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

# Split and Merge Outcomes

> Splits collateral into Yes/No shares or merges complete sets back into collateral.

```json 200 theme={null}
{
  "status": "ok",
  "response": {
    "type": "outcomeOperation",
    "data": {
      "actionId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "adapter": "hyperliquid",
      "operation": "merge",
      "status": "pending"
    }
  }
}
```

```json 400 theme={null}
{
  "error": "No available outcome balance to merge",
  "code": "VALIDATION_FAILED",
  "timestamp": 1785254400000
}
```

```json 401 theme={null}
{
  "error": "Invalid signature",
  "code": "UNAUTHORIZED",
  "timestamp": 1785254400000
}
```

```json 503 theme={null}
{
  "error": "Polymarket position-operation policy is unavailable",
  "code": "SERVICE_UNAVAILABLE",
  "timestamp": 1785254400000,
  "retryAfter": 5
}
```

Hyperliquid
Polymarket

POST
`/exchange`

## Request Body

**action** `object` *required*

Signed action containing exactly one of `splitOutcome` or `mergeOutcome`. Requires protocol
access and an account that is neither frozen nor in active liquidation.

**child attributes**

**type** `string` *required*

Must be `"userOutcome"`.

> **Hyperliquid merge**
>
> **mergeOutcome** `object` *required*
>
> Reserves equal Yes and No shares. Completion credits one USDC per complete set;
> failure releases the reserved shares.
>
> **child attributes**
>
> **outcome** `number` *required*
>
> Nonnegative integer outcome ID from [prediction metadata](/api-reference/info-endpoints/prediction-meta).
> Both sides must be USDC-quoted.
>
> **amount** `string | null` *required*
>
> Positive integer complete-set count within both sides' unreserved balances, or
> `null` to merge the maximum available whole sets. One set consumes one Yes and
> one No share. Exact retries reuse the original resolved amount.

> **Polymarket split and merge**
>
> **splitOutcome** `object`
>
> Reserves available pUSD without borrowing; checks margin and existing borrow support
> after reservation. Completion credits equal Yes and No shares; failure releases
> pUSD. Omit `mergeOutcome`. The operation must be enabled; version 2 operation and
> market objects reject extra fields, and the request does not accept `expiresAfter`.
>
> **child attributes**
>
> **schemaVersion** `number` *required*
>
> Must be `2`.
>
> **market** `object` *required*
>
> Supported, open Polymarket condition. The signed identities and `negRisk` must
> match the registered condition; use the matching sides from
> [prediction metadata](/api-reference/info-endpoints/prediction-meta).
>
> **child attributes**
>
> **adapter** `string` *required*
>
> Must be `"polymarket"`.
>
> **conditionId** `string` *required*
>
> Nonzero lowercase, `0x`-prefixed 32-byte condition ID.
>
> **yesAssetId** `string` *required*
>
> Canonical Yes-side AssetId matching the condition: `0x1001` followed by the
> token ID encoded as 64 lowercase hex characters.
>
> **noAssetId** `string` *required*
>
> Canonical No-side AssetId matching the condition, in the same format as
> `yesAssetId`. The two AssetIds must be distinct.
>
> **negRisk** `boolean` *required*
>
> Negative-risk classification matching the condition.
>
> **amountBaseUnits** `string` *required*
>
> Positive uint256 decimal integer string with no leading zeros, whitespace, or
> decimal point. In micro-pUSD: `"500000"` spends 0.5 pUSD to create 0.5 Yes and
> 0.5 No shares. An explicit amount is required; `null` is unsupported.
>
> **mergeOutcome** `object`
>
> Uses the same `schemaVersion`, `market`, and `amountBaseUnits` fields and validation
> rules as `splitOutcome`. Omit `splitOutcome`. Here, `amountBaseUnits` is micro-shares
> of each side: `"500000"` merges 0.5 Yes and 0.5 No shares into 0.5 pUSD. Reserves equal
> unreserved Yes and No shares; failure releases them. The operation must be enabled.

**nonce** `number` *required*

Unique nonnegative safe integer nonce in Unix milliseconds; follow the [nonce
rules](/api-reference/nonces-and-api-wallets#notional-nonces). Resend the identical signed request
for a retry; it returns the existing operation state.

**signature** `object` *required*

Account owner or approved API wallet; use the [exchange signing format](/api-reference/signing#signing-formats).

**child attributes**

**r** `string` *required*

ECDSA `r` component as a `0x`-prefixed 32-byte hex string.

**s** `string` *required*

ECDSA `s` component as a `0x`-prefixed 32-byte hex string.

**v** `number` *required*

ECDSA recovery value, for example `27`.

## Response

```json 200 theme={null}
{
  "status": "ok",
  "response": {
    "type": "outcomeOperation",
    "data": {
      "actionId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "adapter": "hyperliquid",
      "operation": "merge",
      "status": "pending"
    }
  }
}
```

```json 400 theme={null}
{
  "error": "No available outcome balance to merge",
  "code": "VALIDATION_FAILED",
  "timestamp": 1785254400000
}
```

```json 401 theme={null}
{
  "error": "Invalid signature",
  "code": "UNAUTHORIZED",
  "timestamp": 1785254400000
}
```

```json 503 theme={null}
{
  "error": "Polymarket position-operation policy is unavailable",
  "code": "SERVICE_UNAVAILABLE",
  "timestamp": 1785254400000,
  "retryAfter": 5
}
```

## Response Fields

**status** `string`

`"ok"` when an operation state is returned; completion is reported in `response.data.status`. An
exact retry can return `"error"` with a top-level `error` message.

**error** `string`

Present when the top-level `status` is `"error"`; `response` is then omitted.

**response.type** `string`

Always `"outcomeOperation"`.

**response.data.actionId** `string`

Stable operation ID. Query [non-funding
history](/api-reference/info-endpoints/user-non-funding-ledger-updates) with the account owner's
`user` address and this value as `operationId` to track settlement. An empty result can reflect
read-replica delay.

**response.data.adapter** `string`

`"hyperliquid"` or `"polymarket"`.

**response.data.operation** `string`

`"split"` or `"merge"`. Hyperliquid supports merge only.

**response.data.status** `string`

* `pending`: accepted; awaiting execution or confirmation.
* `active`: execution recorded; awaiting confirmation. Polymarket only.
* `needs_reconciliation`: outcome unconfirmed; funds remain reserved. Polymarket only.
* `completed`: collateral or shares credited. Terminal.
* `failed`: reservation released. Terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.