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

# 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:

{
    "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.

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.

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.

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.

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():

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:

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).