poly-web3 1.0.1__tar.gz → 1.0.2__tar.gz

{poly_web3-1.0.1 → poly_web3-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: poly-web3
-Version: 1.0.1
+Version: 1.0.2
 Summary: Polymarket Proxy wallet redeem SDK - Execute redeem operations on Polymarket using proxy wallets
 Home-page: https://github.com/tosmart01/poly-web3
 Author: PinBar
@@ -27,11 +27,16 @@ Dynamic: requires-python
 
 # poly-web3
 
-Python SDK for redeeming Polymarket positions via Proxy/Safe wallets (gas-free).
+![PyPI](https://img.shields.io/pypi/v/poly-web3)
+![Python](https://img.shields.io/pypi/pyversions/poly-web3)
+![License](https://img.shields.io/github/license/tosmart01/poly-web3)
+
+Python SDK for redeeming and splitting/merging Polymarket positions via Proxy/Safe wallets (gas-free).
 
 [English](README.md) | [中文](README.zh.md)
 
 ```bash
+Python >= 3.11
 pip install poly-web3
 ```
 
@@ -44,7 +49,11 @@ service = PolyWeb3Service(
 )
 
 # Redeem all redeemable positions for the current account.
-service.redeem_all(batch_size=20)
+service.redeem_all(batch_size=10)
+
+# Split/Merge for binary markets (amount in human USDC units).
+service.split("0x...", 10)
+service.merge("0x...", 10)
 ```
 
 [See the full example](#quick-start)
@@ -54,18 +63,25 @@ service.redeem_all(batch_size=20)
 - Redeemable positions are fetched via the official Positions API, which typically has ~1 minute latency.
 - `redeem_all` returns an empty list if there are no redeemable positions. If the returned list contains `None`, the redeem failed and should be retried.
 
-## Troubleshooting
+## Split/Merge Notes
+
+- `split`/`merge` are designed for binary markets (Yes/No) and use the default partition internally.
+- `amount` is in human units (USDC), and is converted to base units internally.
+
+## FAQ
 
 1. **UI shows redeemable, but `redeem_all` returns `[]`**: The official Positions API can be delayed by 1–3 minutes. Wait a bit and retry.
 2. **RPC error during redeem**: Switch RPC endpoints by setting `rpc_url` when instantiating `PolyWeb3Service`.
 3. **Redeem stuck in `execute`**: The official relayer may be congested. Stop redeeming for 1 hour to avoid nonce looping from repeated submissions.
+4. **Relayer client returns 403**: You need to apply for Builder API access and use a valid key. Reference: Polymarket Builders — Introduction: https://docs.polymarket.com/developers/builders/builder-intro
+5. **Relayer daily limit**: The official relayer typically limits to 100 requests per day. Prefer batch redeem (`batch_size`) to reduce the number of requests and avoid hitting the limit.
 
 ## About the Project
 
 This project is a Python rewrite of Polymarket's official TypeScript implementation of `builder-relayer-client`, designed to provide Python developers with a convenient tool for executing Proxy and Safe wallet redeem operations on Polymarket.
 
 **Important Notes:**
-- This project **only implements the official redeem functionality**, focusing on Conditional Token Fund (CTF) redeem operations
+- This project implements official CTF redeem plus binary split/merge operations
 - Other features (such as trading, order placement, etc.) are not within the scope of this project
 
 **Some Polymarket-related redeem or write operations implemented in this project depend on access granted through Polymarket's Builder program. To perform real redeem operations against Polymarket, you must apply for and obtain a Builder key/credentials via Polymarket's official Builder application process. After approval you will receive the credentials required to use the Builder API—only then will the redeem flows in this repository work against the live service. For local development or automated tests, use mocks or testnet setups instead of real keys to avoid exposing production credentials.**
@@ -74,8 +90,8 @@ Reference：
 - Polymarket Builders — Introduction: https://docs.polymarket.com/developers/builders/builder-intro
 
 **Current Status:**
-- ✅ **Proxy Wallet** - Fully supported for redeem functionality
-- ✅ **Safe Wallet** - Fully supported for redeem functionality
+- ✅ **Proxy Wallet** - Fully supported for redeem/split/merge
+- ✅ **Safe Wallet** - Fully supported for redeem/split/merge
 - 🚧 **EOA Wallet** - Under development
 
 We welcome community contributions! If you'd like to help implement EOA wallet redeem functionality, or have other improvement suggestions, please feel free to submit a Pull Request.
@@ -153,21 +169,41 @@ service = PolyWeb3Service(
 )
 
 
+# Redeem all positions that are currently redeemable
+redeem_all_result = service.redeem_all(batch_size=10)
+print(f"Redeem all result: {redeem_all_result}")
+# If redeem_all_result contains None, refer to README FAQ and retry.
+if redeem_all_result and any(item is None for item in redeem_all_result):
+    print("Redeem failed for some items; please retry.")
+
 # Execute redeem operation (batch)
 condition_ids = [
     "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c",
     "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
 ]
-redeem_batch_result = service.redeem(condition_ids, batch_size=20)
+redeem_batch_result = service.redeem(condition_ids, batch_size=10)
 print(f"Redeem batch result: {redeem_batch_result}")
-
-# Redeem all positions that are currently redeemable
-redeem_all_result = service.redeem_all(batch_size=20)
-print(f"Redeem all result: {redeem_all_result}")
 if redeem_all_result and any(item is None for item in redeem_all_result):
     print("Redeem failed for some items; please retry.")
 ```
 
+### Basic Usage - Split/Merge (Binary Markets)
+
+```python
+# amount is in human units (USDC)
+split_result = service.split(
+    "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
+    1.5,
+)
+print(f"Split result: {split_result}")
+
+merge_result = service.merge(
+    "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
+    1.5,
+)
+print(f"Merge result: {merge_result}")
+```
+
 ## API Documentation
 
 ### PolyWeb3Service
@@ -191,7 +227,7 @@ Execute redeem operation.
 
 ```python
 # Batch redeem
-result = service.redeem(["0x...", "0x..."], batch_size=20)
+result = service.redeem(["0x...", "0x..."], batch_size=10)
 ```
 
 ##### `redeem_all(batch_size: int = 20) -> list[dict]`
@@ -205,7 +241,41 @@ Redeem all positions that are currently redeemable for the authenticated account
 
 ```python
 # Redeem all positions that can be redeemed
-service.redeem_all(batch_size=20)
+service.redeem_all(batch_size=10)
+```
+
+##### `split(condition_id: str, amount: int | float | str)`
+
+Split a binary (Yes/No) position. `amount` is in human USDC units.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `amount` (int | float | str): Amount in USDC
+
+**Returns:**
+- `dict | None`: Transaction result
+
+**Examples:**
+
+```python
+result = service.split("0x...", 1.25)
+```
+
+##### `merge(condition_id: str, amount: int | float | str)`
+
+Merge a binary (Yes/No) position. `amount` is in human USDC units.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `amount` (int | float | str): Amount in USDC
+
+**Returns:**
+- `dict | None`: Transaction result
+
+**Examples:**
+
+```python
+result = service.merge("0x...", 1.25)
 ```
 
 #### Optional APIs
@@ -281,7 +351,7 @@ poly_web3/
 
 1. **Environment Variable Security**: Make sure `.env` file is added to `.gitignore`, do not commit sensitive information to the code repository
 2. **Network Support**: Currently mainly supports Polygon mainnet (chain_id: 137), Amoy testnet may have limited functionality
-3. **Wallet Type**: Proxy (signature_type: 1) and Safe (signature_type: 2) are supported; EOA wallet redeem functionality is under development
+3. **Wallet Type**: Proxy (signature_type: 1) and Safe (signature_type: 2) are supported; EOA wallet operations are under development
 4. **Gas Fees**: Transactions are executed through Relayer, gas fees are handled by the Relayer
 
 ## Development
@@ -296,18 +366,18 @@ uv pip install -e ".[dev]"
 
 ```bash
 python examples/example_redeem.py
+python examples/example_split_merge.py
 ```
 
 ### Contributing
 
-We welcome all forms of contributions! If you'd like to:
-
-- Implement EOA wallet support
-- Fix bugs or improve existing functionality
-- Add new features or improve documentation
-- Make suggestions or report issues
+Simple contribution flow:
 
-Please feel free to submit an Issue or Pull Request. Your contributions will help make this project better!
+1. Open an Issue to describe the change (bug/feature/doc).
+2. Fork and create a branch: `feat/xxx` or `fix/xxx`.
+3. Make changes and update/add docs if needed.
+4. Run: `uv run python -m examples.example_redeem` or `uv run python -m examples.example_split_merge` (if applicable).
+5. Open a Pull Request and link the Issue.
 
 ## License
 

{poly_web3-1.0.1 → poly_web3-1.0.2}/README.md

@@ -1,10 +1,15 @@
 # poly-web3
 
-Python SDK for redeeming Polymarket positions via Proxy/Safe wallets (gas-free).
+![PyPI](https://img.shields.io/pypi/v/poly-web3)
+![Python](https://img.shields.io/pypi/pyversions/poly-web3)
+![License](https://img.shields.io/github/license/tosmart01/poly-web3)
+
+Python SDK for redeeming and splitting/merging Polymarket positions via Proxy/Safe wallets (gas-free).
 
 [English](README.md) | [中文](README.zh.md)
 
 ```bash
+Python >= 3.11
 pip install poly-web3
 ```
 
@@ -17,7 +22,11 @@ service = PolyWeb3Service(
 )
 
 # Redeem all redeemable positions for the current account.
-service.redeem_all(batch_size=20)
+service.redeem_all(batch_size=10)
+
+# Split/Merge for binary markets (amount in human USDC units).
+service.split("0x...", 10)
+service.merge("0x...", 10)
 ```
 
 [See the full example](#quick-start)
@@ -27,18 +36,25 @@ service.redeem_all(batch_size=20)
 - Redeemable positions are fetched via the official Positions API, which typically has ~1 minute latency.
 - `redeem_all` returns an empty list if there are no redeemable positions. If the returned list contains `None`, the redeem failed and should be retried.
 
-## Troubleshooting
+## Split/Merge Notes
+
+- `split`/`merge` are designed for binary markets (Yes/No) and use the default partition internally.
+- `amount` is in human units (USDC), and is converted to base units internally.
+
+## FAQ
 
 1. **UI shows redeemable, but `redeem_all` returns `[]`**: The official Positions API can be delayed by 1–3 minutes. Wait a bit and retry.
 2. **RPC error during redeem**: Switch RPC endpoints by setting `rpc_url` when instantiating `PolyWeb3Service`.
 3. **Redeem stuck in `execute`**: The official relayer may be congested. Stop redeeming for 1 hour to avoid nonce looping from repeated submissions.
+4. **Relayer client returns 403**: You need to apply for Builder API access and use a valid key. Reference: Polymarket Builders — Introduction: https://docs.polymarket.com/developers/builders/builder-intro
+5. **Relayer daily limit**: The official relayer typically limits to 100 requests per day. Prefer batch redeem (`batch_size`) to reduce the number of requests and avoid hitting the limit.
 
 ## About the Project
 
 This project is a Python rewrite of Polymarket's official TypeScript implementation of `builder-relayer-client`, designed to provide Python developers with a convenient tool for executing Proxy and Safe wallet redeem operations on Polymarket.
 
 **Important Notes:**
-- This project **only implements the official redeem functionality**, focusing on Conditional Token Fund (CTF) redeem operations
+- This project implements official CTF redeem plus binary split/merge operations
 - Other features (such as trading, order placement, etc.) are not within the scope of this project
 
 **Some Polymarket-related redeem or write operations implemented in this project depend on access granted through Polymarket's Builder program. To perform real redeem operations against Polymarket, you must apply for and obtain a Builder key/credentials via Polymarket's official Builder application process. After approval you will receive the credentials required to use the Builder API—only then will the redeem flows in this repository work against the live service. For local development or automated tests, use mocks or testnet setups instead of real keys to avoid exposing production credentials.**
@@ -47,8 +63,8 @@ Reference：
 - Polymarket Builders — Introduction: https://docs.polymarket.com/developers/builders/builder-intro
 
 **Current Status:**
-- ✅ **Proxy Wallet** - Fully supported for redeem functionality
-- ✅ **Safe Wallet** - Fully supported for redeem functionality
+- ✅ **Proxy Wallet** - Fully supported for redeem/split/merge
+- ✅ **Safe Wallet** - Fully supported for redeem/split/merge
 - 🚧 **EOA Wallet** - Under development
 
 We welcome community contributions! If you'd like to help implement EOA wallet redeem functionality, or have other improvement suggestions, please feel free to submit a Pull Request.
@@ -126,21 +142,41 @@ service = PolyWeb3Service(
 )
 
 
+# Redeem all positions that are currently redeemable
+redeem_all_result = service.redeem_all(batch_size=10)
+print(f"Redeem all result: {redeem_all_result}")
+# If redeem_all_result contains None, refer to README FAQ and retry.
+if redeem_all_result and any(item is None for item in redeem_all_result):
+    print("Redeem failed for some items; please retry.")
+
 # Execute redeem operation (batch)
 condition_ids = [
     "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c",
     "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
 ]
-redeem_batch_result = service.redeem(condition_ids, batch_size=20)
+redeem_batch_result = service.redeem(condition_ids, batch_size=10)
 print(f"Redeem batch result: {redeem_batch_result}")
-
-# Redeem all positions that are currently redeemable
-redeem_all_result = service.redeem_all(batch_size=20)
-print(f"Redeem all result: {redeem_all_result}")
 if redeem_all_result and any(item is None for item in redeem_all_result):
     print("Redeem failed for some items; please retry.")
 ```
 
+### Basic Usage - Split/Merge (Binary Markets)
+
+```python
+# amount is in human units (USDC)
+split_result = service.split(
+    "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
+    1.5,
+)
+print(f"Split result: {split_result}")
+
+merge_result = service.merge(
+    "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
+    1.5,
+)
+print(f"Merge result: {merge_result}")
+```
+
 ## API Documentation
 
 ### PolyWeb3Service
@@ -164,7 +200,7 @@ Execute redeem operation.
 
 ```python
 # Batch redeem
-result = service.redeem(["0x...", "0x..."], batch_size=20)
+result = service.redeem(["0x...", "0x..."], batch_size=10)
 ```
 
 ##### `redeem_all(batch_size: int = 20) -> list[dict]`
@@ -178,7 +214,41 @@ Redeem all positions that are currently redeemable for the authenticated account
 
 ```python
 # Redeem all positions that can be redeemed
-service.redeem_all(batch_size=20)
+service.redeem_all(batch_size=10)
+```
+
+##### `split(condition_id: str, amount: int | float | str)`
+
+Split a binary (Yes/No) position. `amount` is in human USDC units.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `amount` (int | float | str): Amount in USDC
+
+**Returns:**
+- `dict | None`: Transaction result
+
+**Examples:**
+
+```python
+result = service.split("0x...", 1.25)
+```
+
+##### `merge(condition_id: str, amount: int | float | str)`
+
+Merge a binary (Yes/No) position. `amount` is in human USDC units.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `amount` (int | float | str): Amount in USDC
+
+**Returns:**
+- `dict | None`: Transaction result
+
+**Examples:**
+
+```python
+result = service.merge("0x...", 1.25)
 ```
 
 #### Optional APIs
@@ -254,7 +324,7 @@ poly_web3/
 
 1. **Environment Variable Security**: Make sure `.env` file is added to `.gitignore`, do not commit sensitive information to the code repository
 2. **Network Support**: Currently mainly supports Polygon mainnet (chain_id: 137), Amoy testnet may have limited functionality
-3. **Wallet Type**: Proxy (signature_type: 1) and Safe (signature_type: 2) are supported; EOA wallet redeem functionality is under development
+3. **Wallet Type**: Proxy (signature_type: 1) and Safe (signature_type: 2) are supported; EOA wallet operations are under development
 4. **Gas Fees**: Transactions are executed through Relayer, gas fees are handled by the Relayer
 
 ## Development
@@ -269,18 +339,18 @@ uv pip install -e ".[dev]"
 
 ```bash
 python examples/example_redeem.py
+python examples/example_split_merge.py
 ```
 
 ### Contributing
 
-We welcome all forms of contributions! If you'd like to:
-
-- Implement EOA wallet support
-- Fix bugs or improve existing functionality
-- Add new features or improve documentation
-- Make suggestions or report issues
+Simple contribution flow:
 
-Please feel free to submit an Issue or Pull Request. Your contributions will help make this project better!
+1. Open an Issue to describe the change (bug/feature/doc).
+2. Fork and create a branch: `feat/xxx` or `fix/xxx`.
+3. Make changes and update/add docs if needed.
+4. Run: `uv run python -m examples.example_redeem` or `uv run python -m examples.example_split_merge` (if applicable).
+5. Open a Pull Request and link the Issue.
 
 ## License
 

poly_web3-1.0.2/examples/example_split_merge.py

@@ -0,0 +1,56 @@
+# -*- coding = utf-8 -*-
+# @Time: 2025-12-30 12:00:00
+# @Author: PinBar
+# @Site:
+# @File: example_split_merge.py
+# @Software: PyCharm
+import os
+
+import dotenv
+from py_builder_relayer_client.client import RelayClient
+from py_builder_signing_sdk.config import BuilderConfig
+from py_builder_signing_sdk.sdk_types import BuilderApiKeyCreds
+from py_clob_client.client import ClobClient
+
+from poly_web3 import RELAYER_URL, PolyWeb3Service
+
+dotenv.load_dotenv()
+
+if __name__ == "__main__":
+    host: str = "https://clob.polymarket.com"
+    chain_id: int = 137  # No need to adjust this
+    client = ClobClient(
+        host,
+        key=os.getenv("POLY_API_KEY"),
+        chain_id=chain_id,
+        signature_type=1,  # signature_type=2 for Safe
+        funder=os.getenv("POLYMARKET_PROXY_ADDRESS"),
+    )
+    creds = client.create_or_derive_api_creds()
+    client.set_api_creds(creds)
+    relayer_client = RelayClient(
+        RELAYER_URL,
+        chain_id,
+        os.getenv("POLY_API_KEY"),
+        BuilderConfig(
+            local_builder_creds=BuilderApiKeyCreds(
+                key=os.getenv("BUILDER_KEY"),
+                secret=os.getenv("BUILDER_SECRET"),
+                passphrase=os.getenv("BUILDER_PASSPHRASE"),
+            )
+        ),
+    )
+    service = PolyWeb3Service(
+        clob_client=client,
+        relayer_client=relayer_client,
+        rpc_url="https://polygon-bor.publicnode.com",
+    )
+
+    condition_id = "0x58ec217262554683a6c1fa2de9d87addef26dd3348367824d6890c68a98809b0"
+    amount = 10  # amount in human USDC units
+
+    split_result = service.split(condition_id, amount)
+    print(split_result)
+
+    merge_result = service.merge(condition_id, amount)
+    print(merge_result)

{poly_web3-1.0.1 → poly_web3-1.0.2}/poly_web3/const.py

@@ -15,7 +15,7 @@ GET_DEPLOYED = "/deployed"
 RPC_URL = "https://polygon-bor.publicnode.com" # "https://polygon-rpc.com"
 RELAYER_URL = "https://relayer-v2.polymarket.com"
 
-STATE_NEW = ("STATE_NEW",)
+STATE_NEW = "STATE_NEW"
 STATE_EXECUTED = "STATE_EXECUTED"
 STATE_MINED = "STATE_MINED"
 STATE_INVALID = "STATE_INVALID"
@@ -78,6 +78,70 @@ CTF_ABI_REDEEM = [
     }
 ]
 
+CTF_ABI_SPLIT = [
+    {
+        "name": "splitPosition",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "collateralToken", "type": "address"},
+            {"name": "parentCollectionId", "type": "bytes32"},
+            {"name": "conditionId", "type": "bytes32"},
+            {"name": "partition", "type": "uint256[]"},
+            {"name": "amount", "type": "uint256"},
+        ],
+        "outputs": [],
+    }
+]
+
+CTF_ABI_MERGE = [
+    {
+        "name": "mergePositions",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "collateralToken", "type": "address"},
+            {"name": "parentCollectionId", "type": "bytes32"},
+            {"name": "conditionId", "type": "bytes32"},
+            {"name": "partition", "type": "uint256[]"},
+            {"name": "amount", "type": "uint256"},
+        ],
+        "outputs": [],
+    }
+]
+
+CTF_ABI_SPLIT = [
+    {
+        "name": "splitPosition",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "collateralToken", "type": "address"},
+            {"name": "parentCollectionId", "type": "bytes32"},
+            {"name": "conditionId", "type": "bytes32"},
+            {"name": "partition", "type": "uint256[]"},
+            {"name": "amount", "type": "uint256"},
+        ],
+        "outputs": [],
+    }
+]
+
+CTF_ABI_MERGE = [
+    {
+        "name": "mergePositions",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "collateralToken", "type": "address"},
+            {"name": "parentCollectionId", "type": "bytes32"},
+            {"name": "conditionId", "type": "bytes32"},
+            {"name": "partition", "type": "uint256[]"},
+            {"name": "amount", "type": "uint256"},
+        ],
+        "outputs": [],
+    }
+]
+
 NEG_RISK_ADAPTER_ABI_REDEEM = [
     {
         "name": "redeemPositions",

{poly_web3-1.0.1 → poly_web3-1.0.2}/poly_web3/web3_service/base.py

@@ -5,6 +5,7 @@
 # @File: base.py
 # @Software: PyCharm
 from typing import Any
+from decimal import Decimal, InvalidOperation, ROUND_DOWN
 
 from py_builder_relayer_client.client import RelayClient
 from py_clob_client.client import ClobClient
@@ -19,6 +20,8 @@ from poly_web3.const import (
     ZERO_BYTES32,
     USDC_POLYGON,
     CTF_ABI_REDEEM,
+    CTF_ABI_SPLIT,
+    CTF_ABI_MERGE,
     NEG_RISK_ADAPTER_ADDRESS,
     RELAYER_URL,
     POL,
@@ -157,6 +160,40 @@ class BaseWeb3Service:
             [1, 2],
         )._encode_transaction_data()
 
+    def build_ctf_split_tx_data(
+            self,
+            condition_id: str,
+            partition: list[int],
+            amount: int,
+            collateral_token: str = USDC_POLYGON,
+            parent_collection_id: str = ZERO_BYTES32,
+    ) -> str:
+        ctf = self.w3.eth.contract(address=CTF_ADDRESS, abi=CTF_ABI_SPLIT)
+        return ctf.functions.splitPosition(
+            collateral_token,
+            parent_collection_id,
+            condition_id,
+            partition,
+            amount,
+        )._encode_transaction_data()
+
+    def build_ctf_merge_tx_data(
+            self,
+            condition_id: str,
+            partition: list[int],
+            amount: int,
+            collateral_token: str = USDC_POLYGON,
+            parent_collection_id: str = ZERO_BYTES32,
+    ) -> str:
+        ctf = self.w3.eth.contract(address=CTF_ADDRESS, abi=CTF_ABI_MERGE)
+        return ctf.functions.mergePositions(
+            collateral_token,
+            parent_collection_id,
+            condition_id,
+            partition,
+            amount,
+        )._encode_transaction_data()
+
     def build_neg_risk_redeem_tx_data(
             self, condition_id: str, redeem_amounts: list[int]
     ) -> str:
@@ -171,6 +208,9 @@ class BaseWeb3Service:
     def _build_redeem_tx(self, to: str, data: str) -> Any:
         raise NotImplementedError("redeem tx builder not implemented")
 
+    def _build_ctf_tx(self, to: str, data: str) -> Any:
+        return self._build_redeem_tx(to, data)
+
     def _build_redeem_txs_from_positions(self, positions: list[dict]) -> list[Any]:
         neg_amounts_by_condition: dict[str, list[float]] = {}
         normal_conditions: set[str] = set()
@@ -207,8 +247,11 @@ class BaseWeb3Service:
             )
         return txs
 
+    def _submit_transactions(self, txs: list[Any], metadata: str) -> dict | None:
+        raise NotImplementedError("transaction submit not implemented")
+
     def _submit_redeem(self, txs: list[Any]) -> dict | None:
-        raise NotImplementedError("redeem submit not implemented")
+        return self._submit_transactions(txs, "redeem")
 
     def _redeem_batch(self, condition_ids: list[str], batch_size: int) -> list[dict]:
         """
@@ -312,6 +355,26 @@ class BaseWeb3Service:
             for i in range(0, len(condition_ids), batch_size)
         ]
 
+    @staticmethod
+    def _to_usdc_base_units(amount: int | float | str | Decimal) -> int:
+        try:
+            if isinstance(amount, Decimal):
+                human = amount
+            elif isinstance(amount, int):
+                human = Decimal(amount)
+            else:
+                human = Decimal(str(amount))
+        except (InvalidOperation, ValueError) as exc:
+            raise Exception(f"invalid amount: {amount}") from exc
+        if human <= 0:
+            raise Exception("amount must be greater than 0")
+        base_units = (human * Decimal("1000000")).quantize(
+            Decimal("1"), rounding=ROUND_DOWN
+        )
+        if base_units <= 0:
+            raise Exception("amount too small after conversion")
+        return int(base_units)
+
     def redeem(
             self,
             condition_ids: str | list[str],
@@ -330,3 +393,49 @@ class BaseWeb3Service:
         """
         positions = self.fetch_positions(user_address=self._resolve_user_address())
         return self._redeem_from_positions(positions, batch_size)
+
+    def split(
+            self,
+            condition_id: str,
+            amount: int | float | str | Decimal,
+            collateral_token: str = USDC_POLYGON,
+            parent_collection_id: str = ZERO_BYTES32,
+    ) -> dict | None:
+        """
+        Split a position for binary markets (Yes/No), amount in human units.
+        """
+        amount_base_units = self._to_usdc_base_units(amount)
+        tx = self._build_ctf_tx(
+            CTF_ADDRESS,
+            self.build_ctf_split_tx_data(
+                condition_id=condition_id,
+                partition=[1, 2],
+                amount=amount_base_units,
+                collateral_token=collateral_token,
+                parent_collection_id=parent_collection_id,
+            ),
+        )
+        return self._submit_transactions([tx], "split")
+
+    def merge(
+            self,
+            condition_id: str,
+            amount: int | float | str | Decimal,
+            collateral_token: str = USDC_POLYGON,
+            parent_collection_id: str = ZERO_BYTES32,
+    ) -> dict | None:
+        """
+        Merge binary positions (Yes/No) back into a single position, amount in human units.
+        """
+        amount_base_units = self._to_usdc_base_units(amount)
+        tx = self._build_ctf_tx(
+            CTF_ADDRESS,
+            self.build_ctf_merge_tx_data(
+                condition_id=condition_id,
+                partition=[1, 2],
+                amount=amount_base_units,
+                collateral_token=collateral_token,
+                parent_collection_id=parent_collection_id,
+            ),
+        )
+        return self._submit_transactions([tx], "merge")

poly_web3-1.0.2/poly_web3/web3_service/eoa_service.py

@@ -0,0 +1,40 @@
+# -*- coding = utf-8 -*-
+# @Time: 2025-12-27 16:01:09
+# @Author: PinBar
+# @Site:
+# @File: eoa_service.py
+# @Software: PyCharm
+from decimal import Decimal
+
+from poly_web3.const import USDC_POLYGON, ZERO_BYTES32
+from poly_web3.web3_service.base import BaseWeb3Service
+
+
+class EOAWeb3Service(BaseWeb3Service):
+    def redeem(
+        self,
+        condition_ids: str | list[str],
+        batch_size: int = 10,
+    ):
+        raise ImportError("EOA wallet redeem not supported")
+
+    def redeem_all(self, batch_size: int = 10) -> list[dict]:
+        raise ImportError("EOA wallet redeem not supported")
+
+    def split(
+        self,
+        condition_id: str,
+        amount: int | float | str | Decimal,
+        collateral_token: str = USDC_POLYGON,
+        parent_collection_id: str = ZERO_BYTES32,
+    ) -> dict | None:
+        raise ImportError("EOA wallet split not supported")
+
+    def merge(
+        self,
+        condition_id: str,
+        amount: int | float | str | Decimal,
+        collateral_token: str = USDC_POLYGON,
+        parent_collection_id: str = ZERO_BYTES32,
+    ) -> dict | None:
+        raise ImportError("EOA wallet merge not supported")

{poly_web3-1.0.1 → poly_web3-1.0.2}/poly_web3/web3_service/proxy_service.py

@@ -32,7 +32,9 @@ class ProxyWeb3Service(BaseWeb3Service):
             "typeCode": 1,
         }
 
-    def build_proxy_transaction_request(self, args: dict) -> dict:
+    def build_proxy_transaction_request(
+            self, args: dict, metadata: str = "redeem"
+    ) -> dict:
         proxy_contract_config = self.get_contract_config()["ProxyContracts"]
         to = proxy_contract_config["ProxyFactory"]
         proxy = derive_proxy_wallet(args["from"], to, PROXY_INIT_CODE_HASH)
@@ -80,7 +82,7 @@ class ProxyWeb3Service(BaseWeb3Service):
             "signature": final_sig,
             "signatureParams": sig_params,
             "type": self.wallet_type.value,
-            "metadata": "redeem",
+            "metadata": metadata,
         }
         return req
 
@@ -96,7 +98,7 @@ class ProxyWeb3Service(BaseWeb3Service):
         # Encode function data (compatible with web3 6/7)
         return contract.functions.proxy(calls_data)._encode_transaction_data()
 
-    def _submit_redeem(self, txs: list[dict]) -> dict:
+    def _submit_transactions(self, txs: list[dict], metadata: str) -> dict:
         if self.clob_client is None:
             raise Exception("signer not found")
         _from = to_checksum_address(self.clob_client.get_address())
@@ -108,7 +110,7 @@ class ProxyWeb3Service(BaseWeb3Service):
             "relay": rp["address"],
             "nonce": rp["nonce"],
         }
-        req = self.build_proxy_transaction_request(args)
+        req = self.build_proxy_transaction_request(args, metadata=metadata)
         headers = self.relayer_client._generate_builder_headers(
             "POST", SUBMIT_TRANSACTION, req
         )
@@ -122,3 +124,6 @@ class ProxyWeb3Service(BaseWeb3Service):
             max_polls=100,
         )
         return redeem_res
+
+    def _submit_redeem(self, txs: list[dict]) -> dict:
+        return self._submit_transactions(txs, "redeem")

{poly_web3-1.0.1 → poly_web3-1.0.2}/poly_web3/web3_service/safe_service.py

@@ -17,8 +17,13 @@ class SafeWeb3Service(BaseWeb3Service):
             operation=OperationType.Call,
         )
 
-    def _submit_redeem(self, txs: list[SafeTransaction]) -> dict | None:
+    def _submit_transactions(
+            self, txs: list[SafeTransaction], metadata: str
+    ) -> dict | None:
         if self.relayer_client is None:
             raise Exception("relayer_client not found")
-        resp = self.relayer_client.execute(txs, "redeem")
+        resp = self.relayer_client.execute(txs, metadata)
         return resp.wait()
+
+    def _submit_redeem(self, txs: list[SafeTransaction]) -> dict | None:
+        return self._submit_transactions(txs, "redeem")

{poly_web3-1.0.1 → poly_web3-1.0.2}/poly_web3.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: poly-web3
-Version: 1.0.1
+Version: 1.0.2
 Summary: Polymarket Proxy wallet redeem SDK - Execute redeem operations on Polymarket using proxy wallets
 Home-page: https://github.com/tosmart01/poly-web3
 Author: PinBar
@@ -27,11 +27,16 @@ Dynamic: requires-python
 
 # poly-web3
 
-Python SDK for redeeming Polymarket positions via Proxy/Safe wallets (gas-free).
+![PyPI](https://img.shields.io/pypi/v/poly-web3)
+![Python](https://img.shields.io/pypi/pyversions/poly-web3)
+![License](https://img.shields.io/github/license/tosmart01/poly-web3)
+
+Python SDK for redeeming and splitting/merging Polymarket positions via Proxy/Safe wallets (gas-free).
 
 [English](README.md) | [中文](README.zh.md)
 
 ```bash
+Python >= 3.11
 pip install poly-web3
 ```
 
@@ -44,7 +49,11 @@ service = PolyWeb3Service(
 )
 
 # Redeem all redeemable positions for the current account.
-service.redeem_all(batch_size=20)
+service.redeem_all(batch_size=10)
+
+# Split/Merge for binary markets (amount in human USDC units).
+service.split("0x...", 10)
+service.merge("0x...", 10)
 ```
 
 [See the full example](#quick-start)
@@ -54,18 +63,25 @@ service.redeem_all(batch_size=20)
 - Redeemable positions are fetched via the official Positions API, which typically has ~1 minute latency.
 - `redeem_all` returns an empty list if there are no redeemable positions. If the returned list contains `None`, the redeem failed and should be retried.
 
-## Troubleshooting
+## Split/Merge Notes
+
+- `split`/`merge` are designed for binary markets (Yes/No) and use the default partition internally.
+- `amount` is in human units (USDC), and is converted to base units internally.
+
+## FAQ
 
 1. **UI shows redeemable, but `redeem_all` returns `[]`**: The official Positions API can be delayed by 1–3 minutes. Wait a bit and retry.
 2. **RPC error during redeem**: Switch RPC endpoints by setting `rpc_url` when instantiating `PolyWeb3Service`.
 3. **Redeem stuck in `execute`**: The official relayer may be congested. Stop redeeming for 1 hour to avoid nonce looping from repeated submissions.
+4. **Relayer client returns 403**: You need to apply for Builder API access and use a valid key. Reference: Polymarket Builders — Introduction: https://docs.polymarket.com/developers/builders/builder-intro
+5. **Relayer daily limit**: The official relayer typically limits to 100 requests per day. Prefer batch redeem (`batch_size`) to reduce the number of requests and avoid hitting the limit.
 
 ## About the Project
 
 This project is a Python rewrite of Polymarket's official TypeScript implementation of `builder-relayer-client`, designed to provide Python developers with a convenient tool for executing Proxy and Safe wallet redeem operations on Polymarket.
 
 **Important Notes:**
-- This project **only implements the official redeem functionality**, focusing on Conditional Token Fund (CTF) redeem operations
+- This project implements official CTF redeem plus binary split/merge operations
 - Other features (such as trading, order placement, etc.) are not within the scope of this project
 
 **Some Polymarket-related redeem or write operations implemented in this project depend on access granted through Polymarket's Builder program. To perform real redeem operations against Polymarket, you must apply for and obtain a Builder key/credentials via Polymarket's official Builder application process. After approval you will receive the credentials required to use the Builder API—only then will the redeem flows in this repository work against the live service. For local development or automated tests, use mocks or testnet setups instead of real keys to avoid exposing production credentials.**
@@ -74,8 +90,8 @@ Reference：
 - Polymarket Builders — Introduction: https://docs.polymarket.com/developers/builders/builder-intro
 
 **Current Status:**
-- ✅ **Proxy Wallet** - Fully supported for redeem functionality
-- ✅ **Safe Wallet** - Fully supported for redeem functionality
+- ✅ **Proxy Wallet** - Fully supported for redeem/split/merge
+- ✅ **Safe Wallet** - Fully supported for redeem/split/merge
 - 🚧 **EOA Wallet** - Under development
 
 We welcome community contributions! If you'd like to help implement EOA wallet redeem functionality, or have other improvement suggestions, please feel free to submit a Pull Request.
@@ -153,21 +169,41 @@ service = PolyWeb3Service(
 )
 
 
+# Redeem all positions that are currently redeemable
+redeem_all_result = service.redeem_all(batch_size=10)
+print(f"Redeem all result: {redeem_all_result}")
+# If redeem_all_result contains None, refer to README FAQ and retry.
+if redeem_all_result and any(item is None for item in redeem_all_result):
+    print("Redeem failed for some items; please retry.")
+
 # Execute redeem operation (batch)
 condition_ids = [
     "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c",
     "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
 ]
-redeem_batch_result = service.redeem(condition_ids, batch_size=20)
+redeem_batch_result = service.redeem(condition_ids, batch_size=10)
 print(f"Redeem batch result: {redeem_batch_result}")
-
-# Redeem all positions that are currently redeemable
-redeem_all_result = service.redeem_all(batch_size=20)
-print(f"Redeem all result: {redeem_all_result}")
 if redeem_all_result and any(item is None for item in redeem_all_result):
     print("Redeem failed for some items; please retry.")
 ```
 
+### Basic Usage - Split/Merge (Binary Markets)
+
+```python
+# amount is in human units (USDC)
+split_result = service.split(
+    "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
+    1.5,
+)
+print(f"Split result: {split_result}")
+
+merge_result = service.merge(
+    "0x31fb435a9506d14f00b9de5e5e4491cf2223b6d40a2525d9afa8b620b61b50e2",
+    1.5,
+)
+print(f"Merge result: {merge_result}")
+```
+
 ## API Documentation
 
 ### PolyWeb3Service
@@ -191,7 +227,7 @@ Execute redeem operation.
 
 ```python
 # Batch redeem
-result = service.redeem(["0x...", "0x..."], batch_size=20)
+result = service.redeem(["0x...", "0x..."], batch_size=10)
 ```
 
 ##### `redeem_all(batch_size: int = 20) -> list[dict]`
@@ -205,7 +241,41 @@ Redeem all positions that are currently redeemable for the authenticated account
 
 ```python
 # Redeem all positions that can be redeemed
-service.redeem_all(batch_size=20)
+service.redeem_all(batch_size=10)
+```
+
+##### `split(condition_id: str, amount: int | float | str)`
+
+Split a binary (Yes/No) position. `amount` is in human USDC units.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `amount` (int | float | str): Amount in USDC
+
+**Returns:**
+- `dict | None`: Transaction result
+
+**Examples:**
+
+```python
+result = service.split("0x...", 1.25)
+```
+
+##### `merge(condition_id: str, amount: int | float | str)`
+
+Merge a binary (Yes/No) position. `amount` is in human USDC units.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `amount` (int | float | str): Amount in USDC
+
+**Returns:**
+- `dict | None`: Transaction result
+
+**Examples:**
+
+```python
+result = service.merge("0x...", 1.25)
 ```
 
 #### Optional APIs
@@ -281,7 +351,7 @@ poly_web3/
 
 1. **Environment Variable Security**: Make sure `.env` file is added to `.gitignore`, do not commit sensitive information to the code repository
 2. **Network Support**: Currently mainly supports Polygon mainnet (chain_id: 137), Amoy testnet may have limited functionality
-3. **Wallet Type**: Proxy (signature_type: 1) and Safe (signature_type: 2) are supported; EOA wallet redeem functionality is under development
+3. **Wallet Type**: Proxy (signature_type: 1) and Safe (signature_type: 2) are supported; EOA wallet operations are under development
 4. **Gas Fees**: Transactions are executed through Relayer, gas fees are handled by the Relayer
 
 ## Development
@@ -296,18 +366,18 @@ uv pip install -e ".[dev]"
 
 ```bash
 python examples/example_redeem.py
+python examples/example_split_merge.py
 ```
 
 ### Contributing
 
-We welcome all forms of contributions! If you'd like to:
-
-- Implement EOA wallet support
-- Fix bugs or improve existing functionality
-- Add new features or improve documentation
-- Make suggestions or report issues
+Simple contribution flow:
 
-Please feel free to submit an Issue or Pull Request. Your contributions will help make this project better!
+1. Open an Issue to describe the change (bug/feature/doc).
+2. Fork and create a branch: `feat/xxx` or `fix/xxx`.
+3. Make changes and update/add docs if needed.
+4. Run: `uv run python -m examples.example_redeem` or `uv run python -m examples.example_split_merge` (if applicable).
+5. Open a Pull Request and link the Issue.
 
 ## License
 

{poly_web3-1.0.1 → poly_web3-1.0.2}/poly_web3.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 setup.py
 examples/example_redeem.py
+examples/example_split_merge.py
 poly_web3/__init__.py
 poly_web3/const.py
 poly_web3/log.py

{poly_web3-1.0.1 → poly_web3-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "poly-web3"
-version = "1.0.1"
+version = "1.0.2"
 description = "Polymarket Proxy wallet redeem SDK - Execute redeem operations on Polymarket using proxy wallets"
 readme = "README.md"
 requires-python = ">=3.11"

poly_web3-1.0.1/poly_web3/web3_service/eoa_service.py

@@ -1,19 +0,0 @@
-# -*- coding = utf-8 -*-
-# @Time: 2025-12-27 16:01:09
-# @Author: PinBar
-# @Site:
-# @File: eoa_service.py
-# @Software: PyCharm
-from poly_web3.web3_service.base import BaseWeb3Service
-
-
-class EOAWeb3Service(BaseWeb3Service):
-    def redeem(
-        self,
-        condition_ids: str | list[str],
-        batch_size: int = 10,
-    ):
-        raise ImportError("EOA wallet redeem not supported")
-
-    def redeem_all(self, batch_size: int = 10) -> list[dict]:
-        raise ImportError("EOA wallet redeem not supported")