🌟 About the Pi Devkit SDK

This SDK is built for Pi Network developers who want to manage child wallet addresses derived from a single parent wallet. It helps you create unique deposit addresses for each user—just like exchanges such as OKX,... do when supporting Pi deposits.

Now, with just one base wallet, you can:

• ✅ Create individual child wallets for users or sessions
• 🔁 Listen to incoming payments on each one
• 🔗 Map deposits back to users instantly

No need for multiple wallets—create, track, and manage child addresses seamlessly.

💡 Limitations

For now, using this SDK you can create up to 50 child wallet addresses per base wallet.
If you need more, please contact the development team to request an increased limit.

📚 SDK Reference

Initializes the SDK with your main Pi wallet address.

🔧 new PiDevkit({ baseWallet: string })

• baseWallet: A mainnet pi wallet addres(public key) (e.g., G...)

🛠 createChildWallet(id: string): Promise<{ child_address, child_id }>

Returns a child wallet address for the given id.

• id: A unique identifier (alphanumeric, ≤ 8 UTF-8 bytes) used to generate the sub-address.

✅ Returns

• child_address: A child wallet address (e.g., MBKVMNHHA...ABC1234)
• child_id: A numeric identifier used to generate that child address

💡 Use this to assign a unique deposit address to each user.
Store both child_address and child_id in your database to associate incoming Pi with the correct user.

📡 listen(callback: (payment, childId) => void): void

Begins a live Horizon payment stream to monitor deposits.

• The callback is triggered when any child address receives Pi.
• Use the returned childId to find the corresponding user or session.

🔔 Example: If childId = 0034 receives 15 Pi, you can immediately credit User #0034 in your app.

🧠 Best Practices

• 🔐 Persist both child_id and child_address per user in your backend.
• 🧩 Match childId from the listen() stream to your users to track payments.
• 🪪 Keep IDs unique and short (e.g., john123, piUser01, etc.).

⚙️ Installation

npm i pi-stream-sdk

🧪 Usage

import { PiDevkit } from 'pi-stream-sdk';

const sdk = new PiDevkit({
  baseWallet: 'GBKVMNHHAH7YYLCP...' // Replace with your actual Pii network wallet address(public key)[mainnet]
});

async function run() {
  try {
    // 👤 Step 1: Create a Child Wallet for a User
    const wallet = await sdk.createChildWallet('piUser01');

    console.log('🎉 Child Wallet Created Successfully!');
    console.log('Address:', wallet.child_address);
    console.log('Child ID:', wallet.child_id);

    /**
     * 📌 Developer Note:
     * When a user signs up or registers on your platform,
     * generate a unique child wallet for them (as above),
     * then store both the `child_address` and `child_id` in your database.
     * 
     * This allows you to:
     * - Track incoming deposits uniquely per user
     * - Match future payments to the correct user using the child_id
     */

    // 🔄 Step 2: Start Listening for Payments to the Parent Wallet
    sdk.listen((payment, childId) => {
      console.log('\n💰 Payment Received!');
      console.log('Amount:', payment.amount);
      console.log('Asset:', payment.asset_code || 'XLM');
      console.log('From:', payment.from);
      console.log('Child ID:', childId);
      console.log('Tx Hash:', payment.transaction_hash);

      /**
       * 📌 Developer To-Do:
       * 1. Find the user in your database where stored child_id === childId
       * 2. Credit the user's account balance
       * 3. Optionally emit a socket event or trigger a webhook
       *    to notify your frontend or system in real time.
       * 
       * Example:
       * await creditUserBalance(childId, payment.amount);
       * emitToClient(childId, 'new-payment', payment);
       */
    });

  } catch (error) {
    console.error('❌ Error:', error.message || error);
  }
}

run();

👨‍💻 Author & Contact

Built with 💛 by Soleil
If you're planning to use this SDK in production or need integration support, feel free to reach out directly.

• 🔗 LinkedIn: linkedin.com/in/soleil00
• 💬 Telegram: @soleil6
• 📧 Email: [email protected]
• 🐙 GitHub: github.com/soleil00
• 📱 WhatsApp: +250 782 443 651