---
title: "Paykit: Decentralized Payment Protocol (Work in Progress)"
---

> ⚠️ **NOTE**: Paykit is currently under active development and is **NOT production-ready**. The protocol and implementation are subject to significant changes. Integration work in Bitkit serves as a testbed for protocol development.

## Overview

Paykit is a payment protocol (work in progress) built on Pubky that aims to enable payment discovery, negotiation, and coordination across multiple payment methods (Bitcoin onchain, Lightning Network, and potentially others).

## Core Concept

Paykit abstracts payment complexity behind a single, static **Pubky public key**. Your public key becomes a universal payment identifier - recipients would discover your available payment methods by querying your [Homeserver](https://pubky.org/explore/pubkycore/homeserver.md)'s public directory at `/pub/paykit.app/v0/`.

This enables applications where users pay directly to profiles, offering an intuitive experience when multiple payment methods are possible.

## Proposed Architecture (Under Development)

### Three-Layer System

1. **Public Directory Layer** (`paykit-lib`)
   - Publish payment methods to Pubky Homeservers
   - Discover methods from other users' public keys
   - Public read access for discovery

2. **Interactive Payment Layer** (`paykit-interactive`)
   - Encrypted channels using **[Pubky Noise](https://pubky.org/explore/technologies/pubky-noise.md)** for private negotiation
   - Receipt exchange and payment coordination
   - End-to-end encrypted communication

3. **Subscription & Automation Layer** (`paykit-subscriptions`)
   - Recurring payment agreements with cryptographic signatures
   - Auto-pay rules with spending limits
   - Payment request system with expiration

## Key Features (In Development)

### Payment Method Discovery
Query any Pubky identity to discover their available payment methods (onchain, Lightning, or custom).

### Encrypted Payment Negotiation
Private channels for payment coordination using **[Pubky Noise](https://pubky.org/explore/technologies/pubky-noise.md)**, a Noise Protocol (IK pattern) implementation built for the Pubky ecosystem. This avoids revealing payment details publicly.

**Pubky Noise** provides:
- End-to-end encrypted communication channels
- Three-step IK handshake for secure connections
- WebSocket and TCP transport support
- Integration with Pubky identity system

### Subscriptions & Recurring Payments
- Cryptographically signed subscription agreements
- Flexible billing frequencies (daily, weekly, monthly, yearly)
- Auto-pay with configurable spending limits
- Replay protection via nonce tracking

### Security Model (Evolving)
**Sealed Blob v1 Encryption**: Sensitive data on public Pubky paths is encrypted:
- Payment requests encrypted to recipient's Noise public key
- Subscription proposals/agreements encrypted per-party
- X25519 ECDH + HKDF-SHA256 + ChaCha20-Poly1305
- Prerequisite: Noise endpoint published at `/pub/paykit.app/v0/noise`

See **[Pubky Noise](https://pubky.org/explore/technologies/pubky-noise.md)** for details on the encrypted channel implementation.

## Current Implementation Status

**Current Version**: 1.0.1 (Work in Progress)
- 🚧 Core library under development
- 🚧 Interactive protocol (WIP)
- 🚧 Subscription system (WIP)
- 🚧 Security model evolving
- 🚧 Protocol specification in flux
- 🚧 Integration testing in Bitkit (iOS/Android)

### Demo Applications
- **CLI**: Command-line reference implementation (WIP)
- **Web**: WebAssembly browser demo
- **iOS Demo**: SwiftUI prototype with Keychain storage
- **Android Demo**: Jetpack Compose prototype

### Testing Integrations
- **Bitkit iOS**: Protocol testing integration (~80 files)
- **Bitkit Android**: Protocol testing integration (~97 files)
- **[Pubky Ring](https://pubky.org/explore/technologies/pubky-ring.md)**: Identity and key management integration

## Potential Use Cases (Future)

### Direct Peer Payments
Pay directly to profiles using Pubky identity without requesting addresses or invoices.

### Content Monetization
- Paywalls for content
- Tip jars for creators
- Micropayments for API access

### Subscription Services
- Magazine subscriptions
- SaaS billing
- Recurring donations

### E-Commerce
- Online store checkouts
- Marketplace payments
- Service bookings

## Technical Details (Subject to Change)

### Storage Paths
- Payment methods: `/pub/paykit.app/v0/{methodId}` (public)
- Noise endpoint: `/pub/paykit.app/v0/noise` (public)
- Payment requests: `/pub/paykit.app/v0/requests/{id}` (encrypted)
- Subscriptions: `/pub/paykit.app/v0/subscriptions/*` (encrypted)

### Supported Payment Methods (Planned)
- **onchain**: Bitcoin on-chain addresses
- **lightning**: BOLT11 invoices, LNURL-pay, Lightning addresses
- **Custom**: Extensible to other methods (under consideration)

### Key Management
- **Ed25519**: Identity signing and verification
- **X25519**: Noise Protocol key exchange
- Derived from same seed via HKDF ([Pubky Ring](https://pubky.org/explore/technologies/pubky-ring.md) integration)

## Relationship to Pubky Core

Paykit is designed as a **layer 2 protocol** on top of Pubky Core:
- Uses Pubky Homeservers for storage
- Leverages Pubky's public-key identity system
- Integrates with Pubky's DHT-based discovery
- Extends Pubky with payment-specific functionality

## Development Status & Roadmap

- ⏳ Protocol specification stabilization
- ⏳ Security audit and hardening
- ⏳ Cross-platform testing and validation
- ⏳ Production deployment planning
- ⏳ Interoperability testing
- ⏳ Performance optimization

## Related Research

**Atomicity Protocol** - Peer-to-peer mutual credit system research exploring trust-based payment routing using Pubky's [Semantic Social Graph](https://pubky.org/explore/concepts/semantic-social-graph.md). Designed as settlement infrastructure for credit issuance and transfer across economic scales from peer-to-peer to institutional banking. Currently in research phase.

## Resources

- **Repository**: [github.com/pubky/paykit-rs](https://github.com/pubky/paykit-rs) (WIP)
- **Additional Documentation**: [paykit-rs/docs/](https://github.com/BitcoinErrorLog/paykit-rs/tree/main/docs) — informal drafts in a downstream working fork; not authoritative
- **Protocol Spec**: [PAYKIT_PROTOCOL_V0.md](https://github.com/BitcoinErrorLog/paykit-rs/blob/main/docs/PAYKIT_PROTOCOL_V0.md) (Draft)
- **Bitkit iOS (WIP Testing)**: [github.com/BitcoinErrorLog/bitkit-ios](https://github.com/BitcoinErrorLog/bitkit-ios)
- **Bitkit Android (WIP Testing)**: [github.com/BitcoinErrorLog/bitkit-android](https://github.com/BitcoinErrorLog/bitkit-android)
- **[Pubky Ring](https://pubky.org/explore/technologies/pubky-ring.md) (Identity Manager)**: See dedicated page for identity and key management

---

**⚠️ Important**: Do not use Paykit for production applications. The protocol is a work in progress and subject to breaking changes.