# dots.id

> dots.id is a portable identity, verification, and credits layer for any app. Sign in with dots (OAuth 2.1 + PKCE), carry one verified identity + a cross-app credit balance (pute) everywhere, and attest interactions with cryptographic proofs (zkTLS). Drop-in via the `@wrldbld/dots` SDK — one API key.

## For agents — install in three steps

You can wire dots into a project end to end without a human:

1. **CLI** — `npx wrldbld add ui` installs the `@wrldbld/ui` render engine + `@wrldbld/dots` SDK. `npx wrldbld list` shows every module and block.
2. **SDK** — `npm i worldbuild` (the whole ecosystem in one package; `import { createDots } from "worldbuild"`), or the scoped module directly: `npm i @wrldbld/dots@alpha`. `createDots({ apiKey })` gives you auth, credits, identity, attestations, data, connect, cosign.
3. **UI** — `npx wrldbld add provider connector pute-balance attestations` drops working React blocks into the project (also installable with `npx shadcn add https://www.dots.id/r/connector.json`).

Or let the installer wire it for you: `npx wrldbld init` detects the framework, router, and `src/` layout, then writes the provider + `/dots/callback` + env var in the right place (idempotent; `--dry-run` to preview).

Registry index: https://www.dots.id/r/registry.json · Full agent guide: https://www.dots.id/llms-full.txt

## Where it goes — per-framework placement

dots' core SDK (`createDots`) is framework-agnostic; the `@wrldbld/ui` React blocks need React. To wire it correctly, detect the stack and place three things — the provider (wrap once), the `/dots/callback` route, and the public env var. The SDK's default `redirectUri` is `${location.origin}/dots/callback`, so keep the callback at that path and it just works.

| Stack | UI blocks? | Env var | Wrap provider in | Callback file |
|---|---|---|---|---|
| Next.js App Router | yes | `NEXT_PUBLIC_DOTS_API_KEY` | `app/providers.tsx` → `app/layout.tsx` | `app/dots/callback/page.tsx` |
| Next.js Pages Router | yes | `NEXT_PUBLIC_DOTS_API_KEY` | `pages/_app.tsx` | `pages/dots/callback.tsx` |
| Vite + React | yes | `VITE_DOTS_API_KEY` | `src/main.tsx` (around `<App/>`) | route `/dots/callback` |
| Remix / React Router v7 | yes | `VITE_DOTS_API_KEY` | `app/root.tsx` (around `<Outlet/>`) | `app/routes/dots.callback.tsx` |
| Astro (+ @astrojs/react) | island | `PUBLIC_DOTS_API_KEY` | React island, `client:load` | `src/pages/dots/callback.astro` |
| SvelteKit / Vue / Solid | no — SDK only | `PUBLIC_`/`VITE_` per tool | n/a — call `createDots()` directly | framework route calling `dots.handleCallback()` |
| Expo / React Native | no — SDK only | `EXPO_PUBLIC_DOTS_API_KEY` | n/a | deep-link handler; pass a custom `redirectUri` + a `storage` adapter |

Detection signals (read the project's `package.json` deps + dir layout): `next` + `app/` ⇒ App Router; `next` + `pages/` only ⇒ Pages Router; `vite` + `react` ⇒ Vite React; `@remix-run/*` or `@react-router/dev` ⇒ Remix/RRv7; `astro` ⇒ Astro; `@sveltejs/kit`/`vue`/`solid-js` ⇒ SDK-only; `expo`/`react-native` ⇒ native. Honor `src/` if the project uses it. Full per-framework file contents are in https://www.dots.id/llms-full.txt under "Per-framework wiring".

## Built-in UI blocks (@wrldbld/ui — the render engine)

- `provider` — `<DotsProvider>` + the `/dots/callback` route. Install first.
- `sign-in` — `<SignInWithDots />`, one-click OAuth.
- `connector` — `<Connector />`, sign-in / identity chip + menu (the "connect" button for dots).
- `pute-balance` — `<PuteBalance />`, the cross-app credit balance + Stripe top-up.
- `attestations` — `<Attestations />`, verified claims bound to the dot.
- Each block JSON: https://www.dots.id/r/{name}.json. Preview + configure live at https://www.dots.id/dev/ui.

## Core concepts

- A **dot** is a person's portable identity (a Privy wallet + verified emails/socials), created through a multi-step flow (wallet, username, Vercel, verified email, subscription, basecolor) until `dots_id_status = "complete"`.
- **Attestations** are verified claims bound to a dot (emails, socials, or any zkTLS-proven web fact).
- **pute** is one credit balance the user carries across every dots-integrated app (debit before compute, top up via Stripe).
- **Co-sign** (alpha) lets a confirmed dot vouch another dot or agent into scoped, tiered authority — wallet-signed (EIP-712) with a zkTLS second factor.

## SDK (@wrldbld/dots)

- [Quickstart — first app](https://www.dots.id/docs/quickstart): install, API key, sign-in, callback, credits.
- [SDK API reference](https://www.dots.id/docs/api-reference): auth, identity, credits, attestations, emails, cosign.
- Install: `npm i @wrldbld/dots@alpha`. Init: `createDots({ apiKey })`.

## REST API

- [REST reference](https://www.dots.id/docs/api): OAuth, identity/status, confirm, attestations, pute balance/debit/topup, admin grant, cosign.
- OAuth discovery: `/.well-known/openid-configuration`, `/jwks.json`.

## For developers

- [Getting an API key](https://www.dots.id/docs/getting-an-api-key): create an OAuth client at `/dev/clients`; public (PKCE) vs confidential; scopes and redirect URIs. Each client sets a **sign-in requirement** (`min_identity`): `none` (any Privy user — gate features yourself via the `dots_id_status` claim), `subscriber` (active subscription), or `complete` (full dots.id; default). Fresh users below the bar are sent to `/create`.
- [Admin & dev guide](https://www.dots.id/docs/admin): granting credits, smoke tests, zkTLS/co-sign dev flags.

## Optional

- Scopes: `openid profile email wallet social:* data:read data:write pute:read pute:spend context:read context:write mcp:use connect cosign delegate org:act org:admin offline_access`. `connect` (see/grow your dot graph) is the rung before `cosign`.
- Status of a dot is read from access-token claims: `sub`, `username`, `wallet_address`, `dots_id_status`.