Table of Contents

• spoon_ai.turnkey
• spoon_ai.turnkey.client
  • Turnkey
    • __init__
    • whoami
    • import_private_key
    • sign_evm_transaction
    • sign_typed_data
    • sign_message
    • get_activity
    • list_activities
    • get_policy_evaluations
    • get_private_key
    • create_wallet
    • create_wallet_accounts
    • get_wallet
    • get_wallet_account
    • list_wallets
    • list_wallet_accounts
    • init_import_wallet
    • encrypt_wallet
    • encrypt_private_key
    • init_import_private_key
    • import_wallet

Module spoon_ai.turnkey

Turnkey client integration for SpoonAI.

Provides Turnkey for secure signing via Turnkey API.

Module spoon_ai.turnkey.client

Turnkey Objects

class Turnkey()

Turnkey API client class for managing blockchain private keys and wallet operations.

__init__

def __init__(base_url=None,
             api_public_key=None,
             api_private_key=None,
             org_id=None)

Initialize Turnkey client.

Arguments:

• base_url str - Turnkey API base URL (defaults from .env or default value).
• api_public_key str - Turnkey API public key.
• api_private_key str - Turnkey API private key.
• org_id str - Turnkey organization ID.

Raises:

• ValueError - If required configuration parameters are missing.

whoami

def whoami()

Call whoami API to get organization information.

Returns:

• dict - JSON response containing organization information.

import_private_key

def import_private_key(user_id,
                       private_key_name,
                       encrypted_bundle,
                       curve="CURVE_SECP256K1",
                       address_formats=["ADDRESS_FORMAT_ETHEREUM"])

Import private key to Turnkey.

Arguments:

• user_id str - User ID.
• private_key_name str - Private key name.
• encrypted_bundle str - Encrypted private key bundle.
• curve str - Elliptic curve type, defaults to CURVE_SECP256K1.
• address_formats list - Address format list, defaults to ["ADDRESS_FORMAT_ETHEREUM"].

Returns:

• dict - JSON response containing imported private key information.

sign_evm_transaction

def sign_evm_transaction(sign_with, unsigned_tx)

Sign EVM transaction using Turnkey.

Arguments:

• sign_with str - Signing identity (wallet account address / private key address / private key ID).
• unsigned_tx str - Raw unsigned transaction (hex string).

Returns:

• dict - JSON response containing signing result, see signTransactionResult.signedTransaction.

  Reference: https://docs.turnkey.com/api-reference/activities/sign-transaction

sign_typed_data

def sign_typed_data(sign_with, typed_data)

Sign EIP-712 structured data.

Arguments:

• sign_with str - Signing identity (wallet account address / private key address / private key ID).
• typed_data dict|str - EIP-712 structure (domain/types/message) or its JSON string.

Returns:

• dict - Activity response, result contains r/s/v.

Notes:

• encoding uses PAYLOAD_ENCODING_EIP712
• hashFunction uses HASH_FUNCTION_NOT_APPLICABLE (server completes EIP-712 spec hashing)

sign_message

def sign_message(sign_with, message, use_keccak256=True)

Sign arbitrary message (defaults to KECCAK256 following Ethereum convention).

Arguments:

• sign_with str - Signing identity (wallet account address / private key address / private key ID).
• message str|bytes - Text to be signed; bytes will be decoded as UTF-8.
• use_keccak256 bool - Whether to use KECCAK256 as hash function (default True).

Returns:

• dict - Activity response, result contains r/s/v.

get_activity

def get_activity(activity_id)

Query Activity details.

Arguments:

• activity_id str - Activity ID.

Returns:

• dict - Activity details.

  Reference: https://docs.turnkey.com/api-reference/queries/get-activity

list_activities

def list_activities(limit=None,
                    before=None,
                    after=None,
                    filter_by_status=None,
                    filter_by_type=None)

List activities within organization (paginated).

Arguments:

• limit str|None - Number per page.
• before str|None - Pagination cursor (before).
• after str|None - Pagination cursor (after).
• filter_by_status list|None - Filter by activity status (e.g., ['ACTIVITY_STATUS_COMPLETED']).
• filter_by_type list|None - Filter by activity type (e.g., ['ACTIVITY_TYPE_SIGN_TRANSACTION_V2']).

Returns:

• dict - Activity list.

  Reference: https://docs.turnkey.com/api-reference/queries/list-activities

get_policy_evaluations

def get_policy_evaluations(activity_id)

Query policy evaluation results for an Activity (if available).

Arguments:

• activity_id str - Activity ID.

Returns:

• dict - Policy evaluation details.

  Reference: https://docs.turnkey.com/api-reference/queries/get-policy-evaluations

get_private_key

def get_private_key(private_key_id)

Query information for specified private key.

Arguments:

• private_key_id str - Private key ID.

Returns:

• dict - JSON response containing private key information.

create_wallet

def create_wallet(wallet_name, accounts, mnemonic_length=24)

Create new wallet.

Arguments:

• wallet_name str - Wallet name.
• accounts list - Account configuration list, each account contains curve, pathFormat, path, addressFormat.
• mnemonic_length int - Mnemonic length (default 24).

Returns:

• dict - JSON response containing new wallet information.

create_wallet_accounts

def create_wallet_accounts(wallet_id, accounts)

Add accounts to existing wallet.

Arguments:

• wallet_id str - Wallet ID.
• accounts list - New account configuration list, each account contains curve, pathFormat, path, addressFormat.

Returns:

• dict - JSON response containing new account information.

get_wallet

def get_wallet(wallet_id)

Query information for specified wallet.

Arguments:

• wallet_id str - Wallet ID.

Returns:

• dict - JSON response containing wallet information.

get_wallet_account

def get_wallet_account(wallet_id, address=None, path=None)

Query information for specified wallet account.

Arguments:

• wallet_id str - Wallet ID.
• address str, optional - Account address.
• path str, optional - Account path (e.g., m/44'/60'/0'/0/0).

Returns:

• dict - JSON response containing account information.

Raises:

• ValueError - If neither address nor path is provided.

list_wallets

def list_wallets()

List all wallets in the organization.

Returns:

• dict - JSON response containing wallet list.

list_wallet_accounts

def list_wallet_accounts(wallet_id, limit=None, before=None, after=None)

List account list for specified wallet.

Arguments:

• wallet_id str - Wallet ID.
• limit str, optional - Number of accounts returned per page.
• before str, optional - Pagination cursor, returns accounts before this ID.
• after str, optional - Pagination cursor, returns accounts after this ID.

Returns:

• dict - JSON response containing account list.

init_import_wallet

def init_import_wallet(user_id)

Initialize wallet import process, generate import_bundle.

Arguments:

• user_id str - User ID.

Returns:

• dict - JSON response containing import_bundle.

encrypt_wallet

def encrypt_wallet(mnemonic,
                   user_id,
                   import_bundle,
                   encryption_key_name="demo-encryption-key")

Encrypt mnemonic using Turnkey CLI, generate encrypted_bundle.

Arguments:

• mnemonic str - Mnemonic phrase (12/15/18/21/24 words).
• user_id str - User ID.
• import_bundle str - import_bundle obtained from init_import_wallet.
• encryption_key_name str - Encryption key name, defaults to demo-encryption-key.

Returns:

• str - Encrypted encrypted_bundle.

Raises:

• RuntimeError - If CLI command fails or turnkey CLI is not installed.

encrypt_private_key

def encrypt_private_key(private_key,
                        user_id,
                        import_bundle,
                        key_format="hexadecimal",
                        encryption_key_name="demo-encryption-key")

Encrypt private key using Turnkey CLI, generate encrypted_bundle, equivalent to: turnkey encrypt --import-bundle-input "./import_bundle.txt" --plaintext-input /dev/fd/3 --key-format "hexadecimal" --encrypted-bundle-output "./encrypted_bundle.txt"

Arguments:

• private_key str - Private key string (hexadecimal or Solana format).
• user_id str - User ID.
• import_bundle str - import_bundle obtained from init_import_private_key.
• key_format str - Private key format, defaults to "hexadecimal" (supports "hexadecimal", "solana").
• encryption_key_name str - Encryption key name, defaults to "demo-encryption-key".

Returns:

• str - Encrypted encrypted_bundle (Base64 encoded string).

Raises:

• ValueError - If private_key, user_id, import_bundle is empty or key_format is invalid.
• RuntimeError - If CLI command fails or turnkey CLI is not installed.

init_import_private_key

def init_import_private_key(user_id)

Initialize private key import process, generate import_bundle.

Arguments:

• user_id str - User ID.

Returns:

• dict - JSON response containing import_bundle.

import_wallet

def import_wallet(user_id, wallet_name, encrypted_bundle, accounts=None)

Import wallet to Turnkey.

Arguments:

• user_id str - User ID.
• wallet_name str - Wallet name.
• encrypted_bundle str - Encrypted mnemonic bundle.
• accounts list, optional - Account configuration list, each account contains curve, pathFormat, path, addressFormat.

Returns:

• dict - JSON response containing imported wallet information.