Live endpoints
The Bitcoin PIR reference deployment runs two PIR servers — pir1 and
pir2 — with deliberately different roles, plus a Direct ORAM host inside
an AMD SEV-SNP enclave. Wallets connect to the servers of the backend they
use; the SDK handles the routing.
The two roles
| Endpoint | Short name | Role | Hardware | SEV-SNP | Credits |
|---|---|---|---|---|---|
wss://weikeng1.bitcoinpir.org | pir1 | Hint server (+ DPF server 0, OnionPIR) | Hetzner i7-8700 | No | DPF and HarmonyPIR hints free while it has room (hints up to an hourly budget); OnionPIR free one lookup at a time, up to an hourly budget |
wss://bitcoin-pir-weikeng-laptop.chenweikeng.com | pir2 | Query server (+ DPF server 1) | MacBook (macOS arm64) | No | DPF and HarmonyPIR queries free while it has room |
wss://weikeng2.bitcoinpir.org | ORAM host | Direct ORAM only | VPSBG cloud VPS, AMD EPYC 7713P (Milan) | Yes (Tier 3 UKI) | Direct ORAM free while it has room |
Each server publishes what it charges per backend (Payments): DPF-PIR and HarmonyPIR (hints on pir1, queries on pir2) are free while the servers have room, while OnionPIR needs a credit provider.
Until 2026-10-02 pir2 was a VPSBG AMD SEV-SNP host (Tier 3 UKI) at
wss://weikeng2.bitcoinpir.org, which also served Direct ORAM. That host
was retired; a MacBook without a TEE now serves the pir2 roles under the
server id pir2-macbook-v1. Since 2026-10-03 wss://weikeng2.bitcoinpir.org
is a new VPSBG SEV-SNP host (AMD Milan, server id pir2-oram-v1) that
serves Direct ORAM only.
The hint/query split is intentional. The hint server runs on commodity hardware because the hint blob alone reveals nothing about which addresses are queried. Neither PIR server has hardware attestation today: each is checked by its binary pin plus its operator-signed identity. The ORAM host is attested by AMD SEV-SNP as well (see Attestation).
┌───────────────────────────┐
│ pir1 (Hetzner, no SEV) │
│ - HarmonyPIR hint srv │
│ - DPF server 0 │
│ - OnionPIR (single srv) │
└─────────────┬─────────────┘
│
│ hint pool + DPF + OnionPIR
│ per-query traffic
│
┌──────────┐ │
│ Wallet │────────────────────┤
└──────────┘ │
│ DPF + HarmonyPIR per-query
│ traffic
│
┌─────────────▼─────────────┐
│ pir2 (MacBook, no TEE) │
│ - DPF server 1 │
│ - HarmonyPIR query srv │
│ (no OnionPIR — runs │
│ on pir1 only; Direct │
│ ORAM: weikeng2 TEE) │
└───────────────────────────┘WebSocket-only
All three endpoints are WebSocket-only. A plain HTTP GET / returns
502 by design — there is no HTTP fallback, no JSON-RPC layer, no
SSE.
Health-checking from the outside requires a real WebSocket handshake
(Upgrade: websocket, etc.) followed by a REQ_PING (0x00) frame.
A normal curl or wget will not work.
Probing these endpoints with plain HTTP returns 502. The endpoint is
healthy if it returns 502 to HTTP and accepts a WebSocket upgrade.
Use a WS-aware probe like wscat if you need to test from the
command line.
Per-backend routing
Each backend uses the two endpoints differently:
DPF
Connect to both servers. Server 0 = pir1, server 1 = pir2.
new WasmDpfClient(
'wss://weikeng1.bitcoinpir.org', // server 0 (Hetzner)
'wss://bitcoin-pir-weikeng-laptop.chenweikeng.com', // server 1 (MacBook)
);Order matters cryptographically only in that the two share-keys are labelled "server 0" and "server 1"; either ordering is correct as long as the wallet is consistent.
HarmonyPIR
Connect to both, but the role is asymmetric:
new WasmHarmonyClient(
'wss://weikeng1.bitcoinpir.org', // hint server
'wss://bitcoin-pir-weikeng-laptop.chenweikeng.com', // query server
);The hint server (pir1) only sees REQ_HARMONY_HINTS traffic. The
query server (pir2) sees per-query frames.
OnionPIR
OnionPIR is single-server. Connect to whichever server hosts
OnionPIR. In the current reference deployment that's pir1 — pir2
runs --serve-queries only and does not serve OnionPIR. Check
attest-pin.ts
for the canonical config.
Direct ORAM
Direct ORAM is single-server too and runs inside an SEV-SNP guest: the
server process sees the script hash, the host does not. Since 2026-10-03
it runs on its own VPSBG host (wss://weikeng2.bitcoinpir.org, AMD Milan,
server id pir2-oram-v1), free while the guest has room. ORAM_PROVIDER
carries its endpoint and pins; it is null only while Direct ORAM is
paused, and clients then stop with ORAM_PAUSED_MESSAGE. Use the
production request shape — every lookup is one fixed-budget ORAM access
with 25 padded slots:
import {
OramPirClientAdapter, ORAM_PROVIDER, ORAM_PAUSED_MESSAGE, PRODUCTION_ORAM_BATCH_PLANNER,
} from 'bitcoin-pir-web';
if (!ORAM_PROVIDER) throw new Error(ORAM_PAUSED_MESSAGE); // null only while paused
new OramPirClientAdapter({
serverUrl: ORAM_PROVIDER.endpoint,
batchPlanner: PRODUCTION_ORAM_BATCH_PLANNER,
// …pins: see the playground's ORAM snippet
});Reading from the right server
For DPF and HarmonyPIR, the SDK enforces the role. You can't ask
pir1 for a per-query response — it's the hint server and rejects
unknown variants.
For OnionPIR, the wallet picks the endpoint manually.
Server info / catalog
Both servers respond to:
REQ_GET_INFO (0x01) → RESP_INFO (database parameters)
REQ_GET_DB_CATALOG (0x02) → RESP_DB_CATALOG (full per-DB catalog)
REQ_PING (0x00) → RESP_PONG (health check)
REQ_ATTEST (admin) → REPORT bytes (see Attestation)The SDK fetches the catalog automatically as part of connect() /
sync(). For manual inspection use:
const catalog = await client.fetchCatalog();
console.log(catalog.toJson());The catalog lists every database the server hosts — typically the full UTXO snapshot at some height, plus a chain of delta databases covering blocks since.
TLS termination
Both endpoints are fronted by cloudflared running on the host.
TLS is terminated at the tunnel; the WebSocket is then forwarded
to the local unified_server binary on a loopback port.
This means:
- The CA-issued TLS certificate on the public URL is what your browser sees. Use it for the standard browser-level authentication.
- For binding to the binary (not just the TLS cert), use the
attestation flow —
upgradeToSecureChannelwraps the WebSocket in an AEAD layer keyed to the attested server static key.
Running your own
If you're deploying the reference servers yourself, see:
pir-sdk-server— the publishable server wrapper.- The
unified_serverbinary built bynix build .#unified-serveris the production binary. - The
flake.nixtier3-ukiderivation is the UKI build (for SEV-SNP deployments). - Operator runbook lives in
docs/PHASE3_ROADMAP.md.
Where to go next
- Attestation — pinning the running binary and checking the operator-signed identity of each server.
- Wire format — the WebSocket frame layout both endpoints speak.
- Troubleshooting — connection issues.