feat: add TVM exact-payment mechanism to Python SDK

.gitignore

@@ -27,6 +27,7 @@ e2e/servers/gin/server
 e2e/servers/nethttp/nethttp
 e2e/servers/mcp-go/mcp-go
 e2e/servers/mcp-go/mcp-server
+e2e/servers/nethttp/nethttp
 e2e/legacy/servers/gin/gin
 
 # Example build artifacts

e2e/README.md

@@ -48,11 +48,11 @@ pnpm test
 ```
 
 Launches an interactive CLI where you can select:
-- **Facilitators** - Payment verification/settlement services (Go, TypeScript)
+- **Facilitators** - Payment verification/settlement services (Go, TypeScript, Python)
 - **Servers** - Protected endpoints requiring payment (Express, Gin, Hono, Next.js, FastAPI, Flask, etc.)
 - **Clients** - Payment-capable HTTP clients (axios, fetch, httpx, requests, etc.)
 - **Extensions** - Additional features like Bazaar discovery
-- **Protocols** - EVM, SVM, and/or Aptos networks
+- **Protocols** - EVM, SVM, Aptos, Stellar, and/or TVM networks
 
 Every valid combination of your selections will be tested. For example, selecting 2 facilitators, 3 servers, and 2 clients will generate and run all compatible test scenarios.
 
@@ -115,18 +115,24 @@ CLIENT_EVM_PRIVATE_KEY=0x...        # EVM private key for client payments
 CLIENT_SVM_PRIVATE_KEY=...          # Solana private key for client payments
 CLIENT_APTOS_PRIVATE_KEY=...        # Aptos private key for client payments (hex string)
 CLIENT_STELLAR_PRIVATE_KEY=...      # Stellar private key for client payments
+CLIENT_TVM_PRIVATE_KEY=...          # TVM private key for client payments
 
 # Server payment addresses
 SERVER_EVM_ADDRESS=0x...            # Where servers receive EVM payments
 SERVER_SVM_ADDRESS=...              # Where servers receive Solana payments
 SERVER_APTOS_ADDRESS=0x...          # Where servers receive Aptos payments
 SERVER_STELLAR_ADDRESS=...          # Where servers receive Stellar payments
+SERVER_TVM_ADDRESS=...              # Where servers receive TVM payments
 
 # Facilitator wallets (⚠️ TEST WALLETS ONLY — used to fund/drain client between tests)
 FACILITATOR_EVM_PRIVATE_KEY=0x...   # EVM private key for facilitator
 FACILITATOR_SVM_PRIVATE_KEY=...     # Solana private key for facilitator
 FACILITATOR_APTOS_PRIVATE_KEY=...   # Aptos private key for facilitator (hex string)
 FACILITATOR_STELLAR_PRIVATE_KEY=... # Stellar private key for facilitator
+FACILITATOR_TVM_PRIVATE_KEY=...     # TVM private key for facilitator
+
+# TVM support
+TONCENTER_API_KEY=...               # Recommended for TVM client/facilitator access
 ```
 
 ### Account Setup Instructions
@@ -153,7 +159,7 @@ $ pnpm test --min
 ✔ Select servers › express, hono, legacy-express
 ✔ Select clients › axios, fetch, httpx
 ✔ Select extensions › bazaar
-✔ Select protocol families › EVM, SVM, Aptos, Stellar
+✔ Select protocol families › EVM, SVM, Aptos, Stellar, TVM
 
 📊 Coverage-Based Minimization
 Total scenarios: 156

e2e/clients/mcp-python/main.py

@@ -18,11 +18,15 @@
 server_url = os.getenv("RESOURCE_SERVER_URL", "")
 endpoint_path = os.getenv("ENDPOINT_PATH", "")  # tool name, e.g. "get_weather"
 evm_private_key = os.getenv("EVM_PRIVATE_KEY", "")
+tvm_private_key = os.getenv("TVM_PRIVATE_KEY", "")
 
-if not server_url or not endpoint_path or not evm_private_key:
+if not server_url or not endpoint_path or not (evm_private_key or tvm_private_key):
     result = {
         "success": False,
-        "error": "Missing required environment variables: RESOURCE_SERVER_URL, ENDPOINT_PATH, EVM_PRIVATE_KEY",
+        "error": (
+            "Missing required environment variables: RESOURCE_SERVER_URL, ENDPOINT_PATH, "
+            "and one of EVM_PRIVATE_KEY or TVM_PRIVATE_KEY"
+        ),
     }
     print(json.dumps(result))
     sys.exit(1)
@@ -36,21 +40,34 @@ async def main() -> dict:
     from x402.mcp import create_x402_mcp_client
     from x402.mechanisms.evm.exact import register_exact_evm_client
     from x402.mechanisms.evm.signers import EthAccountSigner
-
-    # Create x402 client with EVM scheme
+    from x402.mechanisms.tvm import (
+        TVM_MAINNET,
+        TVM_TESTNET,
+        WalletV5R1Config,
+        WalletV5R1MnemonicSigner,
+    )
+    from x402.mechanisms.tvm.exact import register_exact_tvm_client
+
+    # Create x402 client with the configured payment schemes
     client = x402Client()
-    account = Account.from_key(evm_private_key)
-    evm_signer = EthAccountSigner(account)
-    register_exact_evm_client(client, evm_signer)
+    if evm_private_key:
+        account = Account.from_key(evm_private_key)
+        evm_signer = EthAccountSigner(account)
+        register_exact_evm_client(client, evm_signer)
+
+    if tvm_private_key:
+        tvm_network = os.getenv("TVM_NETWORK", TVM_TESTNET)
+        if tvm_network not in {TVM_TESTNET, TVM_MAINNET}:
+            raise ValueError(f"Unsupported TVM network: {tvm_network}")
+        tvm_config = WalletV5R1Config.from_private_key(tvm_network, tvm_private_key)
+        tvm_config.api_key = os.getenv("TONCENTER_API_KEY")
+        tvm_config.base_url = os.getenv("TONCENTER_BASE_URL")
+        register_exact_tvm_client(client, WalletV5R1MnemonicSigner(tvm_config))
 
     try:
-        async with create_x402_mcp_client(
-            client, server_url, auto_payment=True
-        ) as mcp:
+        async with create_x402_mcp_client(client, server_url, auto_payment=True) as mcp:
             # Call the paid tool - payment is handled automatically
-            result = await mcp.call_tool(
-                endpoint_path, {"city": "San Francisco"}
-            )
+            result = await mcp.call_tool(endpoint_path, {"city": "San Francisco"})
 
             # Extract data from content
             data = None

e2e/clients/mcp-python/pyproject.toml

@@ -6,7 +6,7 @@ requires-python = ">=3.10"
 dependencies = [
     "python-dotenv>=1.0.0",
     "mcp>=1.9.0",
-    "x402[evm,mcp]"
+    "x402[evm,tvm,mcp]"
 ]
 
 [build-system]

e2e/clients/mcp-python/test.config.json

@@ -4,20 +4,28 @@
   "transport": "mcp",
   "language": "python",
   "protocolFamilies": [
-    "evm"
+    "evm",
+    "tvm"
   ],
   "x402Versions": [
     2
   ],
   "evm": {
-    "transferMethods": ["eip3009"]
+    "transferMethods": [
+      "eip3009"
+    ]
   },
   "environment": {
     "required": [
-      "EVM_PRIVATE_KEY",
       "RESOURCE_SERVER_URL",
       "ENDPOINT_PATH"
     ],
-    "optional": []
+    "optional": [
+      "EVM_PRIVATE_KEY",
+      "TVM_PRIVATE_KEY",
+      "TVM_NETWORK",
+      "TONCENTER_API_KEY",
+      "TONCENTER_BASE_URL"
+    ]
   }
 }