poly-web3 0.0.1__tar.gz

poly_web3-0.0.1/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: poly-web3
+Version: 0.0.1
+Summary: Polymarket Proxy wallet redeem SDK - Execute redeem operations on Polymarket using proxy wallets
+Home-page: https://github.com/tosmart01/poly-web3
+Author: PinBar
+Project-URL: Homepage, https://github.com/tosmart01/poly-web3
+Project-URL: Repository, https://github.com/tosmart01/poly-web3
+Project-URL: Bug Tracker, https://github.com/tosmart01/poly-web3/issues
+Keywords: polymarket,web3,proxy,wallet,redeem,blockchain,polygon
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: py-clob-client>=0.25.0
+Requires-Dist: py-builder-relayer-client>=0.0.1
+Requires-Dist: web3==6.8
+Requires-Dist: eth-utils==5.3.1
+Requires-Dist: setuptools>=80.9.0
+Dynamic: home-page
+Dynamic: requires-python
+
+# poly-web3
+
+Python SDK for Polymarket Proxy wallet redeem operations. Supports executing Conditional Token Fund (CTF) redeem operations on Polymarket through proxy wallets.
+
+[English](README.md) | [中文](README.zh.md)
+
+## 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 wallet redeem operations on Polymarket.
+
+**Important Notes:**
+- This project **only implements the official redeem functionality**, focusing on Conditional Token Fund (CTF) redeem operations
+- Other features (such as trading, order placement, etc.) are not within the scope of this project
+
+**Current Status:**
+- ✅ **Proxy Wallet** - Fully supported for redeem functionality
+- 🚧 **Safe Wallet** - Under development
+- 🚧 **EOA Wallet** - Under development
+
+We welcome community contributions! If you'd like to help implement Safe or EOA wallet redeem functionality, or have other improvement suggestions, please feel free to submit a Pull Request.
+
+## Features
+
+- ✅ Support for Polymarket Proxy wallet redeem operations (currently only Proxy wallet is supported)
+- ✅ Check if conditions are resolved
+- ✅ Get redeemable indexes and balances
+- ✅ Support for standard CTF redeem and negative risk (neg_risk) redeem
+- ✅ Automatic transaction execution through Relayer service
+
+## Installation
+
+```bash
+pip install poly-web3
+```
+
+Or using uv:
+
+```bash
+uv add poly-web3
+```
+
+## Requirements
+
+- Python >= 3.11
+
+## Dependencies
+
+- `py-clob-client >= 0.25.0` - Polymarket CLOB client
+- `py-builder-relayer-client >= 0.0.1` - Builder Relayer client
+- `web3 == 6.8` - Web3.py library
+- `eth-utils == 5.3.1` - Ethereum utilities library
+
+## Quick Start
+
+### Basic Usage - Execute Redeem
+
+```python
+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()
+
+# Initialize ClobClient
+host = "https://clob.polymarket.com"
+chain_id = 137  # Polygon mainnet
+client = ClobClient(
+    host,
+    key=os.getenv("POLY_API_KEY"),
+    chain_id=chain_id,
+    signature_type=1,  # Proxy wallet type
+    funder=os.getenv("POLYMARKET_PROXY_ADDRESS"),
+)
+
+client.set_api_creds(client.create_or_derive_api_creds())
+
+# Initialize RelayerClient
+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"),
+        )
+    ),
+)
+
+# Create service instance
+service = PolyWeb3Service(clob_client=client, relayer_client=relayer_client)
+
+# Execute redeem operation
+condition_id = "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c"
+redeem_result = service.redeem(condition_id=condition_id)
+print(f"Redeem result: {redeem_result}")
+```
+
+### Optional - Query Operations
+
+Before executing redeem, you can optionally check the condition status and query redeemable balances:
+
+```python
+# Check if condition is resolved
+condition_id = "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c"
+can_redeem = service.is_condition_resolved(condition_id)
+
+# Get redeemable indexes and balances
+redeem_balance = service.get_redeemable_index_and_balance(
+    condition_id, owner=client.builder.funder
+)
+
+print(f"Can redeem: {can_redeem}")
+print(f"Redeemable balance: {redeem_balance}")
+```
+
+## API Documentation
+
+### PolyWeb3Service
+
+The main service class that automatically selects the appropriate service implementation based on wallet type.
+
+#### Methods
+
+##### `is_condition_resolved(condition_id: str) -> bool`
+
+Check if the specified condition is resolved.
+
+**Parameters:**
+- `condition_id` (str): Condition ID (32-byte hexadecimal string)
+
+**Returns:**
+- `bool`: Returns `True` if the condition is resolved, otherwise `False`
+
+##### `get_winning_indexes(condition_id: str) -> list[int]`
+
+Get the list of winning indexes.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+
+**Returns:**
+- `list[int]`: List of winning indexes
+
+##### `get_redeemable_index_and_balance(condition_id: str, owner: str) -> list[tuple]`
+
+Get redeemable indexes and balances for the specified address.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `owner` (str): Wallet address
+
+**Returns:**
+- `list[tuple]`: List of tuples containing (index, balance), balance is in USDC units
+
+##### `redeem(condition_id: str, neg_risk: bool = False, redeem_amounts: list[int] | None = None)`
+
+Execute redeem operation.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `neg_risk` (bool): Whether it's a negative risk redeem, defaults to `False`
+- `redeem_amounts` (list[int] | None): Amount list for negative risk redeem, must contain 2 elements
+
+**Returns:**
+- `dict`: Transaction result containing transaction status and related information
+
+**Examples:**
+
+```python
+# Standard CTF redeem
+result = service.redeem(condition_id="0x...")
+
+# Negative risk redeem
+result = service.redeem(
+    condition_id="0x...",
+    neg_risk=True,
+    redeem_amounts=[1000000, 2000000]  # Amounts in smallest unit (6 decimal places)
+)
+```
+
+## Project Structure
+
+```
+poly_web3/
+├── __init__.py              # Main entry point, exports PolyWeb3Service
+├── const.py                 # Constant definitions (contract addresses, ABIs, etc.)
+├── schema.py                # Data models (WalletType, etc.)
+├── signature/               # Signature-related modules
+│   ├── build.py            # Proxy wallet derivation and struct hashing
+│   ├── hash_message.py     # Message hashing
+│   └── secp256k1.py        # secp256k1 signing
+└── web3_service/           # Web3 service implementations
+    ├── base.py             # Base service class
+    ├── proxy_service.py    # Proxy wallet service (✅ Implemented)
+    ├── eoa_service.py      # EOA wallet service (🚧 Under development)
+    └── safe_service.py     # Safe wallet service (🚧 Under development)
+```
+
+## Notes
+
+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**: **Currently only Proxy wallet is supported** (signature_type: 1), Safe and EOA wallet redeem functionality is under development
+4. **Gas Fees**: Transactions are executed through Relayer, gas fees are handled by the Relayer
+
+## Development
+
+### Install Development Dependencies
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+### Run Examples
+
+```bash
+python examples/example_redeem.py
+```
+
+### Contributing
+
+We welcome all forms of contributions! If you'd like to:
+
+- Implement Safe or EOA wallet support
+- Fix bugs or improve existing functionality
+- Add new features or improve documentation
+- Make suggestions or report issues
+
+Please feel free to submit an Issue or Pull Request. Your contributions will help make this project better!
+
+## License
+
+MIT
+
+## Author
+
+PinBar
+
+## Related Links
+
+- [Polymarket](https://polymarket.com/)
+- [Polygon Network](https://polygon.technology/)

poly_web3-0.0.1/README.md

@@ -0,0 +1,248 @@
+# poly-web3
+
+Python SDK for Polymarket Proxy wallet redeem operations. Supports executing Conditional Token Fund (CTF) redeem operations on Polymarket through proxy wallets.
+
+[English](README.md) | [中文](README.zh.md)
+
+## 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 wallet redeem operations on Polymarket.
+
+**Important Notes:**
+- This project **only implements the official redeem functionality**, focusing on Conditional Token Fund (CTF) redeem operations
+- Other features (such as trading, order placement, etc.) are not within the scope of this project
+
+**Current Status:**
+- ✅ **Proxy Wallet** - Fully supported for redeem functionality
+- 🚧 **Safe Wallet** - Under development
+- 🚧 **EOA Wallet** - Under development
+
+We welcome community contributions! If you'd like to help implement Safe or EOA wallet redeem functionality, or have other improvement suggestions, please feel free to submit a Pull Request.
+
+## Features
+
+- ✅ Support for Polymarket Proxy wallet redeem operations (currently only Proxy wallet is supported)
+- ✅ Check if conditions are resolved
+- ✅ Get redeemable indexes and balances
+- ✅ Support for standard CTF redeem and negative risk (neg_risk) redeem
+- ✅ Automatic transaction execution through Relayer service
+
+## Installation
+
+```bash
+pip install poly-web3
+```
+
+Or using uv:
+
+```bash
+uv add poly-web3
+```
+
+## Requirements
+
+- Python >= 3.11
+
+## Dependencies
+
+- `py-clob-client >= 0.25.0` - Polymarket CLOB client
+- `py-builder-relayer-client >= 0.0.1` - Builder Relayer client
+- `web3 == 6.8` - Web3.py library
+- `eth-utils == 5.3.1` - Ethereum utilities library
+
+## Quick Start
+
+### Basic Usage - Execute Redeem
+
+```python
+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()
+
+# Initialize ClobClient
+host = "https://clob.polymarket.com"
+chain_id = 137  # Polygon mainnet
+client = ClobClient(
+    host,
+    key=os.getenv("POLY_API_KEY"),
+    chain_id=chain_id,
+    signature_type=1,  # Proxy wallet type
+    funder=os.getenv("POLYMARKET_PROXY_ADDRESS"),
+)
+
+client.set_api_creds(client.create_or_derive_api_creds())
+
+# Initialize RelayerClient
+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"),
+        )
+    ),
+)
+
+# Create service instance
+service = PolyWeb3Service(clob_client=client, relayer_client=relayer_client)
+
+# Execute redeem operation
+condition_id = "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c"
+redeem_result = service.redeem(condition_id=condition_id)
+print(f"Redeem result: {redeem_result}")
+```
+
+### Optional - Query Operations
+
+Before executing redeem, you can optionally check the condition status and query redeemable balances:
+
+```python
+# Check if condition is resolved
+condition_id = "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c"
+can_redeem = service.is_condition_resolved(condition_id)
+
+# Get redeemable indexes and balances
+redeem_balance = service.get_redeemable_index_and_balance(
+    condition_id, owner=client.builder.funder
+)
+
+print(f"Can redeem: {can_redeem}")
+print(f"Redeemable balance: {redeem_balance}")
+```
+
+## API Documentation
+
+### PolyWeb3Service
+
+The main service class that automatically selects the appropriate service implementation based on wallet type.
+
+#### Methods
+
+##### `is_condition_resolved(condition_id: str) -> bool`
+
+Check if the specified condition is resolved.
+
+**Parameters:**
+- `condition_id` (str): Condition ID (32-byte hexadecimal string)
+
+**Returns:**
+- `bool`: Returns `True` if the condition is resolved, otherwise `False`
+
+##### `get_winning_indexes(condition_id: str) -> list[int]`
+
+Get the list of winning indexes.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+
+**Returns:**
+- `list[int]`: List of winning indexes
+
+##### `get_redeemable_index_and_balance(condition_id: str, owner: str) -> list[tuple]`
+
+Get redeemable indexes and balances for the specified address.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `owner` (str): Wallet address
+
+**Returns:**
+- `list[tuple]`: List of tuples containing (index, balance), balance is in USDC units
+
+##### `redeem(condition_id: str, neg_risk: bool = False, redeem_amounts: list[int] | None = None)`
+
+Execute redeem operation.
+
+**Parameters:**
+- `condition_id` (str): Condition ID
+- `neg_risk` (bool): Whether it's a negative risk redeem, defaults to `False`
+- `redeem_amounts` (list[int] | None): Amount list for negative risk redeem, must contain 2 elements
+
+**Returns:**
+- `dict`: Transaction result containing transaction status and related information
+
+**Examples:**
+
+```python
+# Standard CTF redeem
+result = service.redeem(condition_id="0x...")
+
+# Negative risk redeem
+result = service.redeem(
+    condition_id="0x...",
+    neg_risk=True,
+    redeem_amounts=[1000000, 2000000]  # Amounts in smallest unit (6 decimal places)
+)
+```
+
+## Project Structure
+
+```
+poly_web3/
+├── __init__.py              # Main entry point, exports PolyWeb3Service
+├── const.py                 # Constant definitions (contract addresses, ABIs, etc.)
+├── schema.py                # Data models (WalletType, etc.)
+├── signature/               # Signature-related modules
+│   ├── build.py            # Proxy wallet derivation and struct hashing
+│   ├── hash_message.py     # Message hashing
+│   └── secp256k1.py        # secp256k1 signing
+└── web3_service/           # Web3 service implementations
+    ├── base.py             # Base service class
+    ├── proxy_service.py    # Proxy wallet service (✅ Implemented)
+    ├── eoa_service.py      # EOA wallet service (🚧 Under development)
+    └── safe_service.py     # Safe wallet service (🚧 Under development)
+```
+
+## Notes
+
+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**: **Currently only Proxy wallet is supported** (signature_type: 1), Safe and EOA wallet redeem functionality is under development
+4. **Gas Fees**: Transactions are executed through Relayer, gas fees are handled by the Relayer
+
+## Development
+
+### Install Development Dependencies
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+### Run Examples
+
+```bash
+python examples/example_redeem.py
+```
+
+### Contributing
+
+We welcome all forms of contributions! If you'd like to:
+
+- Implement Safe or EOA wallet support
+- Fix bugs or improve existing functionality
+- Add new features or improve documentation
+- Make suggestions or report issues
+
+Please feel free to submit an Issue or Pull Request. Your contributions will help make this project better!
+
+## License
+
+MIT
+
+## Author
+
+PinBar
+
+## Related Links
+
+- [Polymarket](https://polymarket.com/)
+- [Polygon Network](https://polygon.technology/)

poly_web3-0.0.1/examples/example_redeem.py

@@ -0,0 +1,54 @@
+# -*- coding = utf-8 -*-
+# @Time: 2025-12-27 17:01:20
+# @Author: PinBar
+# @Site:
+# @File: example_redeem.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,
+        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"),
+            )
+        ),
+    )
+    condition_id = "0xc3df016175463c44f9c9f98bddaa3bf3daaabb14b069fb7869621cffe73ddd1c"
+    service = PolyWeb3Service(clob_client=client, relayer_client=relayer_client)
+    redeem = service.redeem(condition_id=condition_id)
+    print(redeem)
+
+    # Optional - Query operations (可选操作，用于查询)
+    # can_redeem = service.is_condition_resolved(condition_id)
+    # redeem_balance = service.get_redeemable_index_and_balance(
+    #     condition_id, owner=client.builder.funder
+    # )
+    # print(can_redeem, redeem_balance)

poly_web3-0.0.1/poly_web3/__init__.py

@@ -0,0 +1,31 @@
+# -*- coding = utf-8 -*-
+# @Time: 2025/12/19 15:24
+# @Author: PinBar
+# @Site:
+# @File: __init__.py.py
+# @Software: PyCharm
+from typing import Union
+
+from py_clob_client.client import ClobClient
+from py_builder_relayer_client.client import RelayClient
+
+from poly_web3.const import RELAYER_URL
+from poly_web3.web3_service.base import BaseWeb3Service
+from poly_web3.schema import WalletType
+from poly_web3.web3_service import SafeWeb3Service, EOAWeb3Service, ProxyWeb3Service
+
+
+def PolyWeb3Service(
+    clob_client: ClobClient, relayer_client: RelayClient = None
+) -> Union[SafeWeb3Service, EOAWeb3Service, ProxyWeb3Service]:  # noqa
+    services = {
+        WalletType.EOA: EOAWeb3Service,
+        WalletType.PROXY: ProxyWeb3Service,
+        WalletType.SAFE: SafeWeb3Service,
+    }
+
+    wallet_type = WalletType.get_with_code(clob_client.builder.sig_type)
+    if service := services.get(wallet_type):
+        return service(clob_client, relayer_client)
+    else:
+        raise Exception(f"Unknown wallet type: {wallet_type}")