> ## 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>

<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.
</Warning>

<Steps>
  <Step title="Install System Dependencies" titleSize="h2">
    The Python SDK depends on `starknet.py`, which requires certain system libraries to be installed first.

    <Tabs>
      <Tab title="macOS">
        <Note>
          The following instructions assume [Homebrew](https://brew.sh) is installed.
        </Note>

        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.
        </Warning>

        For more details on macOS installation, see the [starknet.py installation guide](https://starknetpy.readthedocs.io/en/latest/installation.html).
      </Tab>

      <Tab title="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>

      <Tab title="Windows">
        <Note>
          Windows installation requires MinGW. The recommended way to install is through [chocolatey](https://chocolatey.org/).
        </Note>

        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).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install the Python SDK" titleSize="h2">
    <CodeGroup>
      ```bash pip theme={null}
      pip install chipi-stack
      ```

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

      ```bash uv theme={null}
      uv add chipi-stack
      ```
    </CodeGroup>

    <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`.
    </Note>

    <Accordion title="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
      ```
    </Accordion>
  </Step>

  <Step title="Get your API Keys" titleSize="h2">
    <Warning>
      The Python SDK requires **both** your public key AND secret key for authentication.
    </Warning>

    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`)

    <Info>
      Your secret key is used for backend authentication. Keep it secure and never commit it to version control.
    </Info>
  </Step>

  <Step title="Initialize the SDK" titleSize="h2">
    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",
        )
    )
    ```
  </Step>

  <Step title="Create Your First Wallet" titleSize="h2">
    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
    ```
  </Step>

  <Step title="Make Your First Transfer" titleSize="h2">
    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}")
    ```
  </Step>

  <Step title="Environment Variables (Recommended)" titleSize="h2">
    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.
    </Tip>
  </Step>
</Steps>

## 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`).
</Note>

## Next Steps

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

* **[Create Wallet](/sdk/python/methods/create-wallet)** - Detailed wallet creation guide
* **[Transfer Tokens](/sdk/python/methods/transfer)** - Send USDC and other tokens
* **[Backend API Reference](/sdk/backend/quickstart)** - 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)
</Warning>

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