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

> Discover where to find BitChat API documentation. Learn how to integrate with the Nostr protocol directly through this Swift implementation. Get started with decentralized communication.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: api-reference
- Published: 2026-08-01

---

**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`](https://github.com/permissionlesstech/bitchat/blob/main/ARCHITECTURE_V2.md) | Internal API layers, intent-based mutation model, and how the UI communicates with the sync engine | [View on GitHub](https://github.com/permissionlesstech/bitchat/blob/main/docs/ARCHITECTURE_V2.md) |
| [`CONVERSATION-STORE-DESIGN.md`](https://github.com/permissionlesstech/bitchat/blob/main/CONVERSATION-STORE-DESIGN.md) | Intent-based conversation store API implementation details | [View on GitHub](https://github.com/permissionlesstech/bitchat/blob/main/docs/CONVERSATION-STORE-DESIGN.md) |
| [`README.md`](https://github.com/permissionlesstech/bitchat/blob/main/README.md) | Project overview, supported platforms, and quick start guide | [View on GitHub](https://github.com/permissionlesstech/bitchat/blob/main/README.md) |
| [`privacy-assessment.md`](https://github.com/permissionlesstech/bitchat/blob/main/privacy-assessment.md) | Required-reason APIs and privacy manifest documentation | [View on GitHub](https://github.com/permissionlesstech/bitchat/blob/main/docs/privacy-assessment.md) |

### Core API Implementation Files

| File Path | Purpose |
|-----------|---------|
| [`bitchat/Services/NostrTransport.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/NostrTransport.swift) | Core Nostr client for publish, subscribe, and queue management operations |
| [`bitchat/Nostr/NostrRelayURL.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrRelayURL.swift) | URL parsing and validation for Nostr relay endpoints |
| [`bitchat/Nostr/NostrRelaySettings.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrRelaySettings.swift) | Per-relay configuration including read/write flags and Tor routing |
| [`bitchat/Nostr/GeoRelayDirectory.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/GeoRelayDirectory.swift) | CSV-based geographic relay lookup and nearest-relay selection |
| [`bitchat/Services/MeshTopologyTracker.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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

```swift
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

```swift
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

```swift
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

```swift
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`](https://github.com/permissionlesstech/bitchat/blob/main/docs/ARCHITECTURE_V2.md) for the intent-based mutation model and storage layering
2. **Transport layer**: Study [`bitchat/Services/NostrTransport.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/NostrTransport.swift) for publish/subscribe implementation
3. **Relay management**: Examine [`bitchat/Nostr/NostrRelaySettings.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrRelaySettings.swift) and [`bitchat/Nostr/GeoRelayDirectory.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/GeoRelayDirectory.swift) for network topology control

### Key Method Signatures

From [`NostrTransport.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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.