Python SDK Quickstart

The Python SDK is designed for server-side use. You must use both your public and secret API keys. Never expose your secret key in client-side code.

PIN is weak — not recommended for production.A user-typed PIN is a short, low-entropy string. Anyone who shoulder-surfs the PIN, observes a phishing form, or compromises the browser at typing time can decrypt the wallet’s private key. PIN remains in the SDK only as a fallback recovery surface for users who lose access to their platform authenticator.Production embedded-wallet apps should default to a platform passkey (Touch ID, Face ID, Windows Hello, Android biometrics) via the @chipi-stack/chipi-passkey package. For SHHH V8.4 wallets, signerKind: "WEBAUTHN_P256" keeps the private key inside the platform authenticator — it never leaves the device, never reaches Chipi servers, and is never derived from a user-typed secret.Only prompt for a PIN as the encryption key when:

The user explicitly opted into a PIN-only flow (e.g. cold-storage / paper-backup recovery), or
The platform genuinely has no WebAuthn / biometric support available.

If you are migrating an existing PIN-based wallet to a passkey, look up useMigrateWalletToPasskey in your framework’s hook docs.

Install System Dependencies

The Python SDK depends on starknet.py, which requires certain system libraries to be installed first.

macOS
Linux
Windows

The following instructions assume Homebrew is installed.

First, install cmake (required for building crypto dependencies):

brew install cmake gmp

If you’re using an Apple Silicon Mac (M1/M2/M3), you may need to set additional flags during installation. See the installation section below.

For more details on macOS installation, see the starknet.py installation guide.

sudo apt install -y libgmp3-dev

For more details, see the starknet.py installation guide.

Windows installation requires MinGW. The recommended way to install is through chocolatey.

After installing chocolatey, run:

choco install mingw

Make sure MinGW is in your PATH (e.g., C:\ProgramData\chocolatey\lib\mingw\tools\install\mingw64\bin).For more details and troubleshooting, see the starknet.py installation guide.

Install the Python SDK

pip install chipi-stack

poetry add chipi-stack

uv add chipi-stack

Install: chipi-stack (PyPI). Import: from chipi_sdk import .... The PyPI package name and the Python module name differ — pip install chipi-stack succeeds, but import chipi_stack will fail. Always import from chipi_sdk.

Apple Silicon Installation

If you’re on an Apple Silicon Mac (M1/M2/M3) and encounter issues, use these flags:

CFLAGS=-I`brew --prefix gmp`/include LDFLAGS=-L`brew --prefix gmp`/lib pip install chipi-stack

Get your API Keys

The Python SDK requires both your public key AND secret key for authentication.

Go to your API Keys in the Chipi Dashboard
Copy your Public Key (pk_prod_xxxx)
Copy your Secret Key (sk_prod_xxxx)

Your secret key is used for backend authentication. Keep it secure and never commit it to version control.

Initialize the SDK

Create a new instance of the ChipiSDK with your API keys:

from chipi_sdk import ChipiSDK, ChipiSDKConfig

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

Create Your First Wallet

Now you can create a wallet for your users:

from chipi_sdk import CreateWalletParams, WalletType

# Create a new wallet
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
    )
)

print(f"Wallet created: {wallet_response.public_key}")
print(f"Deployed: {wallet_response.is_deployed}")

# wallet_response is a flat object — use it directly
# wallet_response.public_key
# wallet_response.encrypted_private_key

Make Your First Transfer

Transfer USDC between wallets:

from chipi_sdk import TransferParams, ChainToken, WalletData

# Transfer USDC
tx_hash = sdk.transfer(
    params=TransferParams(
        encrypt_key="user-secure-pin",
        wallet=WalletData(
            public_key=wallet_response.public_key,
            encrypted_private_key=wallet_response.encrypted_private_key,
        ),
        token=ChainToken.USDC,
        recipient="0x1234567890abcdef...",  # Recipient address
        amount="1.5",  # Amount in USDC
    )
)

print(f"Transfer completed! TX: {tx_hash}")
print(f"View on Starkscan: https://starkscan.co/tx/{tx_hash}")

Environment Variables (Recommended)

For production applications, store your API keys as environment variables:

# .env
CHIPI_PUBLIC_KEY=pk_prod_your_public_key
CHIPI_SECRET_KEY=sk_prod_your_secret_key

Then initialize the SDK:

import os
from chipi_sdk import ChipiSDK, ChipiSDKConfig

sdk = ChipiSDK(
    config=ChipiSDKConfig(
        api_public_key=os.getenv("CHIPI_PUBLIC_KEY"),
        api_secret_key=os.getenv("CHIPI_SECRET_KEY"),
    )
)

Consider using python-dotenv to load environment variables from .env files.

Async Support

The Python SDK supports both sync and async operations. For better performance in async applications, use the async methods:

import asyncio
from chipi_sdk import ChipiSDK, ChipiSDKConfig, CreateWalletParams

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

async def create_wallet_async():
    wallet_response = await sdk.acreate_wallet(
        params=CreateWalletParams(
            encrypt_key="user-secure-pin",
            external_user_id="your-user-id-123",
        )
    )
    return wallet_response

# Run async function
wallet = asyncio.run(create_wallet_async())

All SDK methods have async equivalents prefixed with a (e.g., create_wallet → acreate_wallet, transfer → atransfer).

Next Steps

Now that you have the basic setup working, explore more advanced features:

Create Wallet - Detailed wallet creation guide
Transfer Tokens - Send USDC and other tokens
Backend API Reference - Full SDK method documentation

Security Best Practices

Never commit your secret API key to version control
Use environment variables for all sensitive credentials
Validate user inputs before making API calls
Securely store wallet encryption keys (never in plaintext)

Need help? Join our Telegram Community for support and to connect with other developers.

Getting Started

Methods

Python SDK Quickstart

Install System Dependencies

Install the Python SDK

Get your API Keys

Initialize the SDK

Create Your First Wallet

Make Your First Transfer

Environment Variables (Recommended)

Async Support

Next Steps

Security Best Practices

Install System Dependencies

Install the Python SDK

Get your API Keys

Initialize the SDK

Create Your First Wallet

Make Your First Transfer

Environment Variables (Recommended)

​Async Support

​Next Steps

​Security Best Practices

Async Support

Next Steps

Security Best Practices