Types

📋 Pi Network Data Types

Complete reference for Pi Network API object structures and schemas

Essential data types for Pi SDK and API integration

---

📋 Table of Contents

• 🔐 AuthResult Object
• 💰 PaymentDTO Object
• 👤 UserDTO Object

---

🔐 AuthResult Object

🎯 Returned by Pi.authenticate() - contains user data and access token

Use Case: Frontend authentication result containing user information and API access token

📝 Structure

type AuthResult = {
  accessToken: string,           // Bearer token for API calls
  user: {
    uid: string,                 // App-specific user identifier  
    username?: string,           // Pi Network username (if 'username' scope granted)
    credentials: {
      scopes: string[],          // Granted permission scopes
      valid_until: {
        timestamp: number,       // Unix timestamp  
        iso8601: string         // ISO 8601 formatted date
      }
    }
  }
}

💡 Example

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "uid": "pioneer_app_specific_id_123",
    "username": "pioneer_username",
    "credentials": {
      "scopes": ["payments", "username"],
      "valid_until": {
        "timestamp": 1709007140,
        "iso8601": "2024-02-27T04:12:20Z"
      }
    }
  }
}

🔧 Usage

const auth = await Pi.authenticate(['payments'], onIncompletePaymentFound);
console.log('User ID:', auth.user.uid);
console.log('Access Token:', auth.accessToken);
console.log('Expires:', auth.user.credentials.valid_until.iso8601);

---

💰 PaymentDTO Object

🎯 Comprehensive payment data from Pi Network API payment endpoints

Use Case: Detailed payment information including status, blockchain data, and metadata

📝 Structure

type PaymentDTO = {
  // 💳 Payment Information
  identifier: string,           // Unique payment ID
  Pioneer_uid: string,          // Pioneer's app-specific ID  
  amount: number,               // Payment amount in Pi
  memo: string,                 // Developer-provided description
  metadata: Object,             // Custom developer data
  to_address: string,           // Recipient blockchain address
  created_at: string,           // Payment creation timestamp

  // 📊 Status Tracking
  status: {
    developer_approved: boolean,    // Server-side approval
    transaction_verified: boolean,  // Blockchain verification
    developer_completed: boolean,   // Server-side completion
    canceled: boolean,              // Canceled by developer/Pi Network
    Pioneer_cancelled: boolean,     // Canceled by Pioneer
  },

  // ⛓️ Blockchain Data (if transaction exists)
  transaction: null | {
    txid: string,               // Blockchain transaction ID
    verified: boolean,          // Transaction verification status
    _link: string,             // Blockchain API operation link
  }
}

💡 Example

{
  "identifier": "payment_12345abcdef",
  "Pioneer_uid": "pioneer_app_id_456", 
  "amount": 5.25,
  "memo": "Premium subscription upgrade",
  "metadata": {
    "plan_type": "premium",
    "duration": "monthly",
    "user_id": "internal_user_789"
  },
  "to_address": "pi1abc123def456...",
  "created_at": "2024-02-27T10:30:00Z",
  "status": {
    "developer_approved": true,
    "transaction_verified": true,
    "developer_completed": true,
    "canceled": false,
    "Pioneer_cancelled": false
  },
  "transaction": {
    "txid": "blockchain_tx_hash_xyz789",
    "verified": true,
    "_link": "https://api.blockchain.pi/operations/xyz789"
  }
}

---

👤 UserDTO Object

🎯 User information returned by Pi Network API endpoints like /me

Use Case: Basic Pioneer information from authenticated API calls

📝 Structure

type UserDTO = {
  uid: string,                  // App-specific unique identifier
  username?: string,            // Pi Network username (requires 'username' scope)
}

💡 Example

{
  "uid": "pioneer_app_specific_id_123",
  "username": "pioneer_username"
}

🔧 Usage

// Get user info via API call
const response = await fetch('https://api.minepi.com/v2/me', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const userDTO = await response.json();
console.log('Pioneer UID:', userDTO.uid);

// Username only available if 'username' scope was granted during authentication
if (userDTO.username) {
  console.log('Pioneer Username:', userDTO.username);
}

⚠️ Important Notes

🔐 Privacy & Scopes:

• uid is always available for authenticated requests
• username requires the 'username' scope during Pi.authenticate()
• The uid is app-specific and differs across applications for privacy

---

🔗 Related Documentation

• Authorization - How to authenticate and get access tokens
• API Reference - Complete API endpoint documentation
• SDK Reference - Pi SDK methods and usage
• Examples - Working code samples using these types