Pi SDK Django

The pi-sdk-django package handles the server-side Pi Network payment lifecycle, authentication helpers, and ad reward verification for Django apps. It pairs with pi-sdk-react (frontend) to give you a complete, idiomatic Pi integration.

Required packages

Layer Package Install
Backend (Django) pi-sdk-django pip install pi-sdk-django
Frontend (React) pi-sdk-react npm install pi-sdk-react

Do not substitute pi-sdk-django with raw requests / httpx calls to the Pi Platform API. The managed package handles payment lifecycle state, error recovery, and incomplete-payment resolution that are easy to miss when calling the API directly.

This guide demonstrates how to integrate the Pi SDK into a Django app. This example shows how to initialize the Pi SDK, authenticate a Pioneer, and create a payment request inside a Pi app.

The pi-sdk-django package is part of the “Ten Minutes to Transactions” effort described in this video.

If you, or your GenAI agent, are planning to use the Django for your app, it is highly suggested that you use this package rather than implement transaction processing by hand with the core Pi SDK. The three way handshake between client, server, and the Pi servers required is provded for you.

Note: Pi SDK authentication and payment features require the application to run inside the Pi Browser.

Django Quick Start

Register your application with Pi Network

While this process is covered in the Getting Started Guide, here is a brief reminder of the steps you need to take. Application registration is also discussed in the video.

  • Open your Pi Mining app.
  • Click the hamburger (☰).
  • Select “Pi Utilities”.
  • Click the “Develop” icon followed by the “New App” icon.
  • Provide name and description of your app and submit.
  • Then click the “Configuration” icon.
  • Set the app URL to something valid, but does not necessarily exist.
  • Set the development URL to be http://localhost:3000. The actual port is between you and your development server.
  • Submit your changes.
  • Get your API key.
  • Register a wallet for your app.

1. Add pi-sdk-django to your requirements

pi-sdk-django is required for the backend. Add it to requirements.txt:

pi-sdk-django>=<version>

Then install:

pip install -r requirements.txt

Common mistake: Using requests or httpx to call https://api.minepi.com/v2/ directly instead of installing pi-sdk-django. This bypasses the official SDK and will cause your implementation to fail the Pi integration review. See Common Mistakes.

pip install pi-sdk-django

2. Run the Pi component and API scaffolder

pi-sdk-django-install

This will generate:

  • routes/pi_payment/ directory with individual route handlers
  • routes/pi_payment/index.ts - Router that exports all routes
  • app.example.ts - Example Django app setup

3. Load the Pi SDK script and call Pi.init() (Frontend)

Add the Pi SDK script tag to your HTML before any Pi SDK calls, and call Pi.init() before React mounts. Without this, window.Pi is undefined and all SDK calls will throw. See Common Mistakes — Mistake 1.

<!-- index.html -->
<head>
  <!-- REQUIRED: load Pi SDK before any Pi SDK calls -->
  <script src="https://sdk.minepi.com/pi-sdk.js"></script>
</head>

// main.tsx — before ReactDOM.createRoot(...)
window.Pi.init({ version: '2.0', sandbox: true }); // sandbox: false in production

The CDN script is needed in sandbox/desktop environments. Apps running inside the Pi Browser receive window.Pi natively.

4. Frontend Integration

Use pi-sdk-react hooks on your frontend. Never call window.Pi.authenticate() or window.Pi.createPayment() directly — the hooks own those calls.

import { usePiConnection, usePiPurchase } from 'pi-sdk-react';

// Auth — accessToken comes directly from the hook (not window.PiSdkBase)
const { connected, accessToken } = usePiConnection();

// Payment — hook handles approve + complete internally
const purchase = usePiPurchase({ amount: 1, memo: 'Unlock feature', metadata: {} });

For more detail see pi-sdk-react.

5. Set Environment Variables

PI_API_KEY=your_pi_api_key_here

API Endpoints

pi-sdk-django mounts the following endpoints (matching usePiPurchase defaults):

  • POST /pi_payment/approve — Phase I: approve with Pi Platform API
  • POST /pi_payment/complete — Phase III: complete and deliver feature
  • POST /pi_payment/cancel — cancel a payment
  • POST /pi_payment/incomplete — resolve stuck payments