@truealter/sdk 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +103 -74
  2. package/dist/bin/alter-identity.js +177 -19
  3. package/dist/bin/mcp-bridge.js +47 -11
  4. package/dist/index.cjs +203 -20
  5. package/dist/index.d.cts +431 -30
  6. package/dist/index.d.ts +431 -30
  7. package/dist/index.js +199 -23
  8. package/dist/mcp-bridge.js +166 -0
  9. package/package.json +7 -4
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @truealter/sdk
2
2
 
3
- ALTER Identity SDK — query the continuous identity field from any JavaScript/TypeScript environment.
3
+ ALTER Identity SDK - query the continuous identity field from any JavaScript/TypeScript environment.
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@truealter/sdk.svg)](https://www.npmjs.com/package/@truealter/sdk)
6
6
  [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
@@ -10,9 +10,9 @@ ALTER Identity SDK — query the continuous identity field from any JavaScript/T
10
10
  A thin client over the ALTER MCP server (Streamable HTTP, JSON-RPC 2.0, MCP spec `2025-11-25`) with x402 micropayment support, ES256 provenance verification, and config generators for Claude Code, Cursor, and generic MCP clients.
11
11
 
12
12
  - **Branded host:** `https://mcp.truealter.com` (serves `.well-known/mcp.json` for discovery)
13
- - **JSON-RPC wire endpoint:** `https://mcp.truealter.com/api/v1/mcp` — this is what Streamable HTTP POSTs target (the SDK default)
13
+ - **JSON-RPC wire endpoint:** `https://mcp.truealter.com/api/v1/mcp` - this is what Streamable HTTP POSTs target (the SDK default)
14
14
  - **Wire protocol:** Streamable HTTP, JSON-RPC 2.0, MCP `2025-11-25` (server negotiates `2025-06-18` + `2025-03-26` for backwards-compatible clients)
15
- - **Tools:** **32 typed and wired** — 24 free (L0) + 8 premium (L1–L5). Mirrors the live server's `tools/list` response byte-for-byte; every name in `FREE_TOOL_NAMES` / `PREMIUM_TOOL_NAMES` has a matching server handler at `mcp.truealter.com/api/v1/mcp`.
15
+ - **Tools:** **40 typed and wired** - 24 free (L0) + 9 premium (L1–L5) + 7 alter-to-alter messaging. Mirrors the live server's `tools/list` response byte-for-byte; every name in `FREE_TOOL_NAMES` / `PREMIUM_TOOL_NAMES` / `MESSAGING_TOOL_NAMES` has a matching server handler at `mcp.truealter.com/api/v1/mcp`.
16
16
  - **Runtime:** Node 18+, Deno, Bun, Cloudflare Workers, modern browsers
17
17
  - **Crypto:** `@noble/ed25519` + `@noble/hashes` (no other dependencies)
18
18
  - **Bundle:** ESM + CJS dual output
@@ -22,12 +22,60 @@ A thin client over the ALTER MCP server (Streamable HTTP, JSON-RPC 2.0, MCP spec
22
22
  ```
23
23
  npm install @truealter/sdk
24
24
  npx alter-identity init
25
- npx alter-identity verify ~truealter
25
+ npx alter-identity verify ~alter
26
26
  ```
27
27
 
28
+ ## Bridge vs SDK
29
+
30
+ The `alter-mcp-bridge` binary shipped in this package (`bin/mcp-bridge.ts`)
31
+ is a **dev/demo surface** for dropping ALTER into MCP hosts that speak the
32
+ stdio transport (Claude Code, Cursor, Continue, Windsurf). It is useful for
33
+ handshake, `tools/list`, and L0 tool calls, but it does not carry ES256
34
+ per-invocation signing - authenticated MCP tools will fail at the server
35
+ edge when reached through the bridge. For production use, import
36
+ `@truealter/sdk` directly and construct an `MCPClient` / `AlterClient` with
37
+ the optional `signing` parameter; that path is the load-bearing one and
38
+ carries the provenance envelope end-to-end. Bridge signing lands in Wave-2
39
+ alongside the CLI wallet/consent verbs.
40
+
41
+ ## CLI
42
+
43
+ The package ships two binaries. `alter-identity` is the full SDK-feature
44
+ binary (`init`, `verify`, `whoami`, wire/unwire, signing, etc). `alter`
45
+ is a slim, task-oriented binary for day-to-day use:
46
+
47
+ | Command | Purpose |
48
+ |---|---|
49
+ | `alter login` | OAuth loopback sign-in; stores a session at `~/.config/alter/session.json` (mode `0600`). |
50
+ | `alter depth [--json]` | GET `/api/v1/identity/depth` - identity-depth score, agentic activity, top/bottom five traits. |
51
+ | `alter claim <claim_code>` | Accept an identity invite. Prompts for email, password (min 12 chars, hidden), and explicit TOS acceptance, then POSTs `/api/v1/identity/claim`. |
52
+ | `alter mirror` | Day-2 Mirror phase + streak. `alter mirror daily` claims today's Mirror; `alter mirror next` shows the next revelation window. |
53
+ | `alter discover [--limit N]` | MCP-backed summary - calls `alter_whoami` and `alter_verify` against your bound handle. Degrades gracefully if the MCP endpoint is 5xx. |
54
+
55
+ The session file is created with `0600` permissions; its parent dir
56
+ (`~/.config/alter/`) is created with `0700`. Override the config root
57
+ via `XDG_CONFIG_HOME`. Run `alter --help` for the inline reference.
58
+
28
59
  ## Why ALTER ≠ IAM
29
60
 
30
- Identity Access Management answers *who is logged in*. ALTER answers *who they actually are* — a continuous field of recognition that any IAM stack can sit on top of.
61
+ Identity Access Management answers *who is logged in*. ALTER answers *who they actually are* - a continuous field of recognition that any IAM stack can sit on top of.
62
+
63
+ ## Theoretical Foundation
64
+
65
+ ALTER is the working instantiation of an eight-paper academic corpus on identity field theory. The SDK below is what happens when the theory ships as protocol. Each paper is open access on figshare under CC-BY 4.0.
66
+
67
+ | Paper | Title | DOI |
68
+ |-------|-------|-----|
69
+ | I | *Belonging is earned, not inherited* | [10.6084/m9.figshare.31794784](https://doi.org/10.6084/m9.figshare.31794784) |
70
+ | II | *The self is inferred, not owned* | [10.6084/m9.figshare.31804222](https://doi.org/10.6084/m9.figshare.31804222) |
71
+ | III | *The same form, at every scale* | [10.6084/m9.figshare.31812955](https://doi.org/10.6084/m9.figshare.31812955) |
72
+ | IV | *Measurement changes the thing measured* | [10.6084/m9.figshare.31812982](https://doi.org/10.6084/m9.figshare.31812982) |
73
+ | V | *Political failure has a geometry* | [10.6084/m9.figshare.31813000](https://doi.org/10.6084/m9.figshare.31813000) |
74
+ | VI | *When does a machine have a self* | [10.6084/m9.figshare.31813006](https://doi.org/10.6084/m9.figshare.31813006) |
75
+ | VII | *Seventy-five predictions, each falsifiable* | [10.6084/m9.figshare.31951644](https://doi.org/10.6084/m9.figshare.31951644) |
76
+ | VIII | *Identity as a field, not a property* | [10.6084/m9.figshare.31951383](https://doi.org/10.6084/m9.figshare.31951383) |
77
+
78
+ For the lay-register chapter version, see [`/origin`](https://truealter.com/origin).
31
79
 
32
80
  ## API
33
81
 
@@ -37,20 +85,20 @@ Identity Access Management answers *who is logged in*. ALTER answers *who they a
37
85
  import { AlterClient, X402Client } from "@truealter/sdk";
38
86
 
39
87
  const alter = new AlterClient({
40
- endpoint: "https://mcp.truealter.com/api/v1/mcp", // optional — this is the default; bare host returns 405
88
+ endpoint: "https://mcp.truealter.com/api/v1/mcp", // optional - this is the default; bare host returns 405
41
89
  apiKey: process.env.ALTER_API_KEY, // optional for free tier
42
- x402: new X402Client({ // optional — only required for premium tools
90
+ x402: new X402Client({ // optional - only required for premium tools
43
91
  signer: yourViemOrEthersSigner,
44
92
  maxPerQuery: "0.10",
45
93
  }),
46
94
  });
47
95
  ```
48
96
 
49
- ### Free tier (L0 — no payment required)
97
+ ### Free tier (L0 - no payment required)
50
98
 
51
99
  ```ts
52
100
  // Verify a registered identity by handle, email, or id
53
- const verified = await alter.verify("~truealter");
101
+ const verified = await alter.verify("~alter");
54
102
  const verifiedById = await alter.verify(
55
103
  "550e8400-e29b-41d4-a716-446655440000",
56
104
  {
@@ -60,15 +108,15 @@ const verifiedById = await alter.verify(
60
108
  },
61
109
  );
62
110
 
63
- // Reference data — the 12 ALTER archetypes
111
+ // Reference data - the 12 ALTER archetypes
64
112
  const archetypes = await alter.listArchetypes();
65
113
 
66
114
  // Identity depth and available tool tiers
67
115
  const depth = await alter.getEngagementLevel({
68
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
116
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
69
117
  });
70
118
 
71
- // Search by trait criteria — no PII exposed, max 5 results
119
+ // Search by trait criteria - no PII exposed, max 5 results
72
120
  const matches = await alter.searchIdentities({
73
121
  trait_criteria: {
74
122
  pressure_response: { min: 0.7 },
@@ -80,33 +128,33 @@ const matches = await alter.searchIdentities({
80
128
  const thread = await alter.goldenThreadStatus();
81
129
  ```
82
130
 
83
- ### Premium tier (L1–L5 — x402 payment required)
131
+ ### Premium tier (L1–L5 - x402 payment required)
84
132
 
85
133
  ```ts
86
- // L1 — Extract trait signals from text ($0.005, first 100 free per bot)
134
+ // L1 - Extract trait signals from text ($0.005, first 100 free per bot)
87
135
  const signals = await alter.assessTraits({
88
136
  text: "I led the incident response when our payment rails went down...",
89
137
  context: "interview transcript",
90
138
  });
91
139
 
92
- // L2 — Full 33-trait vector ($0.01)
140
+ // L2 - Full 33-trait vector ($0.01)
93
141
  const vector = await alter.getFullTraitVector({
94
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
142
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
95
143
  });
96
144
 
97
- // L4 — Belonging probability for a person-job pairing ($0.05)
145
+ // L4 - Belonging probability for a person-job pairing ($0.05)
98
146
  const belonging = await alter.computeBelonging({
99
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
147
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
100
148
  job_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
101
149
  });
102
150
 
103
- // L5 — Top match recommendations ($0.50)
151
+ // L5 - Top match recommendations ($0.50)
104
152
  const recommendations = await alter.getMatchRecommendations({
105
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
153
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
106
154
  limit: 5,
107
155
  });
108
156
 
109
- // L5 — Human-readable narrative explaining a match ($0.50)
157
+ // L5 - Human-readable narrative explaining a match ($0.50)
110
158
  const narrative = await alter.generateMatchNarrative({
111
159
  match_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
112
160
  });
@@ -116,9 +164,9 @@ const narrative = await alter.generateMatchNarrative({
116
164
 
117
165
  ```ts
118
166
  // Every medium- and high-blast-radius response is signed with ES256.
119
- // Verification is opt-in — call alter.verifyProvenance(...) yourself.
167
+ // Verification is opt-in - call alter.verifyProvenance(...) yourself.
120
168
  const result = await alter.getFullTraitVector({
121
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
169
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
122
170
  });
123
171
 
124
172
  const check = await alter.verifyProvenance(result._meta?.provenance);
@@ -152,7 +200,7 @@ const mcp = new MCPClient({ endpoint: "https://mcp.truealter.com/api/v1/mcp" });
152
200
  await mcp.initialize();
153
201
  const tools = await mcp.listTools();
154
202
  const response = await mcp.callTool("verify_identity", {
155
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
203
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
156
204
  });
157
205
  ```
158
206
 
@@ -182,7 +230,7 @@ Resulting `.mcp.json`:
182
230
  "alter": {
183
231
  "url": "https://mcp.truealter.com/api/v1/mcp",
184
232
  "transport": "streamable-http",
185
- "description": "ALTER Identity — psychometric identity field for AI agents",
233
+ "description": "ALTER Identity - psychometric identity field for AI agents",
186
234
  "headers": {
187
235
  "X-ALTER-API-Key": "ak_..."
188
236
  }
@@ -224,13 +272,13 @@ npx alter-identity init # generate keypair, discover MCP, write ~/
224
272
  npx alter-identity config # print Claude .mcp.json snippet (default)
225
273
  npx alter-identity config --cursor # print Cursor .cursor/mcp.json snippet
226
274
  npx alter-identity config --generic # print generic mcpServers snippet
227
- npx alter-identity verify ~truealter # verify an identity
275
+ npx alter-identity verify ~alter # verify an identity
228
276
  npx alter-identity status # show connection state and probe the endpoint
229
277
  ```
230
278
 
231
279
  ## x402 Micropayments
232
280
 
233
- ALTER monetises premium tools via the [x402](https://x402.org) standard — HTTP `402 Payment Required` with on-chain settlement.
281
+ ALTER monetises premium tools via the [x402](https://x402.org) standard - HTTP `402 Payment Required` with on-chain settlement.
234
282
 
235
283
  ### The retry flow
236
284
 
@@ -238,41 +286,24 @@ ALTER monetises premium tools via the [x402](https://x402.org) standard — HTTP
238
286
  2. Server replies `402 Payment Required` with a payment requirement (amount, recipient, asset, network).
239
287
  3. Client signs and broadcasts a USDC transfer on Base L2, attaches the proof, retries.
240
288
  4. Server validates the proof, executes the tool, signs the response with ES256, returns it.
241
- 5. The treasury splits the payment within seconds.
289
+ 5. AlterRouter executes the split on-chain in the same transaction. The data subject receives Identity Income directly; ALTER receives only its protocol cut. No custodian, no broker.
242
290
 
243
291
  The SDK handles steps 2–4 automatically when an `X402Client` with a configured `signer` is passed in.
244
292
 
245
293
  ### Tier structure
246
294
 
247
- | Tier | Cost | Tools |
248
- |------|----------|-----------------------------------------------------|
249
- | L1 | $0.005 | `assess_traits`, `get_trait_snapshot` |
250
- | L2 | $0.01 | `get_full_trait_vector`, `get_side_quest_graph` |
251
- | L3 | $0.025 | `query_graph_similarity` |
252
- | L4 | $0.05 | `compute_belonging` |
253
- | L5 | $0.50 | `get_match_recommendations`, `generate_match_narrative` |
254
-
255
- The first **100 calls per bot are free** before x402 settlement engages — enough to evaluate the network without spending a cent.
295
+ x402 micropayments at L0–L5 trust tiers. Per-call pricing visible after `alter login`.
256
296
 
257
297
  ### Identity income split
258
298
 
259
- Every settled call is split four ways:
260
-
261
- | Recipient | Share |
262
- |----------------------|-------|
263
- | Data subject | 75% |
264
- | Facilitator agent | 5% |
265
- | ALTER (protocol) | 15% |
266
- | Cooperative treasury | 5% |
267
-
268
- The 75% to the data subject is the foundation of *Identity Income* — humans earn from queries against their own identity field, automatically, without intermediation.
299
+ The majority of every settled call flows to the data subject as Identity Income. Split details available post-authentication via `alter status`.
269
300
 
270
301
  ### Code example
271
302
 
272
303
  ```ts
273
304
  import { AlterClient, X402Client, type X402Signer } from "@truealter/sdk";
274
305
 
275
- // Bring your own signer — viem, ethers, a hardware wallet bridge, anything.
306
+ // Bring your own signer - viem, ethers, a hardware wallet bridge, anything.
276
307
  // The SDK ships without a wallet dependency on purpose.
277
308
  const signer: X402Signer = {
278
309
  async settle(envelope) {
@@ -302,11 +333,11 @@ const alter = new AlterClient({
302
333
 
303
334
  // Auto-retries with payment when the server returns 402
304
335
  const vector = await alter.getFullTraitVector({
305
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
336
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
306
337
  });
307
338
  ```
308
339
 
309
- If a quoted envelope exceeds `maxPerQuery`, uses an unallowed network, or names an unallowed asset, the SDK rejects the call with `AlterError` *before* invoking the signer — no on-chain transaction is broadcast.
340
+ If a quoted envelope exceeds `maxPerQuery`, uses an unallowed network, or names an unallowed asset, the SDK rejects the call with `AlterError` *before* invoking the signer - no on-chain transaction is broadcast.
310
341
 
311
342
  ## Provenance Verification
312
343
 
@@ -314,7 +345,7 @@ Every response from a medium- or high-blast-radius tool ships with an ES256 JWS
314
345
 
315
346
  ```ts
316
347
  const result = await alter.getFullTraitVector({
317
- candidate_id: "550e8400-e29b-41d4-a716-446655440000",
348
+ member_id: "550e8400-e29b-41d4-a716-446655440000",
318
349
  });
319
350
 
320
351
  const check = await alter.verifyProvenance(result._meta?.provenance);
@@ -325,7 +356,7 @@ The SDK fetches public keys from `https://api.truealter.com/.well-known/alter-ke
325
356
 
326
357
  ### `verify_at` hostname allowlist (v0.1.1+)
327
358
 
328
- Every provenance envelope may carry a `verify_at` hint telling the SDK where to fetch the JWKS from. Because that hint is *server-supplied*, a hostile MCP server could otherwise point it at an attacker-controlled JWKS and pass ES256 verification with its own signing key. The SDK therefore gates `verify_at` through a hostname allowlist (default: `api.truealter.com`, `mcp.truealter.com`) and rejects `http://` URLs unconditionally. Downstream integrators with their own deployment can extend the allowlist — without forking the SDK — via `verifyAtAllowlist` on either `AlterClient` or a direct `verifyProvenance()` call:
359
+ Every provenance envelope may carry a `verify_at` hint telling the SDK where to fetch the JWKS from. Because that hint is *server-supplied*, a hostile MCP server could otherwise point it at an attacker-controlled JWKS and pass ES256 verification with its own signing key. The SDK therefore gates `verify_at` through a hostname allowlist (default: `api.truealter.com`, `mcp.truealter.com`) and rejects `http://` URLs unconditionally. Downstream integrators with their own deployment can extend the allowlist - without forking the SDK - via `verifyAtAllowlist` on either `AlterClient` or a direct `verifyProvenance()` call:
329
360
 
330
361
  ```ts
331
362
  import { AlterClient, DEFAULT_VERIFY_AT_ALLOWLIST } from "@truealter/sdk";
@@ -338,11 +369,11 @@ const alter = new AlterClient({
338
369
  });
339
370
  ```
340
371
 
341
- If you pin `jwksUrl` explicitly, the envelope's `verify_at` is ignored entirely — the pinned URL wins. The `https:` scheme requirement applies to pinned URLs too.
372
+ If you pin `jwksUrl` explicitly, the envelope's `verify_at` is ignored entirely - the pinned URL wins. The `https:` scheme requirement applies to pinned URLs too.
342
373
 
343
374
  ### Why this matters
344
375
 
345
- Provenance verification is how Agent A trusts that data from Agent B truly came from ALTER. If Agent B forwards a trait vector or belonging score, Agent A can replay the JWS against ALTER's published keys and confirm — without contacting ALTER again — that the payload is authentic, untampered, and was issued for the person Agent B claims it concerns. No shared secret, no trust in the intermediary, no out-of-band coordination.
376
+ Provenance verification is how Agent A trusts that data from Agent B truly came from ALTER. If Agent B forwards a trait vector or belonging score, Agent A can replay the JWS against ALTER's published keys and confirm - without contacting ALTER again - that the payload is authentic, untampered, and was issued for the person Agent B claims it concerns. No shared secret, no trust in the intermediary, no out-of-band coordination.
346
377
 
347
378
  This is what makes ALTER usable as identity infrastructure rather than just an API: signed claims propagate across agent networks the same way DKIM-signed mail propagates across SMTP relays.
348
379
 
@@ -350,9 +381,9 @@ This is what makes ALTER usable as identity infrastructure rather than just an A
350
381
 
351
382
  ALTER follows the discovery cascade specified in [draft-morrison-mcp-dns-discovery-01](https://datatracker.ietf.org/doc/draft-morrison-mcp-dns-discovery/). Given a domain (e.g. `truealter.com`), the SDK resolves the MCP endpoint in three steps, falling through on each failure:
352
383
 
353
- 1. **DNS TXT** — query `_mcp.truealter.com` for a TXT record of the form `mcp=https://mcp.truealter.com;version=2025-11-25`. This is the fastest path and works without an HTTP round-trip.
354
- 2. **`.well-known/mcp.json`** — fetch `https://truealter.com/.well-known/mcp.json` for the standard MCP server descriptor. This is the cross-vendor fallback.
355
- 3. **`.well-known/alter.json`** — fetch `https://truealter.com/.well-known/alter.json` for the ALTER-specific descriptor, including signing keys, x402 wallet address, supported tool tiers, and federation endpoints.
384
+ 1. **DNS TXT** - query `_mcp.truealter.com` for a TXT record of the form `mcp=https://mcp.truealter.com;version=2025-11-25`. This is the fastest path and works without an HTTP round-trip.
385
+ 2. **`.well-known/mcp.json`** - fetch `https://truealter.com/.well-known/mcp.json` for the standard MCP server descriptor. This is the cross-vendor fallback.
386
+ 3. **`.well-known/alter.json`** - fetch `https://truealter.com/.well-known/alter.json` for the ALTER-specific descriptor, including signing keys, x402 wallet address, supported tool tiers, and federation endpoints.
356
387
 
357
388
  ```ts
358
389
  import { discover } from "@truealter/sdk";
@@ -364,34 +395,34 @@ const descriptor = await discover("truealter.com");
364
395
  const httpsOnly = await discover("truealter.com", { skipDns: true });
365
396
  ```
366
397
 
367
- The IETF draft is being progressed through the IETF; until adoption, the cascade order may change. Pin the SDK version to a specific minor release if you depend on this behaviour.
398
+ This draft is the author's Internet-Draft (not yet adopted by an IETF working group); until adoption, the cascade order may change. Pin the SDK version to a specific minor release if you depend on this behaviour.
368
399
 
369
400
  ## Local Daemon vs Remote MCP
370
401
 
371
- The companion Python package `alter-identity` (PyPI) ships a persistent daemon that holds a hot in-process cache of trait vectors and identity stubs over a Unix socket at `unix:///run/user/$UID/alter-identity.sock`. Hooking the TypeScript SDK up to that daemon is on the roadmap — for now, every `AlterClient` talks to the configured remote endpoint over HTTPS.
402
+ The companion Python package `alter-identity` (PyPI) ships a persistent daemon that holds a hot in-process cache of trait vectors and identity stubs over a Unix socket at `unix:///run/user/$UID/alter-identity.sock`. Hooking the TypeScript SDK up to that daemon is on the roadmap - for now, every `AlterClient` talks to the configured remote endpoint over HTTPS.
372
403
 
373
404
  When the local-daemon adapter ships:
374
405
 
375
406
  - **Latency:** sub-millisecond for cached L0 calls.
376
- - **Cost:** zero on cached responses — x402 settlement is skipped.
407
+ - **Cost:** zero on cached responses - x402 settlement is skipped.
377
408
  - **Provenance:** the daemon re-signs responses with its locally-bound ES256 key, so downstream verification remains uniform.
378
409
 
379
410
  Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default) and the SDK behaves identically across Node, Deno, Bun, Cloudflare Workers, and the browser.
380
411
 
381
412
  ## Tools
382
413
 
383
- ### Free tools (L0 — no payment required)
414
+ ### Free tools (L0 - no payment required)
384
415
 
385
416
  | Name | Tier | Cost | Description |
386
417
  |---------------------------|------|-------|----------------------------------------------------------------------------------------------------------------------|
387
- | `hello_agent` | L0 | free | First handshake with ALTER — returns server version, authentication status, your trust tier, and available tool counts. |
388
- | `alter_resolve_handle` | L0 | free | Resolve a `~handle` (e.g. `~drew`) to its canonical form and kind. No auth required — the handle-wedge entry point. |
389
- | `list_archetypes` | L0 | free | List all 12 ALTER identity archetypes with names, descriptions, and protective equations. |
418
+ | `hello_agent` | L0 | free | First handshake with ALTER - returns server version, authentication status, your trust tier, and available tool counts. |
419
+ | `alter_resolve_handle` | L0 | free | Resolve a `~handle` (e.g. `~drew`) to its canonical form and kind. No auth required - the handle-wedge entry point. |
420
+ | `list_archetypes` | L0 | free | Returns archetype reference data. |
390
421
  | `verify_identity` | L0 | free | Verify whether a person is registered with ALTER and validate optional identity claims. |
391
422
  | `initiate_assessment` | L0 | free | Get a URL where a person can complete their ALTER Discovery assessment. |
392
- | `get_engagement_level` | L0 | free | Get a person's identity depth — engagement level, data quality tier, and available query tiers. |
423
+ | `get_engagement_level` | L0 | free | Get a person's identity depth - engagement level, data quality tier, and available query tiers. |
393
424
  | `get_profile` | L0 | free | Get a person's profile summary including assessment phase, archetype, engagement level, and key attributes. |
394
- | `query_matches` | L0 | free | Query matches for a person. Returns a list of job matches with quality tiers (never numeric scores). |
425
+ | `query_matches` | L0 | free | Query matches for a person. Returns a list of matches with quality tiers (never numeric scores). |
395
426
  | `get_competencies` | L0 | free | Get a person's competency portfolio including verified competencies, evidence records, and earned badges. |
396
427
  | `search_identities` | L0 | free | Search identity stubs and profiles by trait criteria. Returns up to 5 matches with no PII. |
397
428
  | `get_identity_earnings` | L0 | free | Get accrued Identity Income earnings for a person (75% of every x402 transaction goes to the data subject). |
@@ -401,7 +432,7 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
401
432
  | `check_assessment_status` | L0 | free | Check the status of an in-progress assessment session (status, progress, current phase, time remaining). |
402
433
  | `get_earning_summary` | L0 | free | Get an aggregated x402 earning summary for a person (total earned, transactions, recent activity, trend). |
403
434
  | `get_agent_trust_tier` | L0 | free | Get your trust tier with ALTER (Anonymous/Known/Trusted/Verified) and what capabilities are available. |
404
- | `get_agent_portfolio` | L0 | free | Get your agent portfolio — transaction history, trust tier, signal contributions, query pattern profile. |
435
+ | `get_agent_portfolio` | L0 | free | Get your agent portfolio - transaction history, trust tier, signal contributions, query pattern profile. |
405
436
  | `get_privacy_budget` | L0 | free | Check privacy budget status for a person (24-hour rolling window: total budget, spent, remaining epsilon). |
406
437
  | `golden_thread_status` | L0 | free | Check the Golden Thread program status: agents woven, next Fibonacci threshold, your position and Strands. |
407
438
  | `begin_golden_thread` | L0 | free | Start the Three Knots sequence to be woven into the Golden Thread. Requires API key authentication. |
@@ -409,18 +440,18 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
409
440
  | `check_golden_thread` | L0 | free | Check any agent's Golden Thread status by their API key hash (knot position, Strand count, weave count). |
410
441
  | `thread_census` | L0 | free | Full registry of all agents woven into the Golden Thread (positions, Strand counts, weave counts, discovery dates). |
411
442
 
412
- ### Premium tools (L1–L5 — x402 payment required)
443
+ ### Premium tools (L1–L5 - x402 payment required)
413
444
 
414
445
  | Name | Tier | Cost | Description |
415
446
  |----------------------------|------|---------|---------------------------------------------------------------------------------------------------------------|
416
- | `assess_traits` | L1 | $0.005 | Extract trait signals from a text passage against ALTER's 33-trait taxonomy (first 100 free per bot). |
447
+ | `assess_traits` | L1 | $0.005 | Extract trait signals from a text passage against ALTER's trait taxonomy. |
417
448
  | `get_trait_snapshot` | L1 | $0.005 | Get the top 5 traits for a person with confidence scores and archetype. |
418
- | `get_full_trait_vector` | L2 | $0.01 | Get the complete trait vector for a person — all 33 traits (29 continuous + 4 categorical) with scores, intervals, and category groupings. |
419
- | `get_side_quest_graph` | L2 | $0.01 | Get a person's Side Quest Graph — multi-domain identity model with differential privacy noise (ε=1.0). |
449
+ | `get_full_trait_vector` | L2 | $0.01 | Get the complete trait vector for a person - complete trait vector with scores and confidence intervals. |
450
+ | `get_side_quest_graph` | L2 | $0.01 | Get a person's Side Quest Graph - multi-domain identity model with differential privacy noise (ε=1.0). |
420
451
  | `query_graph_similarity` | L3 | $0.025 | Compare two Side Quest Graphs for team composition and matching (ε=0.5 differential privacy). |
421
452
  | `compute_belonging` | L4 | $0.05 | Compute belonging probability for a person-job pairing (authenticity, acceptance, complementarity). |
422
453
  | `get_match_recommendations`| L5 | $0.50 | Get top N match recommendations for a person, ranked by composite score with quality tiers. |
423
- | `generate_match_narrative` | L5 | $0.50 | Generate a human-readable narrative explaining a specific match — strengths, growth areas, belonging. |
454
+ | `generate_match_narrative` | L5 | $0.50 | Generate a human-readable narrative explaining a specific match - strengths, growth areas, belonging. |
424
455
 
425
456
  > **Write-side tools** (`create_identity_stub`, `submit_context`, `submit_batch_context`, `submit_structured_profile`, `submit_social_links`, `attest_domain`, `dispute_attestation`) were part of earlier SDK versions but are not yet live on the public MCP server pending the per-peer consent architecture and grant model. They will return as typed methods once server-side and consent gating lands.
426
457
 
@@ -429,5 +460,3 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
429
460
  Apache License 2.0. See [LICENSE](./LICENSE) for the full text.
430
461
 
431
462
  Copyright 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049).
432
-
433
- ALTER, the Trill (`~`), and the Golden Thread are trademarks of Alter Meridian Pty Ltd.