> For the complete documentation index, see [llms.txt](https://docs.opinion.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opinion.trade/developer-guide/opinion-clob-python-sdk/builder-mode/split-merge-redeem.md).

# Split / Merge / Redeem

> Build Safe transactions for on-chain token operations.

All methods in this page follow the same pattern: **build** the transaction, have the **user sign** it, then **submit** it to the backend for relay.

## Common Pattern

```python
# 1. Build the transaction
tx_result = builder.build_split_tx(...)   # or build_merge_tx, build_redeem_tx, build_withdraw_tx

# 2. User signs the EIP-712 data
signature = user.sign_typed_data(tx_result["eip712_data"])

# 3. Submit to backend
result = builder.submit_safe_tx(
    wallet_address=user_address,
    safe_tx_result=tx_result,
    signature=signature,
)
```

All build methods return:

```python
{
    "safe_tx": <SafeTx>,             # SafeTx object
    "eip712_data": { ... },          # EIP-712 data for user signing
    "safe_tx_hash": "0xabcdef...",   # Safe transaction hash
    "submission_data_template": { ... },
}
```

## Split Position

Convert collateral tokens (e.g., USDC) into Yes and No outcome tokens.

```python
tx_result = builder.build_split_tx(
    safe_address="0xSafeAddress...",
    collateral_token="0xQuoteTokenAddress...",
    condition_id="0xConditionId...",
    amount=1000000,          # Amount in wei (e.g., 1 USDC = 1000000 for 6 decimals)
    partition=[1, 2],        # Default: [1, 2] for binary outcomes
)
```

| Parameter          | Type       | Required | Description                                           |
| ------------------ | ---------- | -------- | ----------------------------------------------------- |
| `safe_address`     | str        | Yes      | User's Safe wallet address                            |
| `collateral_token` | str        | Yes      | Quote token contract address                          |
| `condition_id`     | str        | Yes      | Market condition ID (hex string, from `get_market()`) |
| `amount`           | int        | Yes      | Amount in wei                                         |
| `partition`        | list\[int] | No       | Partition array (default: `[1, 2]`)                   |

## Merge Position

Convert equal amounts of Yes and No outcome tokens back into collateral.

```python
tx_result = builder.build_merge_tx(
    safe_address="0xSafeAddress...",
    collateral_token="0xQuoteTokenAddress...",
    condition_id="0xConditionId...",
    amount=1000000,
    partition=[1, 2],
)
```

Parameters are identical to `build_split_tx()`.

## Redeem Position

Claim winnings from a resolved market. Converts winning outcome tokens back into collateral.

```python
tx_result = builder.build_redeem_tx(
    safe_address="0xSafeAddress...",
    collateral_token="0xQuoteTokenAddress...",
    condition_id="0xConditionId...",
    partition=[1, 2],
)
```

| Parameter          | Type       | Required | Description                         |
| ------------------ | ---------- | -------- | ----------------------------------- |
| `safe_address`     | str        | Yes      | User's Safe wallet address          |
| `collateral_token` | str        | Yes      | Quote token contract address        |
| `condition_id`     | str        | Yes      | Market condition ID                 |
| `partition`        | list\[int] | No       | Partition array (default: `[1, 2]`) |

Note: `build_redeem_tx()` does not take an `amount` parameter. It redeems all eligible tokens.

## Withdraw Tokens

Transfer ERC20 tokens from the Safe wallet to any address.

```python
tx_result = builder.build_withdraw_tx(
    safe_address="0xSafeAddress...",
    token_address="0xTokenAddress...",
    amount=1000000,              # Amount in wei
    to_address="0xRecipientAddress...",
)
```

| Parameter       | Type | Required | Description                     |
| --------------- | ---- | -------- | ------------------------------- |
| `safe_address`  | str  | Yes      | User's Safe wallet address      |
| `token_address` | str  | Yes      | ERC20 token address to withdraw |
| `amount`        | int  | Yes      | Amount in wei                   |
| `to_address`    | str  | Yes      | Recipient address               |

## Submit Safe Transaction

All build methods produce a result that is submitted via `submit_safe_tx()`:

```python
result = builder.submit_safe_tx(
    wallet_address=user_address,      # User's EOA address
    safe_tx_result=tx_result,
    signature=signature,
)
```

| Parameter        | Type | Required | Description                            |
| ---------------- | ---- | -------- | -------------------------------------- |
| `wallet_address` | str  | Yes      | User's EOA wallet address (Safe owner) |
| `safe_tx_result` | dict | Yes      | Result from any `build_*_tx()` method  |
| `signature`      | str  | Yes      | User's signature on the EIP-712 data   |

## Testing Helper

For testing, you can sign Safe transactions with a private key directly:

```python
signature = BuilderClient.sign_safe_tx_with_private_key(
    tx_result["eip712_data"],
    "0xPrivateKey...",
)
```

## Notes

* All methods require `rpc_url` to be set in the `BuilderClient` constructor.
* Amounts for `build_split_tx()`, `build_merge_tx()`, and `build_withdraw_tx()` must be in **wei** (smallest token unit). Use `safe_amount_to_wei(amount, decimals)` from `opinion_clob_sdk.builder_sdk` for conversion.
* The backend relays these transactions on-chain; no gas is needed from the user.
* On-chain confirmation typically takes 30-60 seconds.
* The `condition_id` is available from `get_market()` response (`market.condition_id`).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.opinion.trade/developer-guide/opinion-clob-python-sdk/builder-mode/split-merge-redeem.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.