Skip to main content

​
Usage

from chipi_sdk import CreateWalletParams, WalletType

wallet_response = sdk.create_wallet(
    params=CreateWalletParams(
        encrypt_key="user-secure-pin",
        external_user_id="your-user-id-123",
        wallet_type=WalletType.CHIPI,  # Optional, defaults to CHIPI
    )
)

​
Parameters

  • encrypt_key (str): A user-defined code or password used to encrypt the wallet’s private key
  • external_user_id (str): Your application’s unique identifier for the user
  • user_id (str, optional): Internal user ID (optional)
  • wallet_type (WalletType, optional): Type of wallet to create (CHIPI or READY). Defaults to CHIPI
  • use_passkey (bool, optional): Whether to use passkey authentication. Defaults to False

​
Return Value

Returns a CreateWalletResponse object containing:
  • wallet: WalletData object with:
    • public_key: Wallet’s public address
    • encrypted_private_key: AES encrypted private key
    • wallet_type: Type of wallet created
    • normalized_public_key: Normalized public key
  • tx_hash: Transaction hash of the wallet deployment
  • wallet_public_key: Public key of the created wallet (same as wallet.public_key)

​
Example Implementation

from chipi_sdk import ChipiSDK, ChipiSDKConfig, CreateWalletParams, WalletType

# Initialize SDK
sdk = ChipiSDK(
    config=ChipiSDKConfig(
        api_public_key="pk_prod_your_public_key",
        api_secret_key="sk_prod_your_secret_key",
    )
)

def create_user_wallet(user_id: str, user_pin: str):
    """Create a new wallet for a user."""
    try:
        wallet_response = sdk.create_wallet(
            params=CreateWalletParams(
                encrypt_key=user_pin,
                external_user_id=user_id,
                wallet_type=WalletType.CHIPI,
            )
        )

        print(f"✅ Wallet created successfully!")
        print(f"   Address: {wallet_response.wallet_public_key}")
        print(f"   Deployment TX: {wallet_response.tx_hash}")
        print(f"   View on Starkscan: https://starkscan.co/tx/{wallet_response.tx_hash}")

        # Store wallet data securely in your database
        save_wallet_to_database(
            user_id=user_id,
            public_key=wallet_response.wallet.public_key,
            encrypted_private_key=wallet_response.wallet.encrypted_private_key,
            deployment_tx_hash=wallet_response.tx_hash,
        )

        return wallet_response

    except Exception as error:
        print(f"❌ Wallet creation failed: {error}")
        raise

# Usage
def onboard_new_user(user_id: str, pin: str):
    """Onboard a new user by creating their wallet."""
    wallet = create_user_wallet(user_id, pin)
    
    # Verify deployment on StarkScan
    contract_url = f"https://starkscan.co/contract/{wallet.wallet_public_key}"
    print(f"View contract: {contract_url}")
    
    return wallet

# Create wallet
wallet = onboard_new_user("user-123", "secure-pin-1234")

​
Async Version

For async applications, use acreate_wallet: 
import asyncio

async def create_user_wallet_async(user_id: str, user_pin: str):
    """Create a new wallet asynchronously."""
    wallet_response = await sdk.acreate_wallet(
        params=CreateWalletParams(
            encrypt_key=user_pin,
            external_user_id=user_id,
            wallet_type=WalletType.CHIPI,
        )
    )
    return wallet_response

# Run async
wallet = asyncio.run(create_user_wallet_async("user-123", "secure-pin-1234"))

​
Wallet Types

The SDK supports two wallet types:

​
Security Considerations

Encryption Key SecurityThe encrypt_key is critical for wallet security:
  • Never store it in plaintext
  • Use a secure method to derive it (e.g., from user password with PBKDF2)
  • Consider using hardware security modules (HSM) for production
External User IDThe external_user_id should be:
  • Unique per user in your system
  • Stable (doesn’t change over time)
  • Not personally identifiable information (use a UUID instead of email)

​
Error Handling

from chipi_sdk import ChipiTransactionError, ChipiApiError

try:
    wallet = sdk.create_wallet(
        params=CreateWalletParams(
            encrypt_key="user-pin",
            external_user_id="user-123",
        )
    )
except ChipiTransactionError as e:
    # Handle transaction-specific errors
    print(f"Transaction error: {e.message}")
    print(f"Error code: {e.code}")
except ChipiApiError as e:
    # Handle API errors
    print(f"API error: {e.message}")
    print(f"Status: {e.status}")
except Exception as e:
    # Handle other errors
    print(f"Unexpected error: {e}")

​
Complete Example with Database Integration

from chipi_sdk import ChipiSDK, ChipiSDKConfig, CreateWalletParams, WalletType
import sqlite3
from datetime import datetime

# Initialize SDK
sdk = ChipiSDK(
    config=ChipiSDKConfig(
        api_public_key="pk_prod_your_public_key",
        api_secret_key="sk_prod_your_secret_key",
    )
)

def save_wallet_to_db(user_id: str, wallet_data: dict):
    """Save wallet data to database."""
    conn = sqlite3.connect('app.db')
    cursor = conn.cursor()
    
    cursor.execute('''
        INSERT INTO wallets (user_id, public_key, encrypted_private_key, created_at)
        VALUES (?, ?, ?, ?)
    ''', (
        user_id,
        wallet_data['public_key'],
        wallet_data['encrypted_private_key'],
        datetime.now().isoformat()
    ))
    
    conn.commit()
    conn.close()

def create_and_save_wallet(user_id: str, user_pin: str):
    """Create wallet and save to database."""
    # Create wallet
    wallet_response = sdk.create_wallet(
        params=CreateWalletParams(
            encrypt_key=user_pin,
            external_user_id=user_id,
            wallet_type=WalletType.CHIPI,
        )
    )
    
    # Save to database
    save_wallet_to_db(user_id, {
        'public_key': wallet_response.wallet.public_key,
        'encrypted_private_key': wallet_response.wallet.encrypted_private_key,
    })
    
    print(f"✅ Wallet created and saved for user: {user_id}")
    print(f"   Address: {wallet_response.wallet_public_key}")
    
    return wallet_response

# Usage
wallet = create_and_save_wallet("user-123", "secure-pin-1234")
  • get_wallet - Retrieve existing wallet information
  • transfer - Send tokens from the created wallet