BSV blockchainBSV blockchain

Look up a user's identity key with Paymail

Paymail gives a user a handle that looks like an email address, such as alice@walletprovider.com. On the BSV blockchain today, apps and wallets use Paymail for two things:

  • Service discovery: given a handle’s domain, find out which Paymail capabilities it supports and where.
  • Identity key lookup: resolve a handle into the user’s identity key, the public key that identifies them to BRC-100 wallets and apps.

What to Use and What to Skip

Paymail started as a family of protocols, collectively called bsvalias, with many capabilities and extensions, such as resolving a handle into a payment address. Those older capabilities are not recommended for new apps. Payments go through the user’s BRC-100 wallet instead, as in Accept and send payments.

CapabilityFor new apps
Service discoveryUse it
Handle to identity key (public key infrastructure)Use it
Payment addressing and older extensionsSkip them

Look Up an Identity Key

The @bsv/paymail package provides PaymailClient, which discovers a domain’s capabilities and resolves a handle:

npm install @bsv/paymail
import { PaymailClient } from '@bsv/paymail'

const client = new PaymailClient()

// Resolve the handle into the user's identity key
const pki = await client.getPki('alice@walletprovider.com')
console.log(pki.pubkey)

To serve Paymail for your own domain, the same package provides PaymailRouter, an Express router for the /.well-known/bsvalias/* endpoints.

The Specification

The official Paymail standard is published at tsc.bsvblockchain.org. Older copies of the bsvalias and BRFC documents on other sites are pastes of the original text, so link the standard instead of them.