Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

SDK API reference

Concise reference for the main PortalSDK methods. For examples and workflows, see Basic Usage and the Guides.

Lifecycle & Auth

JavaScript
MethodDescription
connect(): Promise<void>Connect to Portal. Call once before other methods.
disconnect(): voidClose connection and clear state.
authenticate(token: string): Promise<void>Authenticate with your auth token (required after connect).

Auth and users

MethodDescription
newKeyHandshakeUrl(onKeyHandshake, staticToken?, noRequest?): Promise<string>Get URL for user key handshake; callback runs when user completes handshake.
authenticateKey(mainKey, subkeys?): Promise<AuthResponseData>Authenticate a user key (NIP-46 style).
Java
  • PortalSDK(healthEndpoint, wsEndpoint) — Create client.
  • connect(authToken) — Connect and authenticate.
  • sendCommand(request, callback) — Send any command. Request classes: AuthRequest, KeyHandshakeUrlRequest, RequestSinglePaymentRequest, MintCashuRequest, CalculateNextOccurrenceRequest, and others in the SDK.

Payments

JavaScript
MethodDescription
requestSinglePayment(mainKey, subkeys, paymentRequest, onStatusChange): Promise<void>Request a one-time Lightning payment.
requestRecurringPayment(mainKey, subkeys, paymentRequest): Promise<RecurringPaymentResponseContent>Request a recurring (subscription) payment.
requestInvoicePayment(mainKey, subkeys, paymentRequest, onStatusChange): Promise<void>Pay an invoice on behalf of a user.
requestInvoice(recipientKey, subkeys, content): Promise<InvoiceResponseContent>Request an invoice.
closeRecurringPayment(mainKey, subkeys, subscriptionId): Promise<string>Close a recurring payment subscription.
listenClosedRecurringPayment(onClosed): Promise<() => void>Listen for closed recurring payments; returns unsubscribe function.
Java

Use RequestSinglePaymentRequest, MintCashuRequest, and other request classes with sendCommand. See the Java SDK repository for the full list.

Profiles and identity

JavaScript
MethodDescription
fetchProfile(mainKey)Fetch a user’s Nostr profile (Promise<Profile | null>).
setProfile(profile): Promise<void>Set or update a profile.
fetchNip05Profile(nip05): Promise<Nip05Profile>Resolve a NIP-05 identifier.
Java

Use the appropriate request classes with sendCommand for profile and identity operations.

JWT

JavaScript
MethodDescription
issueJwt(target_key, duration_hours): Promise<string>Issue a JWT for the given key.
verifyJwt(public_key, token): Promise<{ target_key: string }>Verify a JWT and return claims.
Java

Use the JWT-related request classes with sendCommand.

Relays and Cashu

JavaScript
MethodDescription
addRelay(relay): Promise<string>Add a relay.
removeRelay(relay): Promise<string>Remove a relay.
requestCashu(...)Request Cashu tokens. See Cashu guide.
sendCashuDirect(...)Send Cashu tokens.
mintCashu(...)Mint Cashu tokens.
burnCashu(...)Burn Cashu tokens.
calculateNextOccurrence(calendar, from)Compute next occurrence for a recurrence calendar (Promise<Timestamp | null>).
Java

Use KeyHandshakeUrlRequest, RequestSinglePaymentRequest, MintCashuRequest, relay and Cashu request classes with sendCommand.

Events

JavaScript
MethodDescription
on(eventType | EventCallbacks, callback?): voidRegister listener, e.g. on('connected', fn) or on({ onConnected, onDisconnected, onError }).
off(eventType, callback): voidRemove a listener.
Java

Responses and notifications are delivered in the sendCommand callback.

Types overview

JavaScript
  • Currency — e.g. Currency.Millisats.
  • Timestamp — Timestamp.fromDate(date), Timestamp.fromNow(seconds), toDate(), toJSON().
  • Profile — id, pubkey, name, display_name, picture, about, nip05.
  • RecurringPaymentRequestContent, SinglePaymentRequestContent, InvoiceRequestContent — See type definitions in the package.
  • AuthResponseData, InvoiceStatus, RecurringPaymentStatus — Response and status types.

Full types are exported from portal-sdk; use your editor’s IntelliSense or the package source.

Java

PortalRequest, PortalResponse, PortalNotification, and request/response classes (e.g. CalculateNextOccurrenceRequest). See the Java SDK repository for the full API.

Next: Error Handling for PortalSDKError and error codes.