🧰 Piper TypeScript SDK

The official TypeScript SDK for the Piper — a programmable payment streaming primitive on Sui.

@usepiper/sdk provides a clean, strongly-typed interface for building Programmable Transaction Blocks (PTBs) that interact with the Piper Move contracts. With this SDK, you can integrate per‑second continuous streaming and on-demand pay‑per‑use billing into your decentralized application seamlessly.

📦 Installation

Install the Piper SDK and its peer dependency, the Sui TypeScript SDK:

npm install @usepiper/sdk @mysten/sui

🚀 Quick Start

The Piper SDK methods are pure functions that append instructions to a standard Sui Transaction block. This allows you to combine Piper streaming commands with other on-chain interactions perfectly.

1. Initialization

Set the deployed Package ID for Piper once at application startup. By default, it uses the Piper testnet package.

import { Piper } from '@usepiper/sdk';

// Configure the package ID (e.g., for Mainnet or a local deployment)
Piper.setPackageId('0xYOUR_MAINNET_PACKAGE_ID');

2. Integration Snippet (React + dApp Kit)

Here is a functional example of how to create a continuous stream using @mysten/dapp-kit and the Piper SDK in a React component:

import { Transaction } from '@mysten/sui/transactions';
import { useSignAndExecuteTransaction } from '@mysten/dapp-kit';
import { Piper, extractStreamId, calculateFlowRate } from '@usepiper/sdk';

export function CreateStreamButton() {
    const { mutate: signAndExecute } = useSignAndExecuteTransaction();

    const handleCreateStream = () => {
        const tx = new Transaction();
        
        // Let's stream 100 SUI over 30 days
        const totalAmount = 100_000_000_000n; // Assuming SUI has 9 decimals
        const durationSeconds = 30 * 24 * 60 * 60;
        const flowRate = calculateFlowRate(totalAmount, durationSeconds);

        // 1. Create the continuous stream
        const stream = Piper.createContinuousStream(tx, {
            coin: '0xCoinObjectIdToDeposit', // Replace with the actual coin object ID
            coinType: '0x2::sui::SUI',
            flowRate: flowRate,
            recipient: '0xRecipientSuiAddress',
        });

        // 2. Share the stream so it can be autonomously ticked by anyone
        Piper.shareStream(tx, stream, '0x2::sui::SUI');

        // 3. Execute the transaction
        signAndExecute(
            { 
                transaction: tx,
                options: { showEvents: true } // Request events to extract the new stream ID
            }, 
            {
                onSuccess: (result) => {
                    const streamId = extractStreamId(result);
                    console.log('Stream successfully created! ID:', streamId);
                },
                onError: (error) => {
                    console.error('Failed to create stream', error);
                }
            }
        );
    };

    return <button onClick={handleCreateStream}>Start Streaming SUI</button>;
}

📘 Comprehensive Documentation

For detailed guides, API references, and advanced integration patterns (like On-Demand Streams and Revenue Splits), please visit our full documentation:

👉 piper docs

🔐 Security & Architecture

• No Key Custody: The SDK constructs transaction blocks but never asks for or stores private keys. Execution remains entirely under your application's control.
• On-Chain Enforcement: All authorization checks (such as ensuring only creators can revoke streams or configure splits) happen securely on the Sui network.
• Atomic Composability: Because the SDK returns TransactionResult objects, you can safely pipe outputs from other DeFi protocols directly into a Piper stream.

📄 License

MIT © piper