Where to Find BitChat API Documentation: A Complete Guide to Nostr Protocol Integration

BitChat does not provide a traditional REST or GraphQL API—its entire public interface is the Nostr protocol, a decentralized JSON-based gossip network implemented in Swift under the bitchat/Nostr package.

All API-level operations in BitChat, including publishing notes, reading timelines, managing relays, and handling geohash-based routing, are exposed through this Nostr-based architecture. This guide maps out exactly where to find documentation and how to use the core interfaces.

---

BitChat API Documentation Locations

The project organizes its documentation across design documents, inline code comments, and Swift source files. Here are the primary resources for understanding how the API works.

High-Level Architecture Documents

Document	What It Covers	Direct Link
ARCHITECTURE_V2.md	Internal API layers, intent-based mutation model, and how the UI communicates with the sync engine	View on GitHub
CONVERSATION-STORE-DESIGN.md	Intent-based conversation store API implementation details	View on GitHub
README.md	Project overview, supported platforms, and quick start guide	View on GitHub
privacy-assessment.md	Required-reason APIs and privacy manifest documentation	View on GitHub

Core API Implementation Files

File Path	Purpose
bitchat/Services/NostrTransport.swift	Core Nostr client for publish, subscribe, and queue management operations
bitchat/Nostr/NostrRelayURL.swift	URL parsing and validation for Nostr relay endpoints
bitchat/Nostr/NostrRelaySettings.swift	Per-relay configuration including read/write flags and Tor routing
bitchat/Nostr/GeoRelayDirectory.swift	CSV-based geographic relay lookup and nearest-relay selection
bitchat/Services/MeshTopologyTracker.swift	Internal mesh-network topology for sync layer operations

---

Understanding BitChat's Nostr-Based API

Unlike conventional chat applications, BitChat's API is protocol-native rather than service-native. This means you interact directly with Nostr relays using signed events rather than calling HTTP endpoints.

What Is the Nostr Protocol?

Nostr ("Notes and Other Stuff Transmitted by Relays") is a decentralized protocol where:

• Identity is based on public/private key pairs
• All data is packaged as NostrEvent objects with cryptographic signatures
• Relays store and forward events without requiring accounts
• Clients subscribe to event filters to receive real-time updates

BitChat implements this protocol in Swift, adding geohash-based relay selection and mesh networking capabilities.

Key API Components

1. ** NostrTransport** — The primary interface for all network operations
2. NostrIdentity — Key generation and event signing
3. GeoRelayDirectory — Geographic optimization for relay selection
4. NostrRelaySettings — Fine-grained relay behavior control

---

BitChat API Code Examples

The following Swift snippets demonstrate common API interactions. All examples are derived from the permissionlesstech/bitchat source code and can be run in a Swift Playground or test target with the BitChat package imported.

Publishing a Nostr Note

import BitChat
import BitFoundation

// Generate a fresh Nostr identity (stores keys in the keychain)
let myIdentity = try NostrIdentity.generate()

// Build a simple text event
let event = try NostrEvent(
    kind: .textNote,
    content: "Hello, Nostr from BitChat!",
    createdAt: Date()
)

// Sign the event with our identity
let signed = try myIdentity.sign(event)

// Get a transport (uses the default relay list)
let transport = NostrTransport(
    keychain: .default,
    idBridge: NostrIdentityBridge(keychain: .default)
)

// Queue it for delivery
transport.publish(event: signed) { result in
    switch result {
    case .success:
        print("✅ Event queued")
    case .failure(let err):
        print("❌ Failed: \(err)")
    }
}

This example shows the complete publish flow: identity creation, event construction, cryptographic signing, and asynchronous delivery queueing via NostrTransport.publish(event:completion:).

Fetching the Nearest Relay by Geohash

import BitChat

let directory = GeoRelayDirectory()
let geohash = "u4pruydqqvj"  // example geohash

if let relay = try? directory.relay(for: geohash) {
    print("Nearest relay is: \(relay.url)")
} else {
    print("No relay found for this geohash")
}

The GeoRelayDirectory.relay(for:) method implements location-aware relay selection, loading relay coordinates from a bundled CSV and computing proximity to optimize connection latency.

Subscribing to a Timeline

let transport = NostrTransport(
    keychain: .default,
    idBridge: NostrIdentityBridge(keychain: .default)
)

let relayURL = URL(string: "wss://relay.nostr.example")!

transport.subscribe(
    to: .textNote,
    relay: relayURL,
    since: nil,
    limit: 20
) { event in
    print("🔔 New note from \(event.pubkey): \(event.content)")
}

NostrTransport.subscribe(to:relay:since:limit:handler:) establishes a WebSocket connection and streams matching events through the provided closure.

Configuring Tor-Enabled Relays

var settings = NostrRelaySettings(
    url: URL(string: "wss://relay.tor.example")!
)

settings.useTor = true   // Route traffic via built-in Tor proxy
settings.read = true
settings.write = true

let manager = RelayManager.shared
manager.update(settings: settings)

NostrRelaySettings provides granular control over relay behavior, including onion routing support for privacy-critical deployments.

---

Reading the Source for API Details

Since BitChat's API surface is implemented directly in Swift rather than exposed through OpenAPI or similar specifications, the source code serves as the authoritative documentation.

Where to Start

1. Architecture overview: Read docs/ARCHITECTURE_V2.md for the intent-based mutation model and storage layering
2. Transport layer: Study bitchat/Services/NostrTransport.swift for publish/subscribe implementation
3. Relay management: Examine bitchat/Nostr/NostrRelaySettings.swift and bitchat/Nostr/GeoRelayDirectory.swift for network topology control

Key Method Signatures

From NostrTransport.swift:

• publish(event:completion:) — Queues a signed event for relay transmission
• subscribe(to:relay:since:limit:handler:) — Establishes filtered event subscription
• connect(to:) — Manages WebSocket connection lifecycle

From GeoRelayDirectory.swift:

• relay(for:) — Returns optimal relay for a given geohash string

From NostrIdentity:

• generate() — Creates new keypair with secure keychain storage
• sign(_:) — Cryptographically signs an event for relay acceptance

---

Summary

• BitChat has no traditional REST API — all operations use the Nostr protocol
• Documentation is distributed across docs/ markdown files and Swift source in bitchat/Nostr/
• Core API entry point is NostrTransport for network operations
• GeoRelayDirectory provides geohash-optimized relay selection
• Design documents in docs/ARCHITECTURE_V2.md explain the intent-based mutation model
• All code examples above run against the permissionlesstech/bitchat repository with standard Swift Package Manager import

---

Frequently Asked Questions

Does BitChat have a REST API I can call from Python or JavaScript?

No. According to the permissionlesstech/bitchat source code, there is no HTTP-based API. BitChat communicates exclusively through Nostr protocol messages over WebSocket connections to relays. For Python or JavaScript integration, you would use a Nostr client library (such as nostr-tools for JavaScript or nostr for Python) rather than calling BitChat directly.

How do I authenticate with the BitChat API?

Authentication is keypair-based, not token-based. In NostrIdentity.generate(), BitChat creates an secp256k1 keypair and stores it in the system keychain. Every event you publish must be signed with this identity using NostrIdentity.sign(_:). Relays accept any properly signed event without additional authentication.

Can I self-host BitChat's API server?

BitChat is a client-only application with no server component to host. The "API" is the Nostr network itself. You can run your own Nostr relay (using implementations like strfry or nostr-rs-relay) and configure BitChat to connect to it via NostrRelaySettings, but the application architecture has no centralized server.

Where are API rate limits documented?

Rate limits are relay-specific, not defined by BitChat. Each Nostr relay implements its own policies for event acceptance, connection limits, and subscription filters. BitChat's NostrTransport handles backoff and reconnection, but you must consult individual relay documentation for their specific limits. The GeoRelayDirectory can help distribute load across multiple relays.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}