ctxprotocol 0.5.6__py3-none-any.whl → 0.5.7__py3-none-any.whl

ctxprotocol/__init__.py

@@ -91,6 +91,31 @@ from ctxprotocol.auth import (
     CreateContextMiddlewareOptions,
 )
 
+# Handshake types and helpers for tools that need user interaction
+# (signatures, transactions, OAuth)
+from ctxprotocol.handshake import (
+    # Types
+    HandshakeMeta,
+    EIP712Domain,
+    EIP712TypeField,
+    SignatureRequest,
+    TransactionProposalMeta,
+    TransactionProposal,
+    AuthRequiredMeta,
+    AuthRequired,
+    HandshakeAction,
+    # Type guards
+    is_handshake_action,
+    is_signature_request,
+    is_transaction_proposal,
+    is_auth_required,
+    # Helper functions
+    create_signature_request,
+    create_transaction_proposal,
+    create_auth_required,
+    wrap_handshake_response,
+)
+
 __all__ = [
     # Version
     "__version__",
@@ -144,5 +169,25 @@ __all__ = [
     "ContextMiddleware",
     "VerifyRequestOptions",
     "CreateContextMiddlewareOptions",
+    # Handshake types
+    "HandshakeMeta",
+    "EIP712Domain",
+    "EIP712TypeField",
+    "SignatureRequest",
+    "TransactionProposalMeta",
+    "TransactionProposal",
+    "AuthRequiredMeta",
+    "AuthRequired",
+    "HandshakeAction",
+    # Handshake type guards
+    "is_handshake_action",
+    "is_signature_request",
+    "is_transaction_proposal",
+    "is_auth_required",
+    # Handshake helper functions
+    "create_signature_request",
+    "create_transaction_proposal",
+    "create_auth_required",
+    "wrap_handshake_response",
 ]
 

ctxprotocol/handshake/__init__.py

@@ -0,0 +1,418 @@
+"""
+Handshake Module - Types and helpers for MCP tools that need user interaction.
+
+Use these types when your tool needs to request user actions:
+- Signatures (EIP-712 typed data for Hyperliquid, Polymarket, dYdX)
+- Transactions (direct on-chain actions for Uniswap, NFT mints)
+- OAuth (authentication flows for Discord, Twitter)
+
+Example:
+    >>> from ctxprotocol.handshake import create_signature_request, wrap_handshake_response
+    >>>
+    >>> # In your MCP tool handler:
+    >>> def handle_place_order(args):
+    ...     return wrap_handshake_response(
+    ...         create_signature_request(
+    ...             domain={"name": "Hyperliquid", "version": "1", "chainId": 42161},
+    ...             types={"Order": [{"name": "asset", "type": "uint32"}, ...]},
+    ...             primary_type="Order",
+    ...             message={"asset": 4, "isBuy": True, ...},
+    ...             meta={"description": "Place order", "protocol": "Hyperliquid"}
+    ...         )
+    ...     )
+
+For more information, see: https://docs.ctxprotocol.com/guides/handshake-architecture
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, TypedDict, Union
+
+# =============================================================================
+# Shared Meta Types
+# =============================================================================
+
+
+class HandshakeMeta(TypedDict, total=False):
+    """UI metadata for handshake approval cards."""
+
+    description: str
+    """Human-readable description of the action."""
+
+    protocol: str
+    """Protocol name (e.g., 'Hyperliquid', 'Polymarket')."""
+
+    action: str
+    """Action verb (e.g., 'Place Order', 'Place Bid')."""
+
+    token_symbol: str
+    """Token symbol if relevant."""
+
+    token_amount: str
+    """Human-readable token amount."""
+
+    warning_level: Literal["info", "caution", "danger"]
+    """UI warning level."""
+
+
+# =============================================================================
+# Web3: Signature Requests (EIP-712)
+# =============================================================================
+
+
+class EIP712Domain(TypedDict, total=False):
+    """EIP-712 domain separator."""
+
+    name: str
+    """Domain name (e.g., 'Hyperliquid', 'ClobAuthDomain')."""
+
+    version: str
+    """Domain version."""
+
+    chainId: int
+    """Chain ID (informational - signing is chain-agnostic)."""
+
+    verifyingContract: str
+    """Optional verifying contract address (0x...)."""
+
+
+class EIP712TypeField(TypedDict):
+    """A single field in an EIP-712 type definition."""
+
+    name: str
+    type: str
+
+
+class SignatureRequest(TypedDict, total=False):
+    """
+    Signature Request for EIP-712 typed data signing.
+
+    Use this for platforms with proxy wallets (Hyperliquid, Polymarket, dYdX).
+
+    Benefits:
+    - No gas required (user signs a message, not a transaction)
+    - No network switching needed (signing is chain-agnostic)
+    - Works with Privy embedded wallets on any chain
+    """
+
+    _action: Literal["signature_request"]
+    """Action type identifier (required)."""
+
+    domain: EIP712Domain
+    """EIP-712 domain separator (required)."""
+
+    types: dict[str, list[EIP712TypeField]]
+    """EIP-712 type definitions (required)."""
+
+    primaryType: str
+    """The primary type being signed (required)."""
+
+    message: dict[str, Any]
+    """The message data to sign (required)."""
+
+    meta: HandshakeMeta
+    """UI metadata for the approval card."""
+
+    callbackToolName: str
+    """Optional: Tool name to call with the signature result."""
+
+
+# =============================================================================
+# Web3: Transaction Proposals
+# =============================================================================
+
+
+class TransactionProposalMeta(HandshakeMeta, total=False):
+    """Extended metadata for transaction proposals."""
+
+    estimated_gas: str
+    """Estimated gas cost (informational - Context may sponsor)."""
+
+    explorer_url: str
+    """Link to contract on block explorer."""
+
+
+class TransactionProposal(TypedDict, total=False):
+    """
+    Transaction Proposal for direct on-chain actions.
+
+    Use this for protocols without proxy wallets (Uniswap, NFT mints, etc.).
+
+    Note: May require network switching and gas fees.
+    """
+
+    _action: Literal["transaction_proposal"]
+    """Action type identifier (required)."""
+
+    chainId: int
+    """EVM chain ID (e.g., 137 for Polygon, 8453 for Base) (required)."""
+
+    to: str
+    """Target contract address (0x...) (required)."""
+
+    data: str
+    """Encoded calldata (0x...) (required)."""
+
+    value: str
+    """Wei to send (as string, default '0')."""
+
+    meta: TransactionProposalMeta
+    """UI metadata for the approval card."""
+
+
+# =============================================================================
+# Web2: OAuth Requests
+# =============================================================================
+
+
+class AuthRequiredMeta(TypedDict, total=False):
+    """Metadata for OAuth requests."""
+
+    display_name: str
+    """Human-friendly service name."""
+
+    scopes: list[str]
+    """Permissions being requested."""
+
+    description: str
+    """Description of what access is needed."""
+
+    icon_url: str
+    """Tool's icon URL."""
+
+    expires_in: str
+    """How long authorization lasts."""
+
+
+class AuthRequired(TypedDict, total=False):
+    """
+    Auth Required for OAuth flows.
+
+    Use this when your tool needs the user to authenticate with an external service.
+    """
+
+    _action: Literal["auth_required"]
+    """Action type identifier (required)."""
+
+    provider: str
+    """Service identifier (e.g., 'discord', 'slack') (required)."""
+
+    authUrl: str
+    """Your OAuth initiation endpoint (MUST be HTTPS) (required)."""
+
+    meta: AuthRequiredMeta
+    """UI metadata for the auth card."""
+
+
+# =============================================================================
+# Union Type
+# =============================================================================
+
+HandshakeAction = Union[SignatureRequest, TransactionProposal, AuthRequired]
+
+# =============================================================================
+# Type Guards
+# =============================================================================
+
+
+def is_handshake_action(value: Any) -> bool:
+    """Check if a value is a handshake action."""
+    if not isinstance(value, dict):
+        return False
+    action = value.get("_action")
+    return action in ("signature_request", "transaction_proposal", "auth_required")
+
+
+def is_signature_request(value: Any) -> bool:
+    """Check if a value is a signature request."""
+    return is_handshake_action(value) and value.get("_action") == "signature_request"
+
+
+def is_transaction_proposal(value: Any) -> bool:
+    """Check if a value is a transaction proposal."""
+    return is_handshake_action(value) and value.get("_action") == "transaction_proposal"
+
+
+def is_auth_required(value: Any) -> bool:
+    """Check if a value is an auth required action."""
+    return is_handshake_action(value) and value.get("_action") == "auth_required"
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def create_signature_request(
+    *,
+    domain: EIP712Domain,
+    types: dict[str, list[EIP712TypeField]],
+    primary_type: str,
+    message: dict[str, Any],
+    meta: HandshakeMeta | None = None,
+    callback_tool_name: str | None = None,
+) -> SignatureRequest:
+    """
+    Create a signature request response.
+
+    Use this for platforms with proxy wallets (Hyperliquid, Polymarket, dYdX).
+    Benefits: No gas required, no network switching needed.
+
+    Args:
+        domain: EIP-712 domain separator
+        types: EIP-712 type definitions
+        primary_type: The primary type being signed
+        message: The message data to sign
+        meta: Optional UI metadata for the approval card
+        callback_tool_name: Optional tool name to call with signature result
+
+    Returns:
+        A SignatureRequest dict ready to be wrapped in a handshake response
+    """
+    result: SignatureRequest = {
+        "_action": "signature_request",
+        "domain": domain,
+        "types": types,
+        "primaryType": primary_type,
+        "message": message,
+    }
+    if meta:
+        result["meta"] = meta
+    if callback_tool_name:
+        result["callbackToolName"] = callback_tool_name
+    return result
+
+
+def create_transaction_proposal(
+    *,
+    chain_id: int,
+    to: str,
+    data: str,
+    value: str = "0",
+    meta: TransactionProposalMeta | None = None,
+) -> TransactionProposal:
+    """
+    Create a transaction proposal response.
+
+    Use this for protocols without proxy wallets (Uniswap, NFT mints, etc.).
+    Note: May require network switching and gas.
+
+    Args:
+        chain_id: EVM chain ID (e.g., 137 for Polygon, 8453 for Base)
+        to: Target contract address (0x...)
+        data: Encoded calldata (0x...)
+        value: Wei to send (as string, default '0')
+        meta: Optional UI metadata for the approval card
+
+    Returns:
+        A TransactionProposal dict ready to be wrapped in a handshake response
+    """
+    result: TransactionProposal = {
+        "_action": "transaction_proposal",
+        "chainId": chain_id,
+        "to": to,
+        "data": data,
+        "value": value,
+    }
+    if meta:
+        result["meta"] = meta
+    return result
+
+
+def create_auth_required(
+    *,
+    provider: str,
+    auth_url: str,
+    meta: AuthRequiredMeta | None = None,
+) -> AuthRequired:
+    """
+    Create an auth required response.
+
+    Use this when your tool needs the user to authenticate via OAuth.
+
+    Args:
+        provider: Service identifier (e.g., 'discord', 'slack')
+        auth_url: Your OAuth initiation endpoint (MUST be HTTPS)
+        meta: Optional UI metadata for the auth card
+
+    Returns:
+        An AuthRequired dict ready to be wrapped in a handshake response
+    """
+    result: AuthRequired = {
+        "_action": "auth_required",
+        "provider": provider,
+        "authUrl": auth_url,
+    }
+    if meta:
+        result["meta"] = meta
+    return result
+
+
+def wrap_handshake_response(action: HandshakeAction) -> dict[str, Any]:
+    """
+    Wrap a handshake action in the proper MCP response format.
+
+    MCP tools should return handshake actions in `_meta.handshakeAction` to prevent
+    the MCP SDK from stripping unknown fields.
+
+    Example:
+        >>> return wrap_handshake_response(create_signature_request(
+        ...     domain={"name": "Hyperliquid", "version": "1", "chainId": 42161},
+        ...     types={"Order": [...]},
+        ...     primary_type="Order",
+        ...     message=order_data,
+        ...     meta={"description": "Place order", "protocol": "Hyperliquid"}
+        ... ))
+
+    Args:
+        action: The handshake action (SignatureRequest, TransactionProposal, or AuthRequired)
+
+    Returns:
+        A dict with the proper MCP response format including structuredContent._meta.handshakeAction
+    """
+    action_type = action.get("_action", "unknown").replace("_", " ")
+    description = action.get("meta", {}).get("description", f"{action_type} required")
+
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": f"Handshake required: {action_type}. Please approve in the Context app.",
+            }
+        ],
+        "structuredContent": {
+            "_meta": {
+                "handshakeAction": action,
+            },
+            "status": "handshake_required",
+            "message": description,
+        },
+    }
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__ = [
+    # Types
+    "HandshakeMeta",
+    "EIP712Domain",
+    "EIP712TypeField",
+    "SignatureRequest",
+    "TransactionProposalMeta",
+    "TransactionProposal",
+    "AuthRequiredMeta",
+    "AuthRequired",
+    "HandshakeAction",
+    # Type guards
+    "is_handshake_action",
+    "is_signature_request",
+    "is_transaction_proposal",
+    "is_auth_required",
+    # Helper functions
+    "create_signature_request",
+    "create_transaction_proposal",
+    "create_auth_required",
+    "wrap_handshake_response",
+]

{ctxprotocol-0.5.6.dist-info → ctxprotocol-0.5.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.5.6
+Version: 0.5.7
 Summary: Official Python SDK for the Context Protocol - Discover and execute AI tools programmatically
 Project-URL: Homepage, https://ctxprotocol.com
 Project-URL: Documentation, https://docs.ctxprotocol.com
@@ -48,12 +48,26 @@ Context Protocol is **pip for AI capabilities**. Just as you install packages to
 [![Python versions](https://img.shields.io/pypi/pyversions/ctxprotocol.svg)](https://pypi.org/project/ctxprotocol/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+---
+
+### 💰 $10,000 Developer Grant Program
+
+We're funding the initial supply of MCP Tools for the Context Marketplace. **Become a Data Broker.**
+
+- **🛠️ Build:** Create an MCP Server using this SDK (Solana data, Trading tools, Scrapers, etc.)
+- **📦 List:** Publish it to the Context Registry
+- **💵 Earn:** Get a **$250–$1,000 Grant** + earn USDC every time an agent queries your tool
+
+👉 [**View Open Bounties & Apply Here**](https://docs.ctxprotocol.com/grants)
+
+---
+
 ## Why use Context?
 
 - **🔌 One Interface, Everything:** Stop integrating APIs one by one. Use a single SDK to access any tool in the marketplace.
 - **🧠 Zero-Ops:** We're a gateway to the best MCP tools. Just send the JSON and get the result.
 - **⚡️ Agentic Discovery:** Your Agent can search the marketplace at runtime to find tools it didn't know it needed.
-- **💸 Micro-Billing:** Pay only for what you use (e.g., $0.001/query). No monthly subscriptions for tools you rarely use.
+- **💸 Pay-Per-Response:** The $500/year subscription? Now $0.01/response. No monthly fees, just results.
 
 ## Who Is This SDK For?
 
@@ -282,6 +296,22 @@ The SDK implements a **selective authentication** model — discovery is open, e
 
 This matches standard API patterns (OpenAPI schemas are public, GraphQL introspection is open).
 
+## Execution Timeout & Product Design
+
+⚠️ **Important**: MCP tool execution has a **~60 second timeout** (enforced at the platform/client level, not by MCP itself). This is intentional—it encourages building pre-computed insight products rather than raw data access.
+
+**Best practice**: Run heavy queries offline (via cron jobs), store results in your database, and serve instant results via MCP. This is how Bloomberg, Nansen, and Arkham work.
+
+```python
+# ❌ BAD: Raw access (timeout-prone, no moat)
+{"name": "run_sql", "description": "Run any SQL against blockchain data"}
+
+# ✅ GOOD: Pre-computed product (instant, defensible)
+{"name": "get_smart_money_wallets", "description": "Top 100 wallets that timed market tops"}
+```
+
+See the [full documentation](https://docs.ctxprotocol.com/guides/build-tools#execution-limits--product-design) for detailed guidance.
+
 ## Context Injection (Personalized Tools)
 
 For tools that analyze user data, Context automatically injects user context:

{ctxprotocol-0.5.6.dist-info → ctxprotocol-0.5.7.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ctxprotocol/__init__.py,sha256=3nI2BrD1dmzezm1vi8pcKgrErrkX5K_Izyb3LbnXdSo,3613
+ctxprotocol/__init__.py,sha256=m7s0VtVaMwm-cBBXpvBN30M3RfgDgMTIwcpY_vqVHFg,4755
 ctxprotocol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxprotocol/auth/__init__.py,sha256=J1AWTpN-KKCYfFRMtIW8z8jvBvJHE4cB7Z6t2PjFsVA,13202
 ctxprotocol/client/__init__.py,sha256=dgtQ9_pzVthsNJazibWHcFkdTjZQlT_gn7SuPCsBOHo,940
@@ -11,6 +11,7 @@ ctxprotocol/context/__init__.py,sha256=v_auetqp3w0eScRLhWGbFHXGRfgjcNzTEeeMKOAxi
 ctxprotocol/context/hyperliquid.py,sha256=M59Ku48yCdfpS9_b5l8SyEFukZwbNb8P1xAh2P0Yh-0,7603
 ctxprotocol/context/polymarket.py,sha256=GcBay3VRKf4MQj49VLmhOPrU172_aNa4i2TPS9-sZuQ,3484
 ctxprotocol/context/wallet.py,sha256=g6pXMY_olLn3-4ULQQKmtpDcZ_u9kgCwIdc0JFEkckE,1742
-ctxprotocol-0.5.6.dist-info/METADATA,sha256=hbhW8_vWmyaKWVly5hbLoU8ToV83swFWHHVxR0klTnw,10364
-ctxprotocol-0.5.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ctxprotocol-0.5.6.dist-info/RECORD,,
+ctxprotocol/handshake/__init__.py,sha256=GUWa1lKacLq463cgVaTu5K2Wrx9E8EhJIVbCUbqhwMs,12300
+ctxprotocol-0.5.7.dist-info/METADATA,sha256=cNNsRcxhzJ4Y-jucq1PxJw11bH1sA-L2QfOpQKjFkjs,11706
+ctxprotocol-0.5.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ctxprotocol-0.5.7.dist-info/RECORD,,