pubky · gcomte · Jun 2, 2026 · May 27, 2026 · Jun 1, 2026 · Jun 1, 2026
diff --git a/src/content/docs/explore/pubky-apps/indexing-and-aggregation/web-server.md b/src/content/docs/explore/pubky-apps/indexing-and-aggregation/web-server.md
@@ -9,14 +9,7 @@ The system comprises a suite of **backend services** that orchestrate the inte
 - __Feeds__ - Curated views of aggregated data presented to users. Can include timelines, [tags](/explore/pubky-apps/reference-app/features/tags/), [profiles](/explore/pubky-apps/reference-app/features/profiles/), etc.
 - __Search__ - Services that index aggregated data and enable full text/attribute searches.
 - __Identity__ - It provides single sign-on through self-sovereign credentials. 
-- **[Payments](Paykit.md)** - Payment discovery and coordination service using Paykit protocol (work in progress). Planned capabilities include:
-  - Public directory API for payment method discovery
-  - Encrypted storage for payment requests and subscriptions
-  - Push notification relay for incoming payment notifications
-  - Receipt storage and verification
-  - Subscription management coordination
-
-  ⚠️ **Note**: Paykit is not production-ready and subject to significant changes.
+- **[Payments](/explore/technologies/paykit/)** - Payment method discovery and coordination using the Paykit protocol.
 
 ### Architecture
 

diff --git a/src/content/docs/explore/pubky-apps/reference-app/introduction.md b/src/content/docs/explore/pubky-apps/reference-app/introduction.md
@@ -26,17 +26,6 @@ Using the library analogy, the Pubky Client is like a personalized research assi
 
 - Pubky client uses the open [Pubky Core](/explore/pubkycore/introduction/) for nearly all features, allowing users to avoid censorship by choosing self-hosting or alternate hosts without losing followers or integrity. 
 
-- Pubky also includes support for **[Paykit](/explore/technologies/paykit/)**, an open payment protocol (work in progress) for coordinating payments among peers supporting various methods. This allows users to potentially create payment flows for familiar experiences.
-
-⚠️ **Note**: Paykit is currently **work in progress** and not production-ready. Integrations in Bitkit (iOS and Android) serve as testbeds for protocol development, not production features. The protocol specification, security model, and implementation are subject to significant changes.
-
-**Planned Paykit Features** (WIP):
-- **Pay to profiles**: Send payments to Pubky identities without requesting addresses/invoices
-- **Method discovery**: Discover which payment methods someone accepts (onchain, Lightning)
-- **Encrypted negotiation**: Private [Pubky Noise](/explore/technologies/pubky-noise/) channels for secure payment coordination
-- **Subscriptions**: Cryptographically signed recurring payment agreements
-- **Zero custody**: Users always control their keys and funds
-
-Future Pubky app versions may leverage Paykit once it reaches production readiness to enable peer-to-peer data markets, creator monetization, and value exchange throughout the ecosystem.
+Future pubky.app versions may leverage [Paykit](/explore/technologies/paykit/) once infrastructure reaches production readiness to support creator monetization.
 
 - Communities facilitate moderation and discovery around shared interests.
diff --git a/src/content/docs/explore/technologies/paykit.md b/src/content/docs/explore/technologies/paykit.md
@@ -6,151 +6,62 @@ title: "Paykit: Decentralized Payment Protocol (Work in Progress)"
 
 ## 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).
+Paykit is a payment protocol built on Pubky for payment discovery and coordination across multiple payment methods, including Bitcoin on-chain and Lightning. Apps can start from a Pubky public key, discover public payment details, privately share payment details over encrypted channels, and let payers retrieve encrypted receipts.
 
 ## 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](/explore/pubkycore/homeserver/)'s public directory at `/pub/paykit.app/v0/`.
+Paykit uses a payee's Pubky public key as the stable starting point for payment discovery. Instead of asking for an address or invoice out of band, an app can look up the published payment details on a [Homeserver](/explore/pubkycore/homeserver/) under `/pub/paykit/v0/{payment_endpoint_identifier}`.
 
-This enables applications where users pay directly to profiles, offering an intuitive experience when multiple payment methods are possible.
+This enables applications where users can pay directly to profiles while still letting the integrating wallet or payment processor decide which payment rail to use.
 
-## Proposed Architecture (Under Development)
+## How Paykit Works
 
-### Three-Layer System
+Paykit uses Pubky Homeservers for payment data and [Pubky Noise](/explore/technologies/pubky-noise/) for private Paykit messages.
 
-1. **Public Directory Layer** (`paykit-lib`)
-   - Publish payment methods to Pubky Homeservers
-   - Discover methods from other users' public keys
-   - Public read access for discovery
+### Public Payment Details
 
-2. **Interactive Payment Layer** (`paykit-interactive`)
-   - Encrypted channels using **[Pubky Noise](/explore/technologies/pubky-noise/)** for private negotiation
-   - Receipt exchange and payment coordination
-   - End-to-end encrypted communication
+Payees publish payment details to their Homeserver. Anyone who knows the payee's Pubky public key can discover those public details.
 
-3. **Subscription & Automation Layer** (`paykit-subscriptions`)
-   - Recurring payment agreements with cryptographic signatures
-   - Auto-pay rules with spending limits
-   - Payment request system with expiration
+### Private Payment Coordination
 
-## Key Features (In Development)
+When a payment should not rely on public payment details, a payee can share a private payment list with a specific counterparty over an encrypted channel. Private payment details are exchanged as Private Payment Envelopes.
 
-### Payment Method Discovery
-Query any Pubky identity to discover their available payment methods (onchain, Lightning, or custom).
+### Encrypted Receipts
 
-### Encrypted Payment Negotiation
-Private channels for payment coordination using **[Pubky Noise](/explore/technologies/pubky-noise/)**, a Noise Protocol (IK pattern) implementation built for the Pubky ecosystem. This avoids revealing payment details publicly.
+Paykit receipts are encrypted before storage. The payee stores the encrypted receipt on their Homeserver and sends the payer the access details needed to retrieve and decrypt it.
 
-**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
+## Payment Methods
 
-### 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
+Paykit helps apps discover the payment details a payee publishes, but actual payment method support depends on the integrating wallet or payment application. The initial examples focus on Bitcoin on-chain and Lightning, while the endpoint identifier format is designed to support other payment methods over time. See the [Paykit Payment Endpoint Identifier Specification](https://github.com/pubky/paykit-rs/blob/master/specs/payment-endpoint-identifier.md).
 
-### 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`
+## What Paykit Does Not Do
 
-See **[Pubky Noise](/explore/technologies/pubky-noise/)** for details on the encrypted channel implementation.
+Paykit does not move funds, custody keys, choose a payment rail, or implement wallet logic. Payment method selection, payment execution and key management remain the responsibility of the integrating wallet, payment processor, or application.
 
-## Current Implementation Status
+## Current 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)
+The current implementation includes public payment lists, private payment envelopes, encrypted links, and encrypted receipt access. [Bitkit](https://bitkit.to/) integrations on iOS and Android are used as protocol testbeds before stabilization.
 
-### Demo Applications
-- **CLI**: Command-line reference implementation (WIP)
-- **Web**: WebAssembly browser demo
-- **iOS Demo**: SwiftUI prototype with Keychain storage
-- **Android Demo**: Jetpack Compose prototype
+## Potential Use Cases
 
-### Testing Integrations
-- **Bitkit iOS**: Protocol testing integration (~80 files)
-- **Bitkit Android**: Protocol testing integration (~97 files)
-- **[Pubky Ring](/explore/technologies/pubky-ring/)**: Identity and key management integration
+### Direct Profile Payments
 
-## Potential Use Cases (Future)
+Pay directly to profiles using Pubky identity without asking for an address or invoice out of band.
 
-### Direct Peer Payments
-Pay directly to profiles using Pubky identity without requesting addresses or invoices.
+### Creator Monetization
 
-### Content Monetization
-- Paywalls for content
-- Tip jars for creators
-- Micropayments for API access
+Use public or private payment details for tips, paid content, or creator support.
 
-### Subscription Services
-- Magazine subscriptions
-- SaaS billing
-- Recurring donations
+### Commerce
 
-### 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](/explore/technologies/pubky-ring/) 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
+Applications could use Paykit discovery around store checkouts, service bookings, or marketplace payments while keeping actual payment execution in the wallet or payment processor.
 
 ## Related Research
 
 **Atomicity Protocol** - Peer-to-peer mutual credit system research exploring trust-based payment routing using Pubky's [Semantic Social Graph](/explore/concepts/semantic-social-graph/). 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](/explore/technologies/pubky-ring/) (Identity Manager)**: See dedicated page for identity and key management
-
----
+## References
 
-**⚠️ Important**: Do not use Paykit for production applications. The protocol is a work in progress and subject to breaking changes.
+- **Repository and protocol overview**: [github.com/pubky/paykit-rs](https://github.com/pubky/paykit-rs)
+- **Library usage and API details**: [paykit-lib README](https://github.com/pubky/paykit-rs/blob/master/paykit-lib/README.md)
+- **Paykit Payment Endpoint Identifier Specification**: [payment-endpoint-identifier.md](https://github.com/pubky/paykit-rs/blob/master/specs/payment-endpoint-identifier.md)
diff --git a/src/content/docs/faq.md b/src/content/docs/faq.md
@@ -211,19 +211,17 @@ Via CAPTCHAs, rate-limits, invites, and graph distance rules.
 <a id="q37"></a>
 ### Q37. How does Paykit fit in?
 
-Paykit is a **payment protocol (work in progress)** built on Pubky that aims to enable payment discovery and coordination across multiple methods (Bitcoin, Lightning, etc.). See [Client Features](/explore/pubky-apps/reference-app/introduction/) for the full feature list.
-
-⚠️ **Note**: Paykit is NOT production-ready and the protocol is subject to significant changes.
+Paykit adds payment method discovery and coordination to Pubky identities. See [Paykit](/explore/technologies/paykit/) for the full overview.
 
 <a id="q38"></a>
 ### Q38. Is Paykit ready for use?
 
-No. Paykit is currently a work in progress under active development. The protocol specification, security model, and implementation are all subject to breaking changes. Do not use it for production applications.
+No. Paykit is still a work in progress and not for production use. See [Paykit](/explore/technologies/paykit/) and the [Paykit repository](https://github.com/pubky/paykit-rs) for project status and docs.
 
 <a id="q39"></a>
 ### Q39. What payment methods will Paykit support?
 
-The initial focus is on Bitcoin on-chain and Lightning Network. The protocol is designed to be extensible to other methods (Liquid, Fedimint, ecash, etc.), but these are not yet implemented or specified.
+Paykit helps apps discover the payment details a payee publishes, but actual rail support depends on the integrating wallet or payment application. The initial examples focus on Bitcoin on-chain and Lightning, while the endpoint identifier format is designed to support other payment methods over time. See the [payment endpoint identifier spec](https://github.com/pubky/paykit-rs/blob/master/specs/payment-endpoint-identifier.md).
 
 <a id="q40"></a>
 ### Q40. Where is Paykit being tested?
@@ -233,7 +231,7 @@ Paykit is being integrated into Bitkit (iOS and Android) to validate the protoco
 <a id="q41"></a>
 ### Q41. When will Paykit be production-ready?
 
-There is no set timeline. Significant work remains on protocol stabilization, security auditing, cross-platform testing, and interoperability validation before Paykit can be recommended for production use.
+There is no set timeline. Protocol stabilization, security auditing, cross-platform testing, and interoperability validation still need more work.
 
 <a id="q42"></a>
 ### Q42. Can Pubky do everything Nostr can?

diff --git a/src/content/docs/getting-started.md b/src/content/docs/getting-started.md
@@ -170,9 +170,10 @@ If building a social app, leverage [Pubky Nexus](/explore/pubky-apps/indexing-an
 **Add Payments (WIP):**
 
 [Paykit](/explore/technologies/paykit/) protocol (work in progress) will enable:
-- Payment discovery via public keys
-- Bitcoin/Lightning integration
-- Subscriptions and monetization
+- Payment discovery via Pubky public keys
+- Public or private payment details for Bitcoin onchain, Lightning, and other rails
+- Encrypted receipt access for payers
+- Subscriptions and payment request workflows
 
 **Add Encryption (WIP):**
 

diff --git a/src/content/docs/glossary.md b/src/content/docs/glossary.md
@@ -75,7 +75,7 @@ Noise Protocol implementation for encrypted peer-to-peer communication in the Pu
 ## P
 
 **[Paykit](/explore/technologies/paykit/)**
-Payment protocol built on Pubky for payment discovery and coordination across Bitcoin, Lightning, and other methods (work in progress).
+Payment protocol built on Pubky for payment discovery and coordination across multiple payment methods, including Bitcoin on-chain and Lightning (work in progress).
 
 **[PKARR](/explore/pubkycore/pkarr/introduction/)** (Public Key Addressable Resource Records)
 Self-issued, signed DNS-like records published to the Mainline DHT. Each record is tied to a public key and contains information like Homeserver locations.

diff --git a/src/content/docs/overview.md b/src/content/docs/overview.md
@@ -107,11 +107,11 @@ Understand the fundamental ideas behind Pubky:
 
 ## Work in Progress: Payment Protocol
 
-⚠️ **[Paykit](/explore/technologies/paykit/)** is a payment protocol (work in progress) built on Pubky for payment discovery and coordination. Not production-ready.
+⚠️ **[Paykit](/explore/technologies/paykit/)** is a work-in-progress payment protocol built on Pubky for payment discovery and coordination. Not production-ready.
 
-- [Paykit Overview](/explore/technologies/paykit/) - Current state and architecture (WIP)
-- [Repository](https://github.com/pubky/paykit-rs) - WIP
-- [Additional Documentation](https://github.com/BitcoinErrorLog/paykit-rs/tree/main/docs) - Informal drafts in a downstream working fork; not authoritative
+- [Paykit Overview](/explore/technologies/paykit/) - Current state and architecture
+- [Repository](https://github.com/pubky/paykit-rs) - Project status and docs
+- [Payment Endpoint Identifier Spec](https://github.com/pubky/paykit-rs/blob/master/specs/payment-endpoint-identifier.md) - Identifier convention
 
 ## Work in Progress: Encrypted Communication