Split / Merge / Redeem

Build, sign, and submit Safe transactions for on-chain token operations.

All four operations follow the same pattern: build the transaction, have the user sign it, then submit.

Common Signing Pattern

import { BuilderClient, UserClient } from '@opinion-labs/opinion-clob-sdk';

const builder = new BuilderClient({
  host: 'https://openapi.opinion.trade/openapi',
  builderApiKey: 'YOUR_BUILDER_KEY',
  chainId: 56,
  rpcUrl: 'https://bsc-dataseed.binance.org',
});

// Build any Safe TX (split, merge, redeem, or withdraw)
const txResult = await builder.buildSplitTx(safeAddress, collateral, conditionId, amount);

// User signs the EIP-712 typed data
const user = new UserClient('0xUserPrivateKey...');
const signature = await user.signTypedData(txResult.eip712Data);

// Submit to backend for relay
const result = await builder.submitSafeTx(userAddress, txResult, signature);

Split Position

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

const txResult = await builder.buildSplitTx(
  safeAddress,          // User's Safe wallet address
  collateralToken,      // Quote token address (e.g., USDC)
  conditionId,          // Market condition ID (from getMarket())
  1000000n,             // Amount in wei (e.g., 1 USDC = 1000000 with 6 decimals)
);

Parameter	Type	Required	Description
safeAddress	string	Yes	User's Safe wallet address
collateralToken	string	Yes	Quote token contract address
conditionId	string	Yes	Market condition ID
amount	bigint	Yes	Amount in wei
partition	number[]	No	Outcome partition (default: [1, 2] for binary markets)

Merge Position

Convert equal amounts of Yes and No tokens back into quote tokens.

const txResult = await builder.buildMergeTx(
  safeAddress,
  collateralToken,
  conditionId,
  1000000n,
);

Parameter	Type	Required	Description
safeAddress	string	Yes	User's Safe wallet address
collateralToken	string	Yes	Quote token contract address
conditionId	string	Yes	Market condition ID
amount	bigint	Yes	Amount in wei
partition	number[]	No	Outcome partition (default: [1, 2])

Redeem Position

Claim winnings from a resolved market. Converts winning outcome tokens back to quote tokens.

const txResult = await builder.buildRedeemTx(
  safeAddress,
  collateralToken,
  conditionId,
);

Parameter	Type	Required	Description
safeAddress	string	Yes	User's Safe wallet address
collateralToken	string	Yes	Quote token contract address
conditionId	string	Yes	Market condition ID
partition	number[]	No	Outcome partition (default: [1, 2])

Withdraw Tokens

Transfer ERC20 tokens from the Safe wallet to any address.

const txResult = await builder.buildWithdrawTx(
  safeAddress,          // From: user's Safe wallet
  tokenAddress,         // ERC20 token to withdraw
  1000000n,             // Amount in wei
  recipientAddress,     // To: destination address
);

Parameter	Type	Required	Description
safeAddress	string	Yes	User's Safe wallet address
tokenAddress	string	Yes	ERC20 token contract address
amount	bigint	Yes	Amount in wei
toAddress	string	Yes	Recipient address

Submit Safe Transaction

All build methods return a SafeTxResult. Submit it with a user signature:

const result = await builder.submitSafeTx(userAddress, txResult, signature);

Parameter	Type	Required	Description
walletAddress	string	Yes	User's wallet address (Safe owner EOA)
safeTxResult	SafeTxResult	Yes	Result from any build*Tx() method
signature	string	Yes	User's signature on the EIP-712 data

Test Helper

For testing, sign Safe transactions with a private key:

const signature = await BuilderClient.signSafeTxWithPrivateKey(
  txResult.eip712Data,
  '0xPrivateKey...',
);

Notes

• All Safe TX operations require rpcUrl in the BuilderClient config.

• Transactions are relayed by the backend -- no gas required from the user.

• Safe TX signing uses user.signTypedData(eip712Data), not signHash().

• For amount conversions, use safeAmountToWei() from the SDK:

  import { safeAmountToWei } from '@opinion-labs/opinion-clob-sdk';
  const weiAmount = safeAmountToWei(5.0, 6); // 5 USDC -> 5000000n

• The conditionId for split, merge, and redeem is available from getMarket().

• Redeem only works on resolved markets with winning outcome tokens.