POWR/docs/technical/nostr/nostr_band_integration.md

Nostr.band API Integration

Last Updated: 2025-03-28
Status: Active
Related To: Profile Stats, NostrBandService, useProfileStats

Purpose

This document outlines the integration of the nostr.band API in the POWR app for retrieving profile statistics and other Nostr-related data.

nostr.band API Overview

Nostr.band is a Nostr search engine and indexer that provides a comprehensive API for accessing aggregated statistics and data from the Nostr network. The API offers various endpoints for querying profile stats, events, and other Nostr-related information.

API Base URL

https://api.nostr.band

Authentication

The nostr.band API (as of March 2025) does not require authentication for basic profile statistics. It uses simple REST endpoints with path parameters.

Available Endpoints

Profile Statistics

Retrieve follower and following counts for a specific pubkey:

GET /v0/stats/profile/{pubkey}

Where {pubkey} is the hex-format Nostr public key.

Response Format

{
  "stats": {
    "[pubkey]": {
      "pubkey": "[pubkey]",
      "followers_pubkey_count": 123,
      "pub_following_pubkey_count": 456,
      // Other stats may be available
    }
  }
}

Implementation in POWR

Our implementation consists of two main components:

1. NostrBandService: A service class that handles API communication
2. useProfileStats: A React hook that provides the stats to components

NostrBandService

Located at lib/services/NostrBandService.ts, this service:

• Provides methods to interact with the nostr.band API
• Handles error cases and edge conditions
• Converts between npub and hex formats as needed

// Example usage:
import { nostrBandService } from '@/lib/services/NostrBandService';

// Fetch profile stats
const stats = await nostrBandService.fetchProfileStats('npub1...');
console.log(stats.followersCount); // Number of followers
console.log(stats.followingCount); // Number of accounts being followed

useProfileStats Hook

Located at lib/hooks/useProfileStats.ts, this hook:

• Wraps the NostrBandService in a React hook
• Provides loading/error states
• Supports automatic refresh intervals
• Falls back to current user's pubkey if none provided

// Example usage:
import { useProfileStats } from '@/lib/hooks/useProfileStats';

function MyComponent() {
  const { 
    followersCount, 
    followingCount, 
    isLoading, 
    error 
  } = useProfileStats({
    pubkey: 'npub1...', // Optional: defaults to current user
    refreshInterval: 60000 * 15 // Optional: refreshes every 15 minutes
  });

  if (isLoading) return <LoadingIndicator />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <View>
      <Text>Followers: {followersCount}</Text>
      <Text>Following: {followingCount}</Text>
    </View>
  );
}

How to Use the nostr.band API in POWR

Step 1: Import the Required Dependencies

import { useProfileStats } from '@/lib/hooks/useProfileStats';
// OR for direct API access:
import { nostrBandService } from '@/lib/services/NostrBandService';

Step 2: Use the Hook in Your Component

// With the hook (recommended for React components)
function ProfileComponent({ pubkey }) {
  const { 
    followersCount, 
    followingCount, 
    isLoading,
    refresh, // Function to manually refresh stats
    lastRefreshed // Timestamp of last refresh
  } = useProfileStats({
    pubkey,
    refreshInterval: 300000 // 5 minutes in milliseconds (optional)
  });

  // Now use the stats in your UI
}

Step 3: Handle Loading and Error States

if (isLoading) {
  return <Text>Loading stats...</Text>;
}

if (error) {
  return <Text>Error loading stats: {error.message}</Text>;
}

Step 4: Display the Data

<View className="flex-row mb-2">
  <Text>
    <Text className="font-bold">{followingCount.toLocaleString()}</Text>
    <Text className="text-muted-foreground"> following</Text>
  </Text>
  
  <Text className="ml-4">
    <Text className="font-bold">{followersCount.toLocaleString()}</Text>
    <Text className="text-muted-foreground"> followers</Text>
  </Text>
</View>

API Rate Limiting

As of March 2025, the nostr.band API has the following rate limits:

• 60 requests per minute per IP address
• 1000 requests per day per IP address

To respect these limits:

• Implement reasonable refresh intervals (e.g., 15 minutes)
• Add caching mechanisms for frequently requested data
• Use error handling to gracefully degrade when rate limits are reached

Error Handling

The service handles common error cases:

1. Invalid npub format
2. Network errors
3. API errors (non-200 responses)
4. Missing data in response

In all error cases, the service will:

• Log the error to the console
• Return a structured error object
• Set appropriate loading/error states

Future Enhancements

Potential future enhancements for the nostr.band integration:

1. Add support for additional endpoints (search, events, etc.)
2. Implement caching to reduce API calls
3. Add offline support with cached data
4. Expand UI to show additional statistics

References

• Nostr.band API Documentation (unofficial, as of 2025-03-28)
• Nostr.band Website
• NostrBandService.ts - Service implementation
• useProfileStats.ts - Hook implementation