> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Quickstart

> Quick setup guide for the Chipi Python SDK - server-side wallet management and gasless transactions for Python applications

> [!WARNING]
>
> 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.

> [!WARNING]
>
> **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.

> [tab] macOS
>
> > [!NOTE]
> >
> > The following instructions assume [Homebrew](https://brew.sh) is installed.
>
> First, install `cmake` (required for building crypto dependencies):
>
> ```bash theme={null}
> brew install cmake gmp
> ```
>
> > [!WARNING]
> >
> > If you're using an Apple Silicon Mac (M1/M2/M3), you may need to set additional flags during installation. See the [installation section](#installing-the-sdk) below.
>
> For more details on macOS installation, see the [starknet.py installation guide](https://starknetpy.readthedocs.io/en/latest/installation.html).

> [tab] Linux
>
> ```bash theme={null}
> sudo apt install -y libgmp3-dev
> ```
>
> For more details, see the [starknet.py installation guide](https://starknetpy.readthedocs.io/en/latest/installation.html).

> [tab] Windows
>
> > [!NOTE]
> >
> > Windows installation requires MinGW. The recommended way to install is through [chocolatey](https://chocolatey.org/).
>
> After installing chocolatey, run:
>
> ```bash theme={null}
> 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](https://starknetpy.readthedocs.io/en/latest/installation.html).

## 2. Install the Python SDK

```bash pip theme={null}
pip install chipi-stack
```

```bash poetry theme={null}
poetry add chipi-stack
```

```bash uv theme={null}
uv add chipi-stack
```

> [!NOTE]
>
> **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`.

> [accordion] Apple Silicon Installation
>
> If you're on an Apple Silicon Mac (M1/M2/M3) and encounter issues, use these flags:
>
> ```bash theme={null}
> CFLAGS=-I`brew --prefix gmp`/include LDFLAGS=-L`brew --prefix gmp`/lib pip install chipi-stack
> ```

## 3. Get your API Keys

> [!WARNING]
>
> The Python SDK requires **both** your public key AND secret key for authentication.

1. Go to your [API Keys](https://dashboard.chipipay.com/configure/api-keys) in the Chipi Dashboard
2. Copy your **Public Key** (`pk_prod_xxxx`)
3. Copy your **Secret Key** (`sk_prod_xxxx`)

> [!NOTE]
>
> 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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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}")
```

## 7. Environment Variables (Recommended)

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

```bash theme={null}
# .env
CHIPI_PUBLIC_KEY=pk_prod_your_public_key
CHIPI_SECRET_KEY=sk_prod_your_secret_key
```

Then initialize the SDK:

```python theme={null}
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"),
    )
)
```

> [!TIP]
>
> Consider using [python-dotenv](https://pypi.org/project/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:

```python theme={null}
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())
```

> [!NOTE]
>
> 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](https://docs.chipipay.com/sdk/python/methods/create-wallet.md)** - Detailed wallet creation guide
* **[Transfer Tokens](https://docs.chipipay.com/sdk/python/methods/transfer.md)** - Send USDC and other tokens
* **[Backend API Reference](https://docs.chipipay.com/sdk/backend/quickstart.md)** - Full SDK method documentation

## Security Best Practices

> [!WARNING]
>
> * 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)

> [!TIP]
>
> Need help? Join our [Telegram Community](https://t.me/+e2qjHEOwImkyZDVh) for support and to connect with other developers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.