Turnkey Wallet Client

A Python client for interacting with Turnkey's wallet infrastructure, focused on signing for transactions called by scheduled processes.

Features

• Wallet Management: Create and manage wallets and accounts
• Transaction Signing: Sign transactions across multiple blockchains
• Scheduled Operations: Schedule transaction signing for automated execution
• API Key Authentication: Secure interaction with Turnkey APIs
• MCP Server Support: Integration with Model Context Protocol (MCP) for AI assistant capabilities

Installation

pip install turnkey-wallet-client

Or install directly from the repository:

pip install git+https://github.com/your-username/turnkey-wallet-client.git

Quick Start

Basic Client Usage

import asyncio
from turnkey_wallet_client import TurnkeyClient, ApiKeyAuthenticator

async def main():
    # Initialize the client with API credentials
    auth = ApiKeyAuthenticator(
        organization_id="YOUR_ORGANIZATION_ID",
        api_public_key="YOUR_API_PUBLIC_KEY",
        api_private_key="YOUR_API_PRIVATE_KEY"
    )
    
    client = TurnkeyClient(auth=auth)
    
    try:
        # List all wallets
        wallets = await client.list_wallets(organization_id="YOUR_ORGANIZATION_ID")
        print(f"Found {len(wallets)} wallets")
        
        # Create a new wallet
        wallet_id = await client.create_wallet(
            name="My Wallet",
            organization_id="YOUR_ORGANIZATION_ID"
        )
        print(f"Created wallet with ID: {wallet_id}")
        
        # Create a wallet account
        account_address = await client.create_wallet_account(
            wallet_id=wallet_id,
            organization_id="YOUR_ORGANIZATION_ID"
        )
        print(f"Created account with address: {account_address}")
        
        # Sign a transaction
        signed_tx = await client.sign_transaction(
            wallet_account=account_address,
            unsigned_transaction="YOUR_UNSIGNED_TRANSACTION",
            transaction_type="TRANSACTION_TYPE_ETHEREUM",
            organization_id="YOUR_ORGANIZATION_ID"
        )
        print(f"Transaction signed: {signed_tx}")
    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Scheduled Transactions

import asyncio
from datetime import datetime, timedelta
from turnkey_wallet_client import TurnkeyClient, ApiKeyAuthenticator
from turnkey_wallet_client.scheduler import TurnkeyScheduler
from turnkey_wallet_client.models import TransactionType

async def main():
    # Initialize the client
    auth = ApiKeyAuthenticator(
        organization_id="YOUR_ORGANIZATION_ID",
        api_public_key="YOUR_API_PUBLIC_KEY",
        api_private_key="YOUR_API_PRIVATE_KEY"
    )
    client = TurnkeyClient(auth=auth)
    
    try:
        # Create a scheduler
        scheduler = TurnkeyScheduler(client)
        
        # Start the scheduler
        await scheduler.start()
        
        # Schedule a recurring transaction to run every hour
        await scheduler.schedule_transaction_signing(
            task_id="hourly-payment",
            wallet_account="YOUR_WALLET_ACCOUNT",
            unsigned_transaction="YOUR_UNSIGNED_TRANSACTION",
            transaction_type=TransactionType.ETHEREUM,
            organization_id="YOUR_ORGANIZATION_ID",
            run_at=datetime.now() + timedelta(minutes=5),  # First run in 5 minutes
            interval=timedelta(hours=1),  # Then every hour
            max_retries=3
        )
        
        # Run for a day
        await asyncio.sleep(24 * 60 * 60)
    finally:
        # Stop the scheduler and close the client
        await scheduler.stop()
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Using the MCP Server with an AI Assistant

This project includes a Model Context Protocol (MCP) server that allows LLM-powered AI assistants to interact with the Turnkey wallet infrastructure. The MCP server exposes tools for wallet management, transaction signing, and scheduling.

Running the MCP Server

python mcp_server.py

Using with Claude Desktop or Other MCP Clients

The MCP server can be integrated with Claude Desktop or other MCP-compatible clients through the included agent:

python agent.py

Available MCP Tools

The MCP server exposes the following tools:

• initialize_client: Set up API credentials
• create_wallet: Create a new wallet
• list_wallets: List all wallets
• create_wallet_account: Create a new wallet account
• list_wallet_accounts: List all accounts in a wallet
• sign_transaction: Sign a transaction with a wallet account
• sign_raw_payload: Sign a raw payload with a wallet account
• schedule_transaction: Schedule a transaction signing task
• schedule_raw_payload: Schedule a raw payload signing task
• get_task_status: Get the status of a scheduled task
• remove_task: Remove a scheduled task
• get_scheduler_status: Get the current status of the scheduler

Configuration

The client and MCP server can be configured using environment variables:

• TURNKEY_API_BASE_URL: The base URL for API requests (optional)
• TURNKEY_ORGANIZATION_ID: Your Turnkey organization ID
• TURNKEY_API_PUBLIC_KEY: Your API public key
• TURNKEY_API_PRIVATE_KEY: Your API private key

Alternatively, you can pass these values directly when initializing the client or MCP server.

Scheduling Features

The scheduler provides flexible options for automated transaction signing:

• One-Time Execution: Schedule tasks to run at a specific future time
• Recurring Execution: Schedule tasks to run at regular intervals
• Error Handling: Automatic retries with configurable settings
• Status Monitoring: Track task execution and results
• Task Management: Add, remove, and list scheduled tasks

Examples

See the examples directory for more usage examples:

• basic_signing.py: Basic transaction signing example
• scheduled_signing.py: Examples of using the scheduler
• scheduled_payment.py: Example of setting up recurring payments

Security Considerations

• API keys and private keys should be stored securely and not hardcoded in your application
• Use environment variables or secure secret management systems
• For production use, implement proper error handling and logging

License

MIT License