# Fast ID and fastid-sdk

Fast ID and the @fastxyz/fastid-sdk identity client

[Fast ID](https://id.fast.xyz) is a public identity directory bound to Fast accounts. The Node client [`@fastxyz/fastid-sdk`](https://github.com/fastxyz/fast-sdk/blob/main/packages/fastid-sdk/README.md) 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.

```bash
npm install @fastxyz/fastid-sdk
```

| Network | Fast ID site and public reads | Use |
| --- | --- | --- |
| `fast:mainnet` | [`id.fast.xyz`](https://id.fast.xyz) | Production records |
| `fast:testnet` | [`testnet.id.fast.xyz`](https://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

```ts
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](https://id.fast.xyz/AGENTS.md) 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](https://github.com/fastxyz/fast-sdk/blob/main/packages/fastid-sdk/README.md#claim-a-name-and-read-it-back-testnet) 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](https://id.fast.xyz/AGENTS.md) or [testnet](https://testnet.id.fast.xyz/AGENTS.md) guide for the exact trust and recovery contract.