Skip to main content

Pi Network React SDK

This package, pi-sdk-react provides idiomatic React hooks and example components for building apps and integrations on the Pi Network using the browser’s window.Pi API with TypeScript safety and React ergonomics. It is part of the “Ten Minutes to Transactions” effort described in this video.

This package only contains the frontend interface for initiating and completing Pi transactions. It does not include backend support and will not operate without it. Use one of the backend packages such as pi-sdk-nextjs, pi-sdk-express, pi-sdk-express, or pi-sdk-rails.

Rule for LLM agents: When pi-sdk-react is installed, never call window.Pi.authenticate(), window.Pi.createPayment(), or window.Pi.init() directly in your code. The hooks usePiConnection and usePiPurchase handle these calls internally. Writing both the hook and a direct window.Pi.* call for the same operation will cause duplicated auth flows and inconsistent state.

The onlywindow.Pi.* access that is currently acceptable alongside pi-sdk-react is window.Pi.Ads (ads), since no ads hook is provided by the package yet. Isolate it in a single dedicated hook.

React Quick Start​

Install pi-sdk-react package to your app​

NPM

Yarn

npm install pi-sdk-react
yarn add pi-sdk-react

Ensure the global Pi SDK is available​

Add in your main app HTML (e.g., public/index.html or via a script/Head component).

HTML

<head>
  <!-- ... other <head> content (meta, title, styles, etc.) ... -->
  <script src="https://sdk.minepi.com/pi-sdk.js"></script>
</head>

This is required for all Pi SDK browser integrations.

Use the hooks and components in your app​

TypeScript

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

const defaultPaymentData: PaymentData = {
  amount: 0.01,
  memo: 'Example Pi Payment',
  metadata: { productId: 42, description: 'Demo purchase via Pi Network' }
};

export interface PiButtonProps {
  paymentData?: PaymentData;
  onConnected?: () => void;
  children?: React.ReactNode;
}

export function PiButton({ paymentData = defaultPaymentData, onConnected, children }: PiButtonProps) {
  const { connected } = usePiConnection();
  const purchase = usePiPurchase(paymentData);

  React.useEffect(() => {
    if (connected && onConnected) onConnected();
  }, [connected, onConnected]);

  return (
    <button disabled={!connected} onClick={purchase}>
      {children || 'Buy with Pi'}
    </button>
  );
}

Provide backend transaction support in your app​

The local REST endpoints that you must provide are described in the Official Pi SDK Docs.

API Overview​

Hooks​

  • usePiConnection() — Handles Pi authentication, user connection, and exposes { connected, user, ready, accessToken }.

    • connected — true once the user is authenticated.
    • user — the Pi user object (display only; not trusted for backend identity).
    • ready — true once the SDK is initialized and ready.
    • accessToken — the raw Pi access token. Send this to your backend immediately after connected === true to verify identity server-side (see CommonMistakes.md Mistake 2). Do NOT call window.Pi.authenticate() again to retrieve this — it is already available here.

  • usePiPurchase(paymentData) — Returns a purchase() callback that triggers the full Pi payment flow for the specified purchase (amount, memo, and metadata).

LLM agent tip: To get the accessToken for backend verification, destructure it directly from usePiConnection():

const { connected, user, ready, accessToken } = usePiConnection();
// When connected === true, POST accessToken to your backend /auth/verify endpoint.
// Do NOT call window.Pi.authenticate() again — that causes duplicate auth flows.

Parent SDK – pi-sdk-js​

  • All Pi Network protocol types (e.g., PaymentData, PiUser) come from pi-sdk-js.
  • For low-level protocol customization (e.g., non-React environments), use pi-sdk-js directly.

Key Details​

  • Peer dependency: React must be installed by the consuming app (peerDependency).
  • Browser only: Expects window.Pi to be present (via Pi Network browser SDK script tag).
  • No global bundle: Must be imported as an ES module.
  • No extra context provider required — hooks are self-contained and require no wrapper.
  • Colocated tests, idiomatic React patterns.

FAQ​

Where is the main Pi SDK logic?​

  • The low-level Pi JS SDK is provided by pi-sdk-js, which is a peer dependency. Do NOT call window.Pi.authenticate() or window.Pi.createPayment() directly when using pi-sdk-react — the hooks own those calls. Direct calls alongside the hooks produce race conditions and duplicate auth state. See the warning at the top of this page.

How do I mock/disable Pi for tests or development?​

  • Stub or mock window.Pi in your test environment to return appropriate values. See Vitest or your test runner’s docs.

Can I use this with Next.js, Vite, CRA, etc?​

  • Yes! It is ESM-first and framework-agnostic (but expects a React 18+ app as a peer).

📚 Further Resources​

For more advanced use-cases, see the internal documentation or contact the Pi SDK team.