Skip to main content
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.
1

Install System Dependencies

The Python SDK depends on starknet.py, which requires certain system libraries to be installed first.
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.
2

Install the Python SDK

pip install 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.
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
3

Get your API Keys

The Python SDK requires both your public key AND secret key for authentication.
  1. Go to your API Keys in the Chipi Dashboard
  2. Copy your Public Key (pk_prod_xxxx)
  3. 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.
4

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",
    )
)
5

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
6

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}")

​
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:

​
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.