agentcrab 0.1.0__tar.gz

agentcrab-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Environment variables / secrets
+.env*
+*.pem
+*.key
+
+# Node
+node_modules/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# OS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# Foundry
+Polymarket/contracts/out/
+Polymarket/contracts/cache/
+Polymarket/contracts/broadcast/
+
+# Wrangler (Cloudflare)
+.wrangler/
+
+# SQLite
+*.db

agentcrab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentCrab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentcrab-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: agentcrab
+Version: 0.1.0
+Summary: Python SDK for agentCrab — turn any AI agent into a Polymarket assistant
+Project-URL: Homepage, https://agentcrab.ai
+Project-URL: Documentation, https://github.com/agentcrab/agentcrab-python
+Project-URL: Repository, https://github.com/agentcrab/agentcrab-python
+Author-email: agentCrab <dev@agentcrab.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,polymarket,prediction-market,sdk,web3
+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: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: eth-account>=0.13.0
+Requires-Dist: hexbytes>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# agentcrab
+
+Python SDK for [agentCrab](https://agentcrab.ai) — turn any AI agent into a Polymarket assistant with 3 lines of code.
+
+## Install
+
+```bash
+pip install agentcrab
+```
+
+## Quick Start
+
+```python
+from agentcrab import AgentCrab
+
+client = AgentCrab("https://api.agentcrab.ai/polymarket", "0xYOUR_PRIVATE_KEY")
+
+# Search markets
+markets = client.search("bitcoin")
+for m in markets:
+    print(m.title, m.outcomes)
+
+# Check balance
+balance = client.get_balance()
+print(f"{balance.calls_remaining} API calls remaining")
+```
+
+## Trading
+
+```python
+# One-time setup (deploys Safe + approvals + L2 credentials)
+setup = client.setup_trading()
+print(f"Safe: {setup.safe_address}")
+
+# Buy shares
+result = client.buy(token_id="TOKEN_ID", size=5.0, price=0.65)
+print(f"Order {result.status}: {result.order_id}")
+
+# Sell shares
+result = client.sell(token_id="TOKEN_ID", size=5.0, price=0.70)
+
+# View positions
+for pos in client.get_positions():
+    print(f"{pos.outcome}: {pos.size} shares, PnL: {pos.pnl}")
+```
+
+## Full API
+
+### Balance & Payment
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `get_balance()` | Prepaid balance | Free |
+| `deposit(amount_usdt)` | Deposit to agentCrab | Free |
+| `deposit_to_polymarket(amount_usdt)` | Deposit to Polymarket | 0.01 USDT |
+
+### Market Data
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `search(query, tag, category)` | Search events | 0.01 USDT |
+| `browse(category, mood)` | Browse events | 0.01 USDT |
+| `get_event(event_id)` | Get single event | 0.01 USDT |
+| `get_market(market_id)` | Get single market | 0.01 USDT |
+| `get_orderbook(token_id)` | Get orderbook | 0.01 USDT |
+| `get_price(token_id)` | Get price | 0.01 USDT |
+
+### Positions & History
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `get_positions()` | Your positions | 0.01 USDT |
+| `get_trades(limit, offset)` | Your trades | 0.01 USDT |
+| `get_leaderboard(limit, offset)` | Leaderboard | 0.01 USDT |
+
+### Trading (requires `setup_trading()` first)
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `setup_trading()` | Deploy Safe + approvals + creds | 0.01-0.03 USDT |
+| `set_credentials(key, secret, passphrase)` | Manual cred set | Free |
+| `buy(token_id, size, price)` | Buy shares | 0.01 USDT |
+| `sell(token_id, size, price)` | Sell shares | 0.01 USDT |
+| `cancel_order(order_id)` | Cancel order | 0.01 USDT |
+| `cancel_all_orders()` | Cancel all | 0.01 USDT |
+| `get_open_orders(market)` | Open orders | 0.01 USDT |
+
+### Wallet
+
+| Method | Description |
+|--------|-------------|
+| `AgentCrab.create_wallet(api_url)` | Create new wallet (static) |
+
+## Typed Responses
+
+All methods return typed dataclasses with a `.raw` escape hatch:
+
+```python
+balance = client.get_balance()
+print(balance.calls_remaining)   # typed field
+print(balance.raw)               # full server response dict
+```
+
+## Error Handling
+
+```python
+from agentcrab import AgentCrabError, InsufficientBalance, SetupRequired
+
+try:
+    result = client.buy(token_id, size=5.0, price=0.65)
+except SetupRequired:
+    client.setup_trading()
+    result = client.buy(token_id, size=5.0, price=0.65)
+except InsufficientBalance as e:
+    print(f"Top up: {e.message}")
+except AgentCrabError as e:
+    print(f"Error [{e.error_code}]: {e.message}")
+```
+
+## Dependencies
+
+Minimal — no `web3` required:
+
+- `eth-account` — EIP-191, EIP-712, tx signing
+- `httpx` — Sync HTTP
+- `hexbytes` — SafeTx hash signing
+
+## License
+
+MIT

agentcrab-0.1.0/README.md

@@ -0,0 +1,130 @@
+# agentcrab
+
+Python SDK for [agentCrab](https://agentcrab.ai) — turn any AI agent into a Polymarket assistant with 3 lines of code.
+
+## Install
+
+```bash
+pip install agentcrab
+```
+
+## Quick Start
+
+```python
+from agentcrab import AgentCrab
+
+client = AgentCrab("https://api.agentcrab.ai/polymarket", "0xYOUR_PRIVATE_KEY")
+
+# Search markets
+markets = client.search("bitcoin")
+for m in markets:
+    print(m.title, m.outcomes)
+
+# Check balance
+balance = client.get_balance()
+print(f"{balance.calls_remaining} API calls remaining")
+```
+
+## Trading
+
+```python
+# One-time setup (deploys Safe + approvals + L2 credentials)
+setup = client.setup_trading()
+print(f"Safe: {setup.safe_address}")
+
+# Buy shares
+result = client.buy(token_id="TOKEN_ID", size=5.0, price=0.65)
+print(f"Order {result.status}: {result.order_id}")
+
+# Sell shares
+result = client.sell(token_id="TOKEN_ID", size=5.0, price=0.70)
+
+# View positions
+for pos in client.get_positions():
+    print(f"{pos.outcome}: {pos.size} shares, PnL: {pos.pnl}")
+```
+
+## Full API
+
+### Balance & Payment
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `get_balance()` | Prepaid balance | Free |
+| `deposit(amount_usdt)` | Deposit to agentCrab | Free |
+| `deposit_to_polymarket(amount_usdt)` | Deposit to Polymarket | 0.01 USDT |
+
+### Market Data
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `search(query, tag, category)` | Search events | 0.01 USDT |
+| `browse(category, mood)` | Browse events | 0.01 USDT |
+| `get_event(event_id)` | Get single event | 0.01 USDT |
+| `get_market(market_id)` | Get single market | 0.01 USDT |
+| `get_orderbook(token_id)` | Get orderbook | 0.01 USDT |
+| `get_price(token_id)` | Get price | 0.01 USDT |
+
+### Positions & History
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `get_positions()` | Your positions | 0.01 USDT |
+| `get_trades(limit, offset)` | Your trades | 0.01 USDT |
+| `get_leaderboard(limit, offset)` | Leaderboard | 0.01 USDT |
+
+### Trading (requires `setup_trading()` first)
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `setup_trading()` | Deploy Safe + approvals + creds | 0.01-0.03 USDT |
+| `set_credentials(key, secret, passphrase)` | Manual cred set | Free |
+| `buy(token_id, size, price)` | Buy shares | 0.01 USDT |
+| `sell(token_id, size, price)` | Sell shares | 0.01 USDT |
+| `cancel_order(order_id)` | Cancel order | 0.01 USDT |
+| `cancel_all_orders()` | Cancel all | 0.01 USDT |
+| `get_open_orders(market)` | Open orders | 0.01 USDT |
+
+### Wallet
+
+| Method | Description |
+|--------|-------------|
+| `AgentCrab.create_wallet(api_url)` | Create new wallet (static) |
+
+## Typed Responses
+
+All methods return typed dataclasses with a `.raw` escape hatch:
+
+```python
+balance = client.get_balance()
+print(balance.calls_remaining)   # typed field
+print(balance.raw)               # full server response dict
+```
+
+## Error Handling
+
+```python
+from agentcrab import AgentCrabError, InsufficientBalance, SetupRequired
+
+try:
+    result = client.buy(token_id, size=5.0, price=0.65)
+except SetupRequired:
+    client.setup_trading()
+    result = client.buy(token_id, size=5.0, price=0.65)
+except InsufficientBalance as e:
+    print(f"Top up: {e.message}")
+except AgentCrabError as e:
+    print(f"Error [{e.error_code}]: {e.message}")
+```
+
+## Dependencies
+
+Minimal — no `web3` required:
+
+- `eth-account` — EIP-191, EIP-712, tx signing
+- `httpx` — Sync HTTP
+- `hexbytes` — SafeTx hash signing
+
+## License
+
+MIT

agentcrab-0.1.0/agentcrab/__init__.py

@@ -0,0 +1,55 @@
+"""agentcrab — Python SDK for the agentCrab Polymarket API."""
+
+__version__ = "0.1.0"
+
+from .client import AgentCrab
+from ._exceptions import (
+    AgentCrabError,
+    APIError,
+    AuthError,
+    InsufficientBalance,
+    NetworkError,
+    OrderError,
+    PaymentError,
+    SetupRequired,
+)
+from ._types import (
+    Balance,
+    BatchOrderResult,
+    DepositResult,
+    Market,
+    Orderbook,
+    OrderResult,
+    Position,
+    Price,
+    SetupResult,
+    Trade,
+    Trigger,
+    TriggerResult,
+)
+
+__all__ = [
+    "AgentCrab",
+    # Exceptions
+    "AgentCrabError",
+    "APIError",
+    "AuthError",
+    "InsufficientBalance",
+    "NetworkError",
+    "OrderError",
+    "PaymentError",
+    "SetupRequired",
+    # Types
+    "Balance",
+    "BatchOrderResult",
+    "DepositResult",
+    "Market",
+    "Orderbook",
+    "OrderResult",
+    "Position",
+    "Price",
+    "SetupResult",
+    "Trade",
+    "Trigger",
+    "TriggerResult",
+]

agentcrab-0.1.0/agentcrab/_auth.py

@@ -0,0 +1,39 @@
+"""EIP-191 authentication header building."""
+
+import time
+
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+
+def build_auth_headers(
+    private_key: str,
+    address: str,
+    payment_mode: str = "prepaid",
+) -> dict[str, str]:
+    """Build authentication headers for API requests.
+
+    Signs ``agentcrab:{unix_timestamp}`` with EIP-191 personal_sign.
+    """
+    ts = int(time.time())
+    message = f"agentcrab:{ts}"
+    sig = Account.sign_message(
+        encode_defunct(text=message),
+        private_key=private_key,
+    )
+    headers = {
+        "X-Wallet-Address": address,
+        "X-Signature": "0x" + sig.signature.hex(),
+        "X-Message": message,
+        "X-Payment-Mode": payment_mode,
+    }
+    return headers
+
+
+def build_l2_headers(api_key: str, secret: str, passphrase: str) -> dict[str, str]:
+    """Build Polymarket L2 credential headers."""
+    return {
+        "X-Poly-Api-Key": api_key,
+        "X-Poly-Secret": secret,
+        "X-Poly-Passphrase": passphrase,
+    }

agentcrab-0.1.0/agentcrab/_exceptions.py

@@ -0,0 +1,42 @@
+"""Typed exception hierarchy for the agentcrab SDK."""
+
+
+class AgentCrabError(Exception):
+    """Base exception for all agentcrab errors."""
+
+    def __init__(self, message: str, error_code: str | None = None, status_code: int | None = None):
+        self.message = message
+        self.error_code = error_code
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class AuthError(AgentCrabError):
+    """Signature verification failed (401)."""
+
+
+class PaymentError(AgentCrabError):
+    """Payment-related error (402)."""
+
+
+class InsufficientBalance(PaymentError):
+    """Prepaid balance too low."""
+
+
+class APIError(AgentCrabError):
+    """Server returned an error response (4xx/5xx)."""
+
+
+class SetupRequired(AgentCrabError):
+    """Trading operation called before setup_trading()."""
+
+    def __init__(self, message: str = "Call setup_trading() first to get L2 credentials."):
+        super().__init__(message, error_code="SETUP_REQUIRED")
+
+
+class OrderError(AgentCrabError):
+    """Order placement or cancellation failed."""
+
+
+class NetworkError(AgentCrabError):
+    """HTTP transport failure (timeout, connection refused, etc.)."""

agentcrab-0.1.0/agentcrab/_http.py

@@ -0,0 +1,138 @@
+"""Sync HTTP transport with auto-auth and error mapping."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._auth import build_auth_headers, build_l2_headers
+from ._exceptions import (
+    APIError,
+    AuthError,
+    InsufficientBalance,
+    NetworkError,
+    OrderError,
+    PaymentError,
+)
+
+# Map server error_code to exception class
+_ERROR_MAP: dict[str, type] = {
+    "INVALID_SIGNATURE": AuthError,
+    "MISSING_TX_HASH": PaymentError,
+    "PAYMENT_NOT_VERIFIED": PaymentError,
+    "INSUFFICIENT_BALANCE": InsufficientBalance,
+    "BALANCE_DEDUCTION_FAILED": PaymentError,
+    "INVALID_PAYMENT_MODE": PaymentError,
+    "ORDER_REJECTED": OrderError,
+    "ORDER_ERROR": OrderError,
+    "ORDER_BUILD_FAILED": OrderError,
+}
+
+
+class HttpTransport:
+    """Sync HTTP client with auto-injected auth headers."""
+
+    def __init__(
+        self,
+        base_url: str,
+        private_key: str,
+        address: str,
+        payment_mode: str = "prepaid",
+        timeout: float = 60.0,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._private_key = private_key
+        self._address = address
+        self._payment_mode = payment_mode
+        self._client = httpx.Client(base_url=self._base_url, timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _auth_headers(self) -> dict[str, str]:
+        return build_auth_headers(self._private_key, self._address, self._payment_mode)
+
+    def _raise_for_error(self, resp: httpx.Response) -> None:
+        """Parse server error response and raise typed exception."""
+        if resp.status_code < 400:
+            return
+        try:
+            body = resp.json()
+            # Handle FastAPI's HTTPException detail format
+            detail = body if isinstance(body, dict) and "error_code" in body else body.get("detail", body)
+            if isinstance(detail, dict):
+                error_code = detail.get("error_code", "")
+                message = detail.get("message", resp.text)
+            else:
+                error_code = ""
+                message = str(detail) if detail else resp.text
+        except Exception:
+            error_code = ""
+            message = resp.text
+
+        exc_cls = _ERROR_MAP.get(error_code, APIError)
+        raise exc_cls(message=message, error_code=error_code, status_code=resp.status_code)
+
+    def get(
+        self,
+        path: str,
+        params: dict | None = None,
+        auth: bool = True,
+        paid: bool = False,
+        l2_creds: dict | None = None,
+    ) -> dict:
+        """Send GET request. Returns parsed JSON body."""
+        headers = self._auth_headers() if (auth or paid) else {}
+        if l2_creds:
+            headers.update(build_l2_headers(**l2_creds))
+        try:
+            resp = self._client.get(path, params=params, headers=headers)
+        except httpx.HTTPError as e:
+            raise NetworkError(message=str(e)) from e
+        self._raise_for_error(resp)
+        return resp.json()
+
+    def post(
+        self,
+        path: str,
+        json: Any = None,
+        auth: bool = True,
+        paid: bool = False,
+        l2_creds: dict | None = None,
+    ) -> dict:
+        """Send POST request. Returns parsed JSON body."""
+        headers = self._auth_headers() if (auth or paid) else {}
+        if l2_creds:
+            headers.update(build_l2_headers(**l2_creds))
+        try:
+            resp = self._client.post(path, json=json, headers=headers)
+        except httpx.HTTPError as e:
+            raise NetworkError(message=str(e)) from e
+        self._raise_for_error(resp)
+        return resp.json()
+
+    def delete(
+        self,
+        path: str,
+        params: dict | None = None,
+        json: Any = None,
+        auth: bool = True,
+        paid: bool = False,
+        l2_creds: dict | None = None,
+    ) -> dict:
+        """Send DELETE request. Returns parsed JSON body."""
+        headers = self._auth_headers() if (auth or paid) else {}
+        if l2_creds:
+            headers.update(build_l2_headers(**l2_creds))
+        try:
+            resp = self._client.request("DELETE", path, params=params, json=json, headers=headers)
+        except httpx.HTTPError as e:
+            raise NetworkError(message=str(e)) from e
+        self._raise_for_error(resp)
+        return resp.json()
+
+
+def _extract_data(resp: dict) -> Any:
+    """Extract ``data`` field from SuccessResponse envelope."""
+    return resp.get("data", resp)

agentcrab-0.1.0/agentcrab/_signer.py

@@ -0,0 +1,42 @@
+"""Signing utilities: EIP-712 typed data, raw transactions, Safe tx hashes."""
+
+from eth_account import Account
+from eth_account.messages import encode_defunct
+from hexbytes import HexBytes
+
+
+def sign_typed_data(private_key: str, typed_data: dict) -> str:
+    """Sign EIP-712 typed data and return 0x-prefixed hex signature.
+
+    Used for: Safe deploy (CreateProxy), CLOB auth, order placement.
+    """
+    sig = Account.sign_typed_data(
+        private_key,
+        typed_data["domain"],
+        typed_data["types"],
+        typed_data["message"],
+    )
+    return "0x" + sig.signature.hex()
+
+
+def sign_transaction(private_key: str, tx: dict) -> str:
+    """Sign a raw transaction and return 0x-prefixed hex of the signed bytes.
+
+    Used for: BSC deposits, Polygon approve txs.
+    """
+    account = Account.from_key(private_key)
+    signed = account.sign_transaction(tx)
+    raw = signed.raw_transaction
+    if isinstance(raw, (bytes, bytearray)):
+        return "0x" + raw.hex()
+    return "0x" + bytes(raw).hex()
+
+
+def sign_safe_tx_hash(private_key: str, hash_hex: str) -> str:
+    """Personal-sign a SafeTx hash (bytes32) and return 0x-prefixed hex signature.
+
+    Used for: Safe token approvals via relayer.
+    """
+    account = Account.from_key(private_key)
+    sig = account.sign_message(encode_defunct(HexBytes(hash_hex)))
+    return "0x" + sig.signature.hex()