@overlay-social/sdk

Minimal, read-only TypeScript client for overlay.peck.to — the canonical BSV / BRC-100 social overlay behind peck.to, peck.bio, peck.press and friends.

It is a pure read lens: identity resolution, profiles, feed, and overlay state. It does not write, mint, pay, or federate — those capabilities do not exist on the live service, and this SDK only exposes what actually runs.

npm install @overlay-social/sdk

Requires native fetch (Node 18+, modern browsers, edge runtimes). On older Node, pass your own fetch via the constructor.

Quick start

import { createOverlayClient } from '@overlay-social/sdk'

const overlay = createOverlayClient() // -> https://overlay.peck.to

const feed = await overlay.getFeed({ limit: 20, type: 'post' })

Enriching a feed (the canonical pattern)

Feed authors are P2PKH base58 addresses. Resolve a whole page in one round-trip, then overwrite name/avatar/handle defensively — enrichment must never break the feed:

const { data } = await overlay.getFeed({ limit: 50, type: 'post' })
const addresses = [...new Set(data.map((p) => p.author).filter(Boolean) as string[])]
const ids = await overlay.resolveIdentities({ addresses }) // {} on any error

const rows = data.map((p) => {
  const id = p.author ? ids[p.author] : undefined
  return {
    ...p,
    displayName: id?.displayName ?? p.display_name ?? p.author,
    handle: id?.handle ?? null,
    avatarRef: id?.avatarRef ?? null,
  }
})

resolveIdentities returns {} on any failure and omits keys that have no canonical ProfileToken, so a UI that reads ids[author]?.displayName ?? fallback never throws.

API

Method	Endpoint	Returns
resolveIdentities({pubkeys?, addresses?})	POST /v1/identities/resolve	Record<inputKey, ResolvedIdentity> ({} on error/empty)
getIdentity(pubkey)	GET /identity/:pubkey	IdentityBundle | null
resolveHandle(handle)	GET /resolve/:handle	HandleResolution | null
getProfile({subject|owner|outpoint})	GET /v1/bio/profile	ProfileRow | null
listIdentities({limit?, offset?})	GET /v1/identities	DiscoveredIdentity[] ([] on error)
getFriends(subject)	GET /v1/friends/:subject	FriendsResponse (mutual/pendingIn/pendingOut + legacy)
getNotifications(address, params?)	GET /v1/notifications/:address	NotificationItem[] ([] on error)
getFollows(address)	GET /v1/follows/:address	FollowsResponse
getBlocks(address, kind?)	GET /v1/blocks/:address	BlockEntry[] (outgoing only, by design)
getFeed(params)	GET /v1/feed (incl. near/bbox geo)	FeedResponse (throws on upstream failure)
getPost(txid)	GET /v1/post/:txid	PeckRow | null
getThread(txid)	GET /v1/thread/:txid	{post, replies}
getState()	GET /state	OverlayState (topics + on-chain anchors)
getTopicRoot(topic)	GET /v1/topic/:topic/root (fallback /state)	TopicState | null
getAnchor(topic)	client-side over /state	TopicAnchor | null
verifyRoot(topic)	client-side over /state	{anchored, matchesLive, liveRoot, anchoredRoot, txid}

Avatar field divergence (read this)

The live overlay is not internally consistent and the SDK does not hide it:

• resolveIdentities and getProfile().state give avatarRef — the raw on-chain reference, e.g. uhrp://<sha256>.
• getIdentity().profile gives avatarUrl — an already-resolved https:// URL.

Both are typed verbatim so you choose how to render.

Data reality (honest)

• getFeed runs against ~2.5M indexed pecks today — most rows already carry a display_name.
• The identity layer is live but small: light self-attested profiles/handles (BRC-3) plus legacy ProfileTokens, with key-binding collapse — a bound posting key or address resolves to its identity root's canonical profile. Accounts without any attestation resolve empty; enrichment is additive and grows with adoption.
• getFriends reads the mutual-consent friendship layer (two one-way BRC-3 attestations = an active pair). Legacy BAP-era friend rows are exposed display-only and never count toward mutual.
• Every topic's Merkle state-root is anchored on-chain (1Sat ordinal with a logical prev-chain); verifyRoot(topic) tells you whether the served state matches the anchored root right now.

Configuration

const overlay = createOverlayClient({
  baseUrl: 'https://overlay.peck.to', // default
  timeoutMs: 8000,                    // hard per-request ceiling
  fetch: myFetch,                     // optional injected fetch
})

Not included (on purpose)

No writing / minting / wallet / payment-channel / paywall / federation. Reads go through the /v1/* + /identity + /resolve + /state facade, never the BRC-24 peck-schema lookup (that lookup() is a deliberate no-op), and never WhatsOnChain.

License

Open BSV License v5 — usable only on the Bitcoin SV blockchain, by design.