Fast ID and fastid-sdk

Fast ID is a public identity directory bound to Fast accounts. The Node client @fastxyz/fastid-sdk exposes public reads and owner-authorized claims. It is not an OAuth 2.0 / OpenID Connect login provider, proof of personhood, or an assertion service for third parties. Names and profile fields should not be presented as independently verified identity.

Install and select a network

The published package requires Node.js 20.19 or newer. The former @fastxyz/id-sdk package name has been replaced by @fastxyz/fastid-sdk; update imports when migrating.

npm install @fastxyz/fastid-sdk

Network	Fast ID site and public reads	Use
fast:mainnet	id.fast.xyz	Production records
fast:testnet	testnet.id.fast.xyz	Testing only; not evidence about real people

The SDK binds responses to the selected network. Never use testnet identity data as a production fact or silently switch a signer between networks.

Read without a signer

import { IdReader, isCanonicalName } from '@fastxyz/fastid-sdk';

const reader = new IdReader({ network: 'fast:mainnet' });
const name = 'alice.smith';
if (!isCanonicalName(name)) throw new Error('Invalid Fast ID name');
const record = await reader.resolve(name);
console.log(record.address); // Fast address reported by this network's directory

IdReader also exposes identity(), availability(), links(), and propertyClaimed(). It needs no private key and applies network/name-binding response checks. A successful read establishes what the selected directory currently reports, not an independent validator-quorum proof or verified personhood. Owner-scoped link rows may be pending, verified, or stale; consumers of public evidence should inspect verified_properties in the name’s id.json. propertyClaimed(...).claimed === false is not proof of availability because that endpoint can fail open. See the Fast ID agent guide for each field’s evidence limits.

Owner-authorized writes

IdClient requires an authorized signer for claims and updates. Supported workflows include claiming a name, website/GitHub/ORCID/X claims, DOI imports, profile updates, revocation, sealed reports, and sharing URLs. A key gives signing authority; protect it as carefully as a payment key. Use fast:testnet and a funded test key before production. The package README contains a journaled claim example; do not replace it with an unjournaled one-line retry loop.

Before approving a paid claim, inspect the selected network’s GET /v1/network-info fee schedule, default fee token, and atomic units. Empty authoritative fee data can mean zero fee; a failed or malformed fee lookup does not. A preview does not cap the fee if the schedule changes before submission. claimName() performs its own fail-closed identity preflight, but a prior availability read cannot reserve a name or eliminate a race.

Persist an attempt record before the first paid submission. If the result is unknown, do not create another payment. IndeterminateSubmissionError carries a nonce, transaction ID, and an in-memory signed recoveryEnvelope for reconciliation; that envelope is a structured clone, not JSON-safe persistent data. RegistrationPendingError means the paid Fast transaction can have settled while the directory registration is pending. retryRegistration() retries registration only, not the payment. If settlement or registration cannot be established, stop and reconcile with trusted evidence rather than paying again.

GitHub and ORCID claims use a browser OAuth proof step. The SDK can prepare instructions and poll a persisted proof for a known provider identity; it does not run headless OAuth or receive provider tokens. For reports, the public workflow is a human handoff rather than a stable raw-envelope API. Follow the mainnet or testnet guide for the exact trust and recovery contract.