Skip to content

API.md

Latest commit

 

History

History
278 lines (238 loc) · 4.87 KB

API.md

File metadata and controls

278 lines (238 loc) · 4.87 KB

Bitchat Heatmap API Documentation

Base URL

http://localhost:3001/api

Endpoints

🗝️ Key Management

Generate New Keys

POST /api/keys/generate

Response:

{
  "privateKey": "hex_private_key",
  "publicKey": "hex_public_key", 
  "nsec": "nsec1...",
  "npub": "npub1..."
}

Decode Keys (npub/nsec/nprofile)

POST /api/keys/decode
Content-Type: application/json

{
  "key": "nsec1... | npub1... | nprofile1..."
}

Response for nsec:

{
  "type": "nsec",
  "privateKey": "hex_private_key",
  "publicKey": "hex_public_key",
  "nsec": "nsec1...",
  "npub": "npub1..."
}

Response for npub:

{
  "type": "npub", 
  "publicKey": "hex_public_key",
  "npub": "npub1..."
}

⚡ Lightning Address

Validate Lightning Address

POST /api/lightning/validate
Content-Type: application/json

{
  "address": "user@domain.com"
}

Response:

{
  "valid": true,
  "address": "user@domain.com",
  "lnurlEndpoint": "https://domain.com/.well-known/lnurlp/user",
  "callback": "https://domain.com/lnurl/pay/callback",
  "minSendable": 1000,
  "maxSendable": 100000000,
  "allowsNostr": true,
  "nostrPubkey": "hex_pubkey",
  "metadata": [...]
}

📍 Events & Geohash

Publish Geohash Event

POST /api/events/publish
Content-Type: application/json

{
  "privateKey": "nsec1... | hex_private_key",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "nickname": "MyNickname",
  "message": "Hello from NYC!",
  "lightningAddress": "user@domain.com" // optional
}

Response:

{
  "success": true,
  "event": { /* full nostr event */ },
  "npub": "npub1...",
  "geohash": "dr5regy7",
  "eventId": "event_hash"
}

Get Heatmap Data

GET /api/heatmap-data

Response:

[
  {
    "geohash": "dr5regy7",
    "intensity": 100,
    "count": 10,
    "lastActivity": 1755875402
  }
]

Get All Activity

GET /api/activity

Response:

[
  {
    "geohash": "dr5regy7",
    "nickname": "TestUser",
    "message": "Hello world!",
    "timestamp": 1755875402,
    "relay": "wss://relay.damus.io",
    "lightningAddress": "user@domain.com",
    "npub": "npub1..."
  }
]

⚡ Lightning Zaps (NIP-57)

Create Zap Request

POST /api/zaps/create-request
Content-Type: application/json

{
  "senderPrivateKey": "nsec1... | hex_private_key",
  "recipientPubkey": "hex_pubkey | npub1...",
  "amount": "21000", // millisats
  "message": "Great post!",
  "eventId": "event_hash_to_zap", // optional
  "relays": ["wss://relay.damus.io"] // optional
}

Response:

{
  "success": true,
  "zapRequest": { /* NIP-57 zap request event */ },
  "senderNpub": "npub1...",
  "recipientNpub": "npub1..."
}

👤 User Profiles

Get User Profile

GET /api/users/{npub}

Response:

{
  "npub": "npub1...",
  "publicKey": "hex_public_key",
  "activities": [
    {
      "geohash": "dr5regy7",
      "nickname": "User",
      "message": "Hello!",
      "timestamp": 1755875402,
      "lightningAddress": "user@domain.com"
    }
  ],
  "totalActivities": 25,
  "lastActivity": 1755875402
}

Usage Examples

JavaScript/Node.js Examples

Generate and use keys:

// Generate new keys
const response = await fetch('/api/keys/generate', { method: 'POST' });
const keys = await response.json();
console.log('Your nsec:', keys.nsec);
console.log('Your npub:', keys.npub);

// Decode existing key
const decodeResponse = await fetch('/api/keys/decode', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: 'nsec1...' })
});
const decoded = await decodeResponse.json();

Publish geohash event:

const publishResponse = await fetch('/api/events/publish', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    privateKey: 'nsec1...',
    latitude: 40.7128,
    longitude: -74.0060,
    nickname: 'MyNickname',
    message: 'Hello from NYC!',
    lightningAddress: 'myuser@domain.com'
  })
});
const result = await publishResponse.json();

Validate Lightning address:

const validateResponse = await fetch('/api/lightning/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ address: 'user@domain.com' })
});
const validation = await validateResponse.json();

Error Responses

All endpoints return appropriate HTTP status codes with error messages:

{
  "error": "Descriptive error message"
}

WebSocket Events

Real-time Updates

Connect to: ws://localhost:3001

Incoming message format:

{
  "type": "new_activity",
  "data": {
    "geohash": "dr5regy7",
    "nickname": "User",
    "message": "Hello!",
    "timestamp": 1755875402,
    "lightningAddress": "user@domain.com",
    "npub": "npub1..."
  }
}