Portal

Portal is the identity and payment layer for Bitcoin-native applications — no accounts, no KYC, no payment processor.

Users interact through the Portal mobile app using their Nostr identity. You run a single Docker container and talk to it with our SDK.

---

How it works

Your backend  ←—WebSocket—→  sdk-daemon  ←—Nostr relays—→  Portal app (user's phone)

1. Your backend asks sdk-daemon for a handshake URL → show it as a QR code
2. User scans with Portal app → you receive their Nostr public key
3. Your backend requests a payment (sats or fiat) → user approves in app → Lightning settlement

---

Quick start

1. Run sdk-daemon

docker run -d -p 3000:3000 \
  -e PORTAL__AUTH__AUTH_TOKEN=your-secret-token \
  -e PORTAL__NOSTR__PRIVATE_KEY=your-nostr-private-key-hex \
  getportal/sdk-daemon:0.3.0

2. Install the SDK

npm install portal-sdk          # TypeScript / JavaScript

// Java (Gradle) — via JitPack
implementation 'com.github.PortalTechnologiesInc:java-sdk:0.3.0'

3. Connect and authenticate a user

import { PortalSDK } from 'portal-sdk';

const client = new PortalSDK({ serverUrl: 'ws://localhost:3000/ws' });
await client.connect();
await client.authenticate('your-secret-token');

const url = await client.newKeyHandshakeUrl((userKey) => {
  console.log('User authenticated:', userKey);
});
// Show `url` as a QR code to the user

---

SDK versions

SDK	Version	Install
TypeScript / JavaScript	0.3.0	npm install portal-sdk
Java	0.3.0	JitPack
Docker image	0.3.0	docker pull getportal/sdk-daemon:0.3.0

The SDK major.minor version must match the daemon. Patch versions are independent. See Versioning & Compatibility.

---

What you can do

• Authenticate users — passwordless login via Nostr identity
• Request payments — single, recurring, or invoice-based; BTC (sats) or fiat (EUR, USD, and more)
• Issue JWTs — signed by the user's Nostr key, verifiable server-side
• Cashu tokens — mint, burn, and transfer ecash
• NWC wallet — connect any NWC-compatible wallet for outbound payments

---

This repository

Package	Description
portal-rest	SDK Daemon — HTTP + WebSocket API server
portal	Core Nostr protocol and conversation logic
portal-app	App runtime and wallet integration
portal-wallet	Wallet backends (NWC, Breez)
portal-rates	Fiat/BTC exchange rates
clients/ts	TypeScript SDK source
portal-cli	CLI tools for development and testing

---

Documentation

Full docs at portaltechnologiesinc.github.io/lib — guides for authentication, payments, Cashu, JWT, relay setup, Docker deployment, and more.

---

License: MIT · Java SDK · Demo