> 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.