Pi Network JS SDK

This package, pi-sdk-js, provides a fully-typed, modern ES module interface to the Pi Network protocol for browser or web-app integrations. It is intended for developers building applications that use the Pi browser extension or the window.Pi global API, and wish to use TypeScript or class-based control. 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.

Quick Start

Install pi-sdk-js package to your app

npm install pi-sdk-js
yarn add pi-sdk-js

Ensure the global Pi SDK (window.Pi) is available in your 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.

Import and use the SDK in your project

import { PiSdkBase, PiUser, PaymentData } from 'pi-sdk-js';

const pi = new PiSdkBase();
await pi.connect();
// Now PiSdkBase.user is available (or listen for onConnection)
pi.createPayment({ amount: 1, memo: "Demo", metadata: { productId: 42 } });

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

Classes and Types

PiSdkBase (Class)

Core interface to Pi Network via the browser SDK. Example usage:

  • connect() – Initiates authentication and session handshake. Should be called on user intent (or mount).
  • createPayment(paymentData) – Begins a payment operation. All server callbacks are handled automatically via Pi’s callback protocol.
  • Static helpers:
    • PiSdkBase.user: PiUser | null – Current user after .connect()
    • PiSdkBase.connected: boolean – Is SDK authenticated/connected?
    • PiSdkBase.accessToken: string | null – Latest session access token (opaque bearer token)

PiUser (Type)

Represents an authenticated Pi user, at minimum { name: string, ... }.

PaymentData (Type)

interface PaymentData {
  amount: number;
  memo: string;
  metadata: Record<string, unknown>;
}

Key Details

  • ESM Only: Use import { ... } from 'pi-sdk-js'; no CommonJS support.
  • Depends on the global window.Pi: The SDK does NOT bundle or polyfill the Pi Network global; you must include the Pi SDK <script> yourself.
  • Callbacks & Events: Payment lifecycle events (approve, complete, cancel, error, incomplete) are managed via static methods—override or listen as needed.
  • No React dependency.

FAQ

How do I mock window.Pi for testing/development?

Assign a stub to window.Pi with mock methods (see your test runner for examples). No real payments or network calls will be made.

What is required to run in Node.js?

This package is intended for browsers; headless use requires you to polyfill window and window.Pi.

Where are user roles or advanced Pi features?

See the complete API in source. Most advanced features are mapped, but basics are exposed as above for typical dApps.

Further Resources

For advanced integration patterns, see the pi-sdk-react package or your framework’s best practices.