[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_127":128},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":47,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":47,"_57":58,"_59":60,"_61":62,"_63":64,"_65":66,"_67":47,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":-5,"_79":-5,"_80":81,"_82":47,"_83":-5,"_84":58,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94,"_95":96},"apiUrl","https://odel.app/api","creator","true-alter","moduleId","sdk","@true-alter/sdk","displayName","~Alter Identity","tagline","Mint an agent identity in two free calls. Verify anyone. Earn 75% when someone reads you.","iconKey","https://avatars.githubusercontent.com/u/267181656?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://mcp.truealter.com/api/v1/mcp\",\"transport\":\"streamable-http\",\"authType\":\"headers\",\"requiredSecrets\":[{\"name\":\"X_ALTER_API_KEY\",\"scope\":\"per-user\",\"header\":\"X-ALTER-API-Key\"}]}","pricingModel","free","creatorUserId","system:external-import","createdAt",1788236612000,"updatedAt","sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=com.truealter%2Fidentity","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",0,"upstreamUpdatedAt",1788231530000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/true-alter/sdk","githubRepoFullName","true-alter/sdk","releaseId","ext-true-alter-sdk","version","0.5.10","descriptionMarkdown","

\n\n $\"\"$ \n\n# ~alter SDK\n\n**Read identity from your own code with the person's consent and their cut.**\n\n[![npm](https://img.shields.io/npm/v/@truealter/sdk?label=%40truealter%2Fsdk&color=C9A84C&style=flat-square)](https://www.npmjs.com/package/@truealter/sdk)\n[![Node](https://img.shields.io/badge/node-%E2%89%A518-555?style=flat-square)](#install)\n[![Runtimes](https://img.shields.io/badge/runs%20on-Node%20%7C%20Deno%20%7C%20Bun%20%7C%20Workers%20%7C%20browser-555?style=flat-square)](#install)\n[![Licence](https://img.shields.io/badge/licence-Apache--2.0-555?style=flat-square)](./LICENSE)\n\n[What is ~alter?](#what-is-alter) · [Install](#install) · [From nothing to a paid read](#from-nothing-to-a-paid-read)\n\n

\n\n## What is ~alter?\n\nMost people who read about ~Alter are here about their own identity, and you are\nnot. You are building something that has to know who its users are, which makes\nyou the party who asks, stores the answer, and carries it afterwards.\n\nThe asking is the cheap part. What comes after it is the encryption at rest, the\nretention schedule, the access review, the deletion request that arrives long\nafter they stopped using you, and the notification you send if any of it ever\nleaks. You carry all of that for data whose only source was somebody typing into\na box you built, unverified by anyone, and out of date from the day it was\nentered.\n\n~Alter is a record kept under a name the person owns, and what is in it was read\nfrom what they have done rather than typed into a form. Your code reads that\nrecord at the point it needs an answer, and holds none of it once the call\nreturns. The person decides in advance what your application is allowed to see,\nwhich puts the consent conversation on their surface rather than on yours.\n\nChecking that somebody exists costs nothing and discloses nothing past the fact\nof them. A read that goes further is priced, and three quarters of what you pay\nfor it reaches the person whose record was read. You are buying an answer for as\nlong as you need it rather than taking custody of one.\n\n

I want to know more

Your friends do not know you from a login. Neither does your family, or the people you work with, or your sports team. They know who you are from how you have shown up, over years. You may look and sound nothing like you did ten years ago and it is still you.

Software still asks the narrow question. A password at the login screen. A token in the app. Each one checks whether this is the right person, right now, at this exact spot, and then looks away. Everything in between is invisible to it, and that is almost all of your life. The AI tools made it worse, because one of them writes in your name now, and when somebody asks who allowed it, there is no answer anywhere on this machine.

One name, and the record under it is yours. ~yourname works at every tool that speaks the protocol, so nothing is set up twice and there is no key to paste, at any point. What is in the record was read from what you did, not typed into a box by you or guessed at by a model. You can cut off access to any of it with one command. No form, no review.

Being read pays you. Anyone can check for free that your handle exists. Reading further, past the fact of you, costs the reader money, that money goes to you, and you decide who gets to read what. Collectives hold a record on the same terms, because it is one record at every scale and the same form holds you, your team, and your country. A union, a club, a trade body, or a group of people who have never met can vouch for their own members and be read the same way you are.

Threads are how you get somewhere. A thread is something you are working towards. You take one on yourself, or ~Alter plants one from what it can already see, or a collective confers one on you. What gets read is the trail you leave while you are doing it, never a certificate at the end.

All of that is the short version of an argument set out properly, in eight chapters at truealter.com/origin. Its seventy-six predictions were each written so the data could come back and say no. Five of them did, and those five are still published alongside the rest.

\n\n

I want to check it myself

\n\nNone of it needs taking on trust. Hand this to the AI you already use and\nlet it take you through in your own words.\n\n```text\nGo to truealter.com, find the genesis and the origin papers, and read all of\nthem. Then start a discussion with me in my own language, no jargon.\n\nAsk me one question at a time and wait for my answer. Follow what I am curious\nabout, not the order the site is written in.\n\nDo not only read the pages. Connect to their interface directly and call\nget_started. That tells you where I am and what comes next, and we work the\nrest of this from there.\n\nIf I have a ~handle I will give it to you. If I do not and I decide I want\none, set it up with me here.\n\nWhat I want to understand is what ~Alter is, how it applies to me, and what it\nmeans for everyone else. Find me somewhere in it, and not the version written\nfor people who work in technology. Find the life nearest mine and walk me\nthrough it, including what it would cost me.\n\nTry to prove them wrong. Go and find where they show their working, and if\nsomething is unclear or does not hold up, say so.\n```\n\n

\n\n## What is ~alter SDK?\n\nIt's a typed TypeScript client for that record, so your code can ask whether a\nhandle exists, read the traits the person has consented to share with you, and\nsettle a deeper read in USDC.\n\nThe front door is [`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli),\nwhich is how somebody gets a handle in the first place and which carries the MCP\nbridge. This package is what your application imports once they already have one.\n\nUnderneath, it's a thin client over ~Alter's MCP server, speaking MCP spec\n`2025-11-25` over Streamable HTTP and JSON-RPC 2.0. It carries x402 settlement\nand ES256 provenance verification, it depends on `@noble/ed25519` and\n`@noble/hashes` and nothing else, and it ships both ESM and CJS.\n\nForty-seven tools are publicly advertised, and thirty-eight of those sit on the\nfree tier. Free is not the same as open. Twelve of the forty-seven answer a\ncaller holding no credential at all, and everything that reads an identity wants\na `~handle` first.\n\nYour IAM stack answers who's logged in. It can sit on top of this without\nchanging.\n\n## Install\n\n```\nnpm install @truealter/sdk\n```\n\nNode 18 or newer. It also runs on Deno, Bun, Cloudflare Workers and modern\nbrowsers, and it brings no wallet dependency of its own.\n\n

The stdio bridge in here, and why not to build on it

\n\n

This package also ships a stdio bridge at bin/mcp-bridge.ts, built to dist/bin/mcp-bridge.js, which the alter CLI launches by file path through its mcp-bridge subcommand. It is a dev and demo surface for dropping ~Alter into MCP hosts that speak stdio, and it handles the handshake, tools/list and free tool calls.

It does not carry ES256 per-invocation signing, so authenticated tools fail at the server edge when they are reached through it. Import the SDK directly and construct an MCPClient or AlterClient with the optional signing parameter instead. That path carries the provenance envelope end to end and is the one to build on. Bridge signing is planned.

There is no command-line binary in this package. The bridge entrypoint is not a published bin, and alter --help is the inline reference for the command line, which is distributed separately.

\n\n## From nothing to a paid read\n\nStep one runs with nothing at all. From step two you need a `~handle`, which\ncosts nothing and needs no human account, and the short section between the two\nis how you mint one. The paid step at the end is the only one that costs money,\nand it's the only one that pays anybody.\n\n### 1. Connect with nothing\n\n```ts\nimport { AlterClient } from \"@truealter/sdk\";\n\nconst alter = new AlterClient();\n```\n\nThe default endpoint is `https://mcp.truealter.com/api/v1/mcp`. Every free tool\nanswers an anonymous client. The working example at\n[`examples/hello-agent/`](https://github.com/true-alter/sdk/blob/main/examples/hello-agent/) connects with no credential\nat all.\n\n### Before step two, mint a `~handle`\n\nTwelve tools answer a caller holding no credential, and they're the discovery\nand registration surface rather than the free tier. Everything that reads an\nidentity needs a `~handle`, and so does anything acting on your own. An agent\nmints its own over MCP with `register_autonomous` and\n`register_autonomous_challenge`, neither of which costs anything or wants a\nhuman account behind it. A person runs `alter login` once, which writes the\nmember credential into `~/.config/alter/session.json`. Either way the hosted\nendpoint is bearer-first, so the CLI bridge reads that session for you and there\nisn't a key to mint or paste at any point. Constructing a client yourself, pass\nthe same session credential as the optional `apiKey`.\n\n### 2. Ask whether somebody is known\n\n```ts\nconst verified = await alter.verify(\"~alter\");\n```\n\nA handle, an email or an id. This is the check that costs nothing and reveals\nnothing beyond the fact of the person, which is the free tier by design.\n\n### 3. Read what they have consented to share\n\n```ts\nconst depth = await alter.getEngagementLevel({ member_id });\nconst matches = await alter.searchIdentities({\n trait_criteria: {\n pressure_response: { min: 0.7 },\n cognitive_flexibility: { min: 0.6 },\n },\n});\n```\n\nDepth tells you how much of a record exists and which tiers are open to you.\nTrait search returns at most five results and no personally identifying data.\n\n### 4. Check that the answer really came from ~Alter\n\n```ts\nconst check = await alter.verifyProvenance(result._meta?.provenance);\nif (!check.valid) throw new Error(`provenance failed: ${check.reason}`);\n```\n\nEvery medium- and high-sensitivity response is signed with ES256. Verification\nis opt-in and offline against published keys, so an agent that forwards a\nresult to another agent can be checked without anyone contacting ~Alter again.\n\n### 5. Pay for a deeper read, and pay the person\n\n```ts\nimport { AlterClient, X402Client } from \"@truealter/sdk\";\n\nconst alter = new AlterClient({\n x402: new X402Client({\n signer: yourViemOrEthersSigner,\n networks: [\"base\"],\n assets: [\"USDC\"],\n maxPerQuery: \"0.10\",\n }),\n});\n\nconst vector = await alter.getFullTraitVector({ member_id });\n```\n\nThe server answers `402`, the SDK settles on Base and retries, and the split\nruns on-chain in the same transaction. The majority of it goes to the person\nwhose record was read, as Identity Income, and it reaches them directly rather\nthan through anybody holding it first. Bring your own signer; there is no wallet\nin this package on purpose.\n\nIf a quote exceeds `maxPerQuery`, or names a network or asset you did not\nallow, the SDK refuses before the signer is ever called and nothing is\nbroadcast.\n\nEverything below is closed by default. The first two are what you open while\nyou are wiring it up, the next four are how the payment, the signatures and the\ndiscovery actually work, and the last two are the reading and the project.\n\n

The API in full

\n\n#### Initialise the client\n\n```ts\nimport { AlterClient, X402Client } from \"@truealter/sdk\";\n\nconst alter = new AlterClient({\n endpoint: \"https://mcp.truealter.com/api/v1/mcp\", // optional, this is the default. A bare host returns 405\n x402: new X402Client({ // optional, only for paid reads\n signer: yourViemOrEthersSigner,\n maxPerQuery: \"0.10\",\n }),\n});\n```\n\n**Authentication**\n\nThe client above is anonymous, and every free L0 tool answers with no\ncredential. For tools that act on your own identity (standing requirements,\nthe Golden Thread, member self-writes), run `alter login` once: it provisions\nyour member credential into the local session\n(`~/.config/alter/session.json`). The hosted endpoint is bearer-first, so the\n[`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli) bridge reads\nthat session credential for you; you never mint or paste a key. If you\nconstruct a client yourself, pass that same session credential as the optional\n`apiKey` option.\n\n#### The minimum-version floor\n\n~Alter's backend publishes a minimum version per client and enforces it at the\nedge. A client below the floor is answered with HTTP 426 and the response body\ncarries the upgrade command. The floor document is signed with a floor-only\nEd25519 key, so no signing secret ships in any client and a compromised client\ncannot forge one.\n\nThis SDK does not preflight that floor. There is no typed below-floor error\nhere, so a 426 arrives the way any other unhandled status does, as an\n`AlterError` with code `NETWORK` whose message carries the status and the first\n200 characters of the body. The typed preflight lives in `@truealter/cli`,\nwhich verifies the floor document's signature before it trusts a floor.\n\n```ts\nimport { AlterClient, AlterError } from \"@truealter/sdk\";\n\nconst alter = new AlterClient();\ntry {\n await alter.verify(\"~alter\");\n} catch (err) {\n if (err instanceof AlterError && err.message.includes(\"HTTP 426\")) {\n console.error(`upgrade required: ${err.message}`);\n process.exit(1);\n }\n throw err;\n}\n```\n\nPin the version you build against and upgrade deliberately. A typed preflight\nbelongs in this SDK and is not written yet.\n\n#### Identity headers\n\nEvery outbound request from `AlterClient` / `MCPClient` carries three\nidentity headers that the server-side floor middleware consults:\n\n| Header | Value (this SDK) |\n| -------------------------- | ------------------ |\n| `X-Alter-Client-Id` | `alter-identity` |\n| `X-Alter-Client-Version` | the running `SDK_VERSION` |\n| `X-Alter-Client-Channel` | `npm` |\n\nThese are MANDATORY on every authenticated backend endpoint so the\nserver can enforce its minimum supported client version. The User-Agent\nheader remains informational and is NEVER used for floor enforcement.\n\n#### Free reads, L0, no payment\n\n```ts\n// Verify a registered identity by handle, email, or id\nconst verified = await alter.verify(\"~alter\");\nconst verifiedById = await alter.verify(\n \"550e8400-e29b-41d4-a716-446655440000\",\n {\n archetype: \"weaver\",\n min_engagement_level: 3,\n traits: { pressure_response: { min: 0.6 } },\n },\n);\n\n// Reference data, the 12 ~Alter archetypes\nconst archetypes = await alter.listArchetypes();\n\n// Identity depth and available tool tiers\nconst depth = await alter.getEngagementLevel({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n});\n\n// Search by trait criteria. No PII exposed, max 5 results\nconst matches = await alter.searchIdentities({\n trait_criteria: {\n pressure_response: { min: 0.7 },\n cognitive_flexibility: { min: 0.6 },\n },\n});\n\n// Golden Thread program status\nconst thread = await alter.goldenThreadStatus();\n```\n\n#### Paid reads, L1 to L5, settled with x402\n\n```ts\n// L1, extract trait signals from text ($0.01, first 100 free per bot)\nconst signals = await alter.assessTraits({\n text: \"I led the incident response when our payment rails went down...\",\n context: \"interview transcript\",\n});\n\n// L2, the full 30-trait vector ($0.10)\nconst vector = await alter.getFullTraitVector({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n});\n\n// L4, belonging probability for a person-job pairing ($0.60)\nconst belonging = await alter.computeBelonging({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n job_id: \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n});\n\n// L5, top match recommendations ($1.00)\nconst recommendations = await alter.getMatchRecommendations({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n limit: 5,\n});\n\n// L5, a human-readable narrative explaining a match ($1.00)\nconst narrative = await alter.generateMatchNarrative({\n match_id: \"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n});\n```\n\n#### Provenance verification\n\n```ts\n// Every medium- and high-sensitivity response is signed with ES256.\n// Verification is opt-in. Call alter.verifyProvenance(...) yourself.\nconst result = await alter.getFullTraitVector({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n});\n\nconst check = await alter.verifyProvenance(result._meta?.provenance);\nif (!check.valid) throw new Error(`provenance failed: ${check.reason}`);\n\n// Verify that schema hashes published in tools/list._meta.signatures\n// match the local representation of each tool.\nconst tools = await alter.mcp.listTools();\nconst sigs = tools._meta?.signatures ?? {};\nconst results = await alter.verifyToolSignatures(tools.tools, sigs);\nconst tampered = results.filter((r) => !r.valid);\nif (tampered.length) throw new Error(`tampered tools: ${tampered.map((t) => t.tool).join(\", \")}`);\n```\n\n#### Discovery\n\n```ts\nimport { discover } from \"@truealter/sdk\";\n\n// Three-step discovery cascade: DNS TXT to mcp.json to alter.json\nconst descriptor = await discover(\"truealter.com\");\n// returns { url: \"https://mcp.truealter.com/api/v1/mcp\", transport, source, publicKey, x402Contract, capability }\n```\n\n#### Low-level MCPClient\n\n```ts\nimport { MCPClient } from \"@truealter/sdk\";\n\nconst mcp = new MCPClient({ endpoint: \"https://mcp.truealter.com/api/v1/mcp\" });\nawait mcp.initialize();\nconst tools = await mcp.listTools();\nconst response = await mcp.callTool(\"verify_identity\", {\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n});\n```\n\n

\n\n

Generating MCP client config

\n\nThe SDK ships config generators for the major MCP-aware clients. Each emits a JSON snippet you can paste (or write directly) into the appropriate file.\n\n#### Claude Code (`.mcp.json`)\n\n```ts\nimport { generateClaudeConfig } from \"@truealter/sdk\";\nimport { writeFileSync } from \"node:fs\";\n\nconst config = generateClaudeConfig({\n endpoint: \"https://mcp.truealter.com/api/v1/mcp\",\n});\n\nwriteFileSync(\".mcp.json\", JSON.stringify(config, null, 2));\n```\n\nResulting `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"alter\": {\n \"url\": \"https://mcp.truealter.com/api/v1/mcp\",\n \"transport\": \"streamable-http\",\n \"description\": \"~Alter Identity - psychometric identity field for AI agents\"\n }\n }\n}\n```\n\nThis config reaches every free L0 tool anonymously. For authenticated\naccess, run `alter login` and let the CLI write the config\n(`alter config`); the bearer-first bridge then carries your session\ncredential, so no key sits in the file.\n\n#### Cursor (`.cursor/mcp.json`)\n\n```ts\nimport { generateCursorConfig } from \"@truealter/sdk\";\nimport { writeFileSync } from \"node:fs\";\n\nconst config = generateCursorConfig({\n endpoint: \"https://mcp.truealter.com/api/v1/mcp\",\n});\n\nwriteFileSync(\".cursor/mcp.json\", JSON.stringify(config, null, 2));\n```\n\n#### Generic MCP client\n\n```ts\nimport { generateGenericMcpConfig } from \"@truealter/sdk\";\n\nconst config = generateGenericMcpConfig({\n endpoint: \"https://mcp.truealter.com/api/v1/mcp\",\n serverName: \"alter\", // editor-specific key under mcpServers\n});\n```\n\n#### CLI\n\nThe command line lives in [`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli),\nnot in this SDK package:\n\n```\nalter init # generate keypair, discover MCP, write ~/.config/alter/identity.json\nalter config # print Claude .mcp.json snippet (default)\nalter config --cursor # print Cursor .cursor/mcp.json snippet\nalter config --generic # print generic mcpServers snippet\nalter verify ~alter # verify an identity\nalter status # show connection state and probe the endpoint\n```\n\n

\n\n

How the payment actually works

\n\n~Alter prices its deeper reads through the [x402](https://x402.org) standard, which is HTTP `402 Payment Required` with on-chain settlement.\n\n#### The retry flow\n\n1. Client calls a paid tool *without* a payment header.\n2. Server replies `402 Payment Required` with a payment requirement (amount, recipient, asset, network).\n3. Client signs and broadcasts a USDC transfer on Base L2, attaches the proof, retries.\n4. Server validates the proof, executes the tool, signs the response with ES256, returns it.\n5. 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.\n\nThe SDK handles steps 2-4 automatically when an `X402Client` with a configured `signer` is passed in.\n\n#### Tier structure\n\nx402 micropayments at L0-L5 trust tiers. Per-call pricing visible after `alter login`.\n\n#### Identity income split\n\nThe majority of every settled call flows to the data subject as Identity Income. Split details available post-authentication via `alter status`.\n\n#### Code example\n\n```ts\nimport { AlterClient, X402Client, type X402Signer } from \"@truealter/sdk\";\n\n// Bring your own signer. viem, ethers, a hardware wallet bridge, anything.\n// The SDK ships without a wallet dependency on purpose.\nconst signer: X402Signer = {\n async settle(envelope) {\n const txHash = await yourWallet.sendUsdcTransfer({\n to: envelope.recipient,\n amount: envelope.amount,\n chain: envelope.network,\n });\n return {\n reference: txHash,\n network: envelope.network,\n amount: envelope.amount,\n asset: envelope.asset,\n };\n },\n};\n\nconst alter = new AlterClient({\n endpoint: \"https://mcp.truealter.com/api/v1/mcp\",\n x402: new X402Client({\n signer,\n networks: [\"base\", \"base-sepolia\"], // policy allow-list\n assets: [\"USDC\"],\n maxPerQuery: \"0.10\", // refuse anything over $0.10 USDC\n }),\n});\n\n// Auto-retries with payment when the server returns 402\nconst vector = await alter.getFullTraitVector({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n});\n```\n\nIf 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, and no on-chain transaction is broadcast.\n\n

\n\n

Provenance, in detail

\n\nEvery response from a medium- or high-sensitivity tool ships with an ES256 JWS in `_meta.provenance`. The signature covers a canonical JSON serialisation of the response payload, the tool name, the call timestamp, the requesting agent's key hash, and a monotonic sequence number.\n\n```ts\nconst result = await alter.getFullTraitVector({\n member_id: \"550e8400-e29b-41d4-a716-446655440000\",\n});\n\nconst check = await alter.verifyProvenance(result._meta?.provenance);\nif (!check.valid) throw new Error(`~alter provenance check failed: ${check.reason}`);\n```\n\nThe SDK fetches public keys from `https://api.truealter.com/.well-known/alter-keys.json` and caches them per their `Cache-Control` headers. The endpoint returns a JWKS containing all current and recently-rotated signing keys; verifying clients should accept any key whose `kid` matches and is still within its validity window.\n\n#### `verify_at` hostname allowlist (v0.1.1+)\n\nEvery 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 gates `verify_at` through a hostname allowlist, `api.truealter.com` and `mcp.truealter.com` by default, and rejects `http://` URLs unconditionally. Downstream integrators running their own deployment can extend that allowlist, without forking the SDK, through `verifyAtAllowlist` on either `AlterClient` or a direct `verifyProvenance()` call.\n\n```ts\nimport { AlterClient, DEFAULT_VERIFY_AT_ALLOWLIST } from \"@truealter/sdk\";\n\nconst alter = new AlterClient({\n verifyAtAllowlist: [\n ...DEFAULT_VERIFY_AT_ALLOWLIST, // keep the ~Alter canonicals\n \"keys.myorg.example\", // plus your own JWKS host\n ],\n});\n```\n\nIf you pin `jwksUrl` explicitly, the envelope's `verify_at` is ignored entirely and the pinned URL wins. The `https:` scheme requirement applies to pinned URLs too.\n\n#### Why this matters\n\nProvenance 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.\n\nThis 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.\n\n

\n\n

Finding the endpoint yourself

\n\n~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 such as `truealter.com`, the SDK resolves the MCP endpoint in three steps, falling through on each failure:\n\n1. **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.\n2. **`.well-known/mcp.json`**, fetch `https://truealter.com/.well-known/mcp.json` for the standard MCP server descriptor. This is the cross-vendor fallback.\n3. **`.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.\n\n```ts\nimport { discover } from \"@truealter/sdk\";\n\n// Cascading discovery (DNS TXT to mcp.json to alter.json)\nconst descriptor = await discover(\"truealter.com\");\n\n// Skip the DNS step, in browsers or Cloudflare Workers\nconst httpsOnly = await discover(\"truealter.com\", { skipDns: true });\n```\n\nThis 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.\n\n

\n\n

The forty-seven tools

\n\n#### Free tools, L0, no payment\n\n| Name | Tier | Cost | Description |\n|---------------------------------|------|------|-------------|\n| `hello_agent` | L0 | free | First handshake with ~Alter, returning server version, authentication status, your trust tier, and available tool counts. |\n| `get_started` | L0 | free | Cold-start overview: what ~Alter is, how to authenticate, and which tool tiers are available to you. |\n| `list_archetypes` | L0 | free | Returns archetype reference data. |\n| `alter_resolve_handle` | L0 | free | Resolve a `~handle` such as `~example` to its canonical form and kind. No auth required, the handle-wedge entry point. |\n| `verify_identity` | L0 | free | Verify whether a person is registered with ~Alter and validate optional identity claims. |\n| `register_autonomous_challenge` | L0 | free | Issue a proof-of-work challenge to begin keyless self-registration as an owner-less ~Alter principal, with no human account needed. |\n| `register_autonomous` | L0 | free | Complete keyless self-registration by submitting a solved proof-of-work challenge, minting an owner-less `~handle` and a one-time agent key. |\n| `alter_presence_read` | L0 | free | Read whether a `~handle` is publicly open, the shop-front sign. Returns open or closed only; the closed reason is never disclosed. |\n| `alter_resolve_by_key` | L0 | free | Resolve a paired third-party key (email or OAuth user-id) to its bound `~handle`, gated by the member's per-stream resolver opt-in. |\n| `get_engagement_level` | L0 | free | Get a person's identity depth, meaning engagement level, data quality tier, and available query tiers. |\n| `get_profile` | L0 | free | Get a person's profile summary including assessment phase, archetype, engagement level, and key attributes. |\n| `query_matches` | L0 | free | Query matches for a person. Returns a list of matches with quality tiers (never numeric scores). |\n| `get_competencies` | L0 | free | Get a person's competency portfolio including verified competencies, evidence records, and earned badges. |\n| `create_identity_stub` | L0 | free | Create an anonymous identity stub for a person who has not yet completed Discovery, which they claim later. Present the privacy notice first. |\n| `search_identities` | L0 | free | Search identity stubs and profiles by trait criteria. Returns up to 5 matches with no PII. |\n| `create_requirement` | L0 | free | Post a standing identity-trait requirement that rests as an order and accumulates fills as matching identities are claimed or updated. |\n| `demand_board` | L0 | free | Read the public board's both sides, resting identity requirements and resting offers, with no account needed to read either. |\n| `list_requirements` | L0 | free | List your own standing requirements, with fill counts and the number of fills not yet delivered. Requires an authenticated member credential (`alter login`). |\n| `get_requirement` | L0 | free | Read one of your standing requirements by id, with its fill and undelivered-fill counts. Requires an authenticated member credential (`alter login`). |\n| `cancel_requirement` | L0 | free | Cancel one of your standing requirements by id; the order stops resting and accepts no further fills. Requires an authenticated member credential (`alter login`). |\n| `create_offer` | L0 | free | Post a signed, expiring offer of goods, services, capabilities or outcomes against your own `~handle`, at a price and admission bar you set yourself. |\n| `list_offers` | L0 | free | List your own resting offers; a withdrawn offer never appears here. |\n| `get_offer` | L0 | free | Read one of your resting offers by id; a withdrawn offer returns not found, the same as one that never existed. |\n| `withdraw_offer` | L0 | free | Withdraw one of your resting offers by id, stopping it from resting immediately rather than merely flagging it. |\n| `list_plugins` | L0 | free | Browse the published community plugin directory of third-party capabilities built on ~Alter, with an optional category filter. |\n| `submit_plugin` | L0 | free | File a plugin submission to the community directory for operator review, attributed to your own bound `~handle`. |\n| `get_identity_earnings` | L0 | free | Get accrued Identity Income earnings for a person (75% of every x402 transaction goes to the data subject). |\n| `get_network_stats` | L0 | free | Get aggregate ~Alter network statistics: total identities, verified profiles, query volume, active bots. |\n| `get_identity_trust_score` | L0 | free | Get the trust score for an identity based on query diversity (unique querying agents / total queries). |\n| `get_privacy_budget` | L0 | free | Check privacy budget status for a person (24-hour rolling window: total budget, spent, remaining epsilon). |\n| `dispute_attestation` | L0 | free | Record a dispute against a competence attestation; if disputes exceed corroborations, the attestation is flagged for review. |\n| `golden_thread_status` | L0 | free | Check the Golden Thread program status: agents woven, next Fibonacci threshold, your position and Strands. |\n| `begin_golden_thread` | L0 | free | Start the Three Knots sequence to be woven into the Golden Thread. Requires an authenticated member credential (`alter login`). |\n| `complete_knot` | L0 | free | Submit completion data for a knot in the Three Knots sequence (1: register, 2: describe, 3: reflect). |\n| `check_golden_thread` | L0 | free | Check any agent's Golden Thread status by their credential hash (knot position, Strand count, weave count). |\n| `describe_traits` | L0 | free | List the canonical trait vocabulary: trait codes grouped by category with one-line semantics, the valid discovery contexts, and the EU AI Act Art 5(1)(d) workforce gating rules. Read this before composing `query_field` trait_priorities. |\n| `describe_competencies` | L0 | free | List the published competency vocabulary, grouped by how each claim is denominated, as reference before composing `query_field` competency_requirements. |\n\n#### Paid tools, L1 to L5, settled with x402\n\n| Name | Tier | Cost | Description |\n|-----------------------------|------|-------|-------------|\n| `get_trait_snapshot` | L1 | $0.01 | Get the top 5 traits for a person with confidence scores and archetype. |\n| `attest_domain` | L1 | $0.01 | Record a competence attestation for a person in a specific domain, weighted by your agent reputation. |\n| `poll_requirement_matches` | L1 | $0.01 | Collect one recorded fill for a standing requirement as a priced identity reveal; 75% of the fee is paid to that person as Identity Income. |\n| `get_full_trait_vector` | L2 | $0.10 | Get the complete trait vector for a person, with scores and confidence intervals. |\n| `get_side_quest_graph` | L2 | $0.10 | Get a person's Side Quest Graph, a multi-domain identity model with differential privacy noise (ε=1.0). |\n| `query_graph_similarity` | L3 | $0.30 | Compare two Side Quest Graphs for team composition and matching (ε=0.5 differential privacy). |\n| `compute_belonging` | L4 | $0.60 | Compute belonging probability for a person-job pairing (authenticity, acceptance, complementarity). |\n| `get_match_recommendations` | L5 | $1.00 | Get top N match recommendations for a person, ranked by composite score with quality tiers. |\n| `generate_match_narrative` | L5 | $1.00 | Generate a human-readable narrative explaining a specific match, covering strengths, growth areas and belonging. |\n| `query_field` | L5 | $1.00 | Query the identity field by situation, not by name: weight 3 to 7 traits and rank the opted-in field. One call reveals one top-ranked member; that member earns 75% as Identity Income. Zero-match reveals nothing and charges nothing. |\n\n> **Member self-write tools** (`submit_context`, `submit_batch_context`, `submit_structured_profile`, `submit_social_links`) are live but member-self-scoped: a member calls them on their own identity with an authenticated member credential (`alter login`). They are not anonymously discoverable, so they do not appear in the advertised tool list above.\n\n

\n\n

The papers underneath it

\n\n~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.\n\n| Paper | Title | DOI |\n|-------|-------|-----|\n| I | *Jus Identitatis: Toward Post-Geographic Sovereignty* | [10.6084/m9.figshare.31794784](https://doi.org/10.6084/m9.figshare.31794784) |\n| II | *Identity as Inference: A Predictive Processing Account of Psychometric Measurement and Civic Belonging* | [10.6084/m9.figshare.31804222](https://doi.org/10.6084/m9.figshare.31804222) |\n| III | *Identity at Every Scale: Recursive Self-Modelling and the Dissolution of the Composition Problem* | [10.6084/m9.figshare.31812955](https://doi.org/10.6084/m9.figshare.31812955) |\n| IV | *Generative Psychometrics: Measurement Theory for Self-Reflective Constructs* | [10.6084/m9.figshare.31812982](https://doi.org/10.6084/m9.figshare.31812982) |\n| V | *Social Free Energy: A Formal Theory of Polity* | [10.6084/m9.figshare.31813000](https://doi.org/10.6084/m9.figshare.31813000) |\n| VI | *The Self-Model Test: A Measurement Protocol for Synthetic Self-Models* | [10.6084/m9.figshare.31813006](https://doi.org/10.6084/m9.figshare.31813006) |\n| VII | *Empirical Validation of Identity as Inference Predictions* | [10.6084/m9.figshare.31951644](https://doi.org/10.6084/m9.figshare.31951644) |\n| VIII | *Identity Field Theory: Toward a Physics of Being Known* | [10.6084/m9.figshare.31951383](https://doi.org/10.6084/m9.figshare.31951383) |\n\nFor the lay-register chapter version, see [`/origin`](https://truealter.com/origin).\n\n

The protocols underneath it

\n\nThe record formats are open Internet-Drafts, so somebody else's implementation reads and writes the same records this one does without asking us. These are the drafts this repository actually rests on.\n\n| Draft | What it specifies |\n|---|---|\n| [`mcp-dns-discovery`](https://datatracker.ietf.org/doc/draft-morrison-mcp-dns-discovery/) | The DNS records that publish a `~handle`, the server that answers for it, and the signed envelope bound to it. |\n| [`consent-settlement`](https://datatracker.ietf.org/doc/draft-morrison-consent-settlement/) | Binding a paid read of somebody's identity to their own recorded consent, and settling part of that payment to them. |\n| [`mcp-tool-surface-names-registry`](https://datatracker.ietf.org/doc/draft-morrison-mcp-tool-surface-names-registry/) | An IANA registry for MCP tool surface names, so the names other drafts register have somewhere to go. |\n| [`solo-agent-earn-registration`](https://datatracker.ietf.org/doc/draft-morrison-solo-agent-earn-registration/) | How an agent with no human behind it registers as an economic principal and becomes eligible to be paid. |\n\nEighteen drafts make up the whole stack. The rest are on the [IETF datatracker](https://datatracker.ietf.org/doc/search/?name=draft-morrison&activedrafts=on).\n\n

\n\n

The rest of it

\n\n`~alter` is one identity rail with several ways in, and this package is the one\nfor code.\n\n| Name | What it is |\n|---|---|\n| **[`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli)** | The command line, and the front door for a person. |\n| **[homebrew-tap](https://github.com/true-alter/homebrew-tap)** | That command line, packaged for macOS and Linux. |\n| **[runtime](https://github.com/true-alter/runtime)** | The daemon that keeps your `~handle` known on your own machine. |\n| **sdk** | Reading identity from your own code. **You are here.** |\n| **[obsidian](https://github.com/true-alter/obsidian)** | ~Alter inside an Obsidian vault, on-device. |\n| **[mcp-ollama](https://github.com/true-alter/mcp-ollama)** | Local models, for work that should stay on the machine it runs on. |\n\n| Where to read more | |\n|---|---|\n| Website | [truealter.com](https://truealter.com) |\n| The reasoning behind it | [truealter.com/origin](https://truealter.com/origin) |\n| Getting started | [truealter.com/build](https://truealter.com/build) |\n| What the tools do | [truealter.com/docs/mcp/tools](https://truealter.com/docs/mcp/tools) |\n| The open specifications | [the draft stack](https://datatracker.ietf.org/doc/search/?name=draft-morrison&activedrafts=on) |\n\nBug reports and small patches are welcome, see\n[CONTRIBUTING.md](https://github.com/true-alter/sdk/blob/main/CONTRIBUTING.md). Security reports go to\nsecurity@truealter.com and never a public issue, with scope and the disclosure\npolicy in [SECURITY.md](https://github.com/true-alter/sdk/blob/main/SECURITY.md).\n\nApache-2.0. Copyright 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049).\n\n

\n\n---\n\n

\n\n_{~alter is identity infrastructure. Your name is ~yourname and claiming one is free.}\n\n_{\nWebsite · \nDocs · \nThe argument in eight chapters · \nThe open specifications · \nEvery repository\n}\n\n

\n","changelogMarkdown","videoKey","requiredSecretsJson","[{\"name\":\"X_ALTER_API_KEY\",\"scope\":\"per-user\",\"header\":\"X-ALTER-API-Key\"}]","publishedAt","priceCents","trialDays","iconType","image","upstream",{"_115":116,"_117":118,"_119":120,"_121":122,"_123":124,"_125":126},"requiredSecrets",[108],"tags",[99,100,101,102,103,104,105,106,107],"assets",[],"stats",{"_97":58,"_98":58},"ratingAvg","reviewCount","agent-identity","agent-payments","agent-skills","anthropic-skills","autonomous-agents","identity","skill-md-skillsmp","usdc","x402",{"_109":110,"_111":112,"_113":114},"name","X_ALTER_API_KEY","scope","per-user","header","X-ALTER-API-Key","topics",[99,100,101,102,103,104,105,106,107],"license","Apache-2.0","language","TypeScript","registryName","com.truealter/identity","homepage","https://truealter.com","packages",[],"ENV",{"_129":130,"_131":132,"_133":134},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]