Public source for `@truealter/sdk`. This repository is the public reference for the SDK that ships on npm. File issues here. Pull requests are welcome and are incorporated into tagged releases.

@truealter/sdk

A TypeScript and JavaScript client for the ~Alter identity field: verify a person is known, query inferred traits, and settle premium calls in USDC.

Install: npm install @truealter/sdk Publish channel: the SDK ships on npm as @truealter/sdk. This repository is its public source; PRs and issues are welcome here and are incorporated into tagged releases.

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.

• Branded host: https://mcp.truealter.com (serves .well-known/mcp.json for discovery)
• JSON-RPC wire endpoint: https://mcp.truealter.com/api/v1/mcp - this is what Streamable HTTP POSTs target (the SDK default)
• Wire protocol: Streamable HTTP, JSON-RPC 2.0, MCP 2025-11-25 (server negotiates 2025-06-18 + 2025-03-26 for backwards-compatible clients)
• Tools: 36 typed and wired, 27 free (L0) + 9 premium (L1 to L5). Every advertised name has a matching server handler at mcp.truealter.com/api/v1/mcp.
• Runtime: Node 18+, Deno, Bun, Cloudflare Workers, modern browsers
• Crypto: @noble/ed25519 + @noble/hashes (no other dependencies)
• Bundle: ESM + CJS dual output

Quickstart

npm i @truealter/sdk

import { AlterClient } from "@truealter/sdk";

const alter = new AlterClient();
const verified = await alter.verify("~alter");

Why ~alter is not IAM

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.

Theoretical Foundation

~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.

For the lay-register chapter version, see /origin.

API

Initialise the client

import { AlterClient, X402Client } from "@truealter/sdk";

const alter = new AlterClient({
  endpoint: "https://mcp.truealter.com/api/v1/mcp", // optional - this is the default; bare host returns 405
  apiKey: process.env.ALTER_API_KEY,     // optional for free tier
  x402: new X402Client({                  // optional - only required for premium tools
    signer: yourViemOrEthersSigner,
    maxPerQuery: "0.10",
  }),
});

Free tier (L0 - no payment required)

// Verify a registered identity by handle, email, or id
const verified = await alter.verify("~alter");
const verifiedById = await alter.verify(
  "550e8400-e29b-41d4-a716-446655440000",
  {
    archetype: "strategist",
    min_engagement_level: 3,
    traits: { pressure_response: { min: 0.6 } },
  },
);

// Reference data - the 12 ~alter archetypes
const archetypes = await alter.listArchetypes();

// Identity depth and available tool tiers
const depth = await alter.getEngagementLevel({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
});

// Search by trait criteria - no PII exposed, max 5 results
const matches = await alter.searchIdentities({
  trait_criteria: {
    pressure_response: { min: 0.7 },
    cognitive_flexibility: { min: 0.6 },
  },
});

// Golden Thread program status
const thread = await alter.goldenThreadStatus();

Premium tier (L1 to L5, x402 payment required)

// L1 - Extract trait signals from text
const signals = await alter.assessTraits({
  text: "I led the incident response when our payment rails went down...",
  context: "interview transcript",
});

// L2 - Full trait vector
const vector = await alter.getFullTraitVector({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
});

// L4 - Belonging probability for a person-job pairing
const belonging = await alter.computeBelonging({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
  job_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
});

// L5 - Top match recommendations
const recommendations = await alter.getMatchRecommendations({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
  limit: 5,
});

// L5 - Human-readable narrative explaining a match
const narrative = await alter.generateMatchNarrative({
  match_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
});

Provenance verification

// Every medium- and high-blast-radius response is signed with ES256.
// Verification is opt-in - call alter.verifyProvenance(...) yourself.
const result = await alter.getFullTraitVector({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
});

const check = await alter.verifyProvenance(result._meta?.provenance);
if (!check.valid) throw new Error(`provenance failed: ${check.reason}`);

// Verify that schema hashes published in tools/list._meta.signatures
// match the local representation of each tool.
const tools = await alter.mcp.listTools();
const sigs = tools._meta?.signatures ?? {};
const results = await alter.verifyToolSignatures(tools.tools, sigs);
const tampered = results.filter((r) => !r.valid);
if (tampered.length) throw new Error(`tampered tools: ${tampered.map((t) => t.tool).join(", ")}`);

Discovery

import { discover } from "@truealter/sdk";

// Three-step discovery cascade: DNS TXT → mcp.json → alter.json
const descriptor = await discover("truealter.com");
// → { url: "https://mcp.truealter.com/api/v1/mcp", transport, source, publicKey, x402Contract, capability }

Low-level MCPClient

import { MCPClient } from "@truealter/sdk";

const mcp = new MCPClient({ endpoint: "https://mcp.truealter.com/api/v1/mcp" });
await mcp.initialize();
const tools = await mcp.listTools();
const response = await mcp.callTool("verify_identity", {
  member_id: "550e8400-e29b-41d4-a716-446655440000",
});

MCP Config Generation

The SDK ships config generators for the major MCP-aware clients. Each emits a JSON snippet you can drop into (or write directly to) the appropriate file.

Claude Code (.mcp.json)

import { generateClaudeConfig } from "@truealter/sdk";
import { writeFileSync } from "node:fs";

const config = generateClaudeConfig({
  endpoint: "https://mcp.truealter.com/api/v1/mcp",
  apiKey: process.env.ALTER_API_KEY,
});

writeFileSync(".mcp.json", JSON.stringify(config, null, 2));

Resulting .mcp.json:

{
  "mcpServers": {
    "alter": {
      "url": "https://mcp.truealter.com/api/v1/mcp",
      "transport": "streamable-http",
      "description": "~Alter, psychometric identity field for AI agents",
      "headers": {
        "X-ALTER-API-Key": "ak_..."
      }
    }
  }
}

Cursor (.cursor/mcp.json)

import { generateCursorConfig } from "@truealter/sdk";
import { writeFileSync } from "node:fs";

const config = generateCursorConfig({
  endpoint: "https://mcp.truealter.com/api/v1/mcp",
  apiKey: process.env.ALTER_API_KEY,
});

writeFileSync(".cursor/mcp.json", JSON.stringify(config, null, 2));

Generic MCP client

import { generateGenericMcpConfig } from "@truealter/sdk";

const config = generateGenericMcpConfig({
  endpoint: "https://mcp.truealter.com/api/v1/mcp",
  apiKey: process.env.ALTER_API_KEY,
  serverName: "alter", // editor-specific key under mcpServers
});

x402 Micropayments

~alter monetises premium tools via the x402 standard, HTTP 402 Payment Required with on-chain settlement.

The retry flow

1. Client calls a premium tool without a payment header.
2. Server replies 402 Payment Required with a payment requirement (amount, recipient, asset, network).
3. Client signs and broadcasts a USDC transfer on Base L2, attaches the proof, retries.
4. Server validates the proof, executes the tool, signs the response with ES256, returns it.
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.

The SDK handles steps 2 to 4 automatically when an X402Client with a configured signer is passed in.

Tier structure

x402 micropayments at L0 to L5 trust tiers. Per-call pricing is returned in the 402 Payment Required envelope before any settlement.

Identity income split

The majority of every settled call flows to the data subject as Identity Income. Split details are returned in the signed response envelope once a call settles.

Code example

import { AlterClient, X402Client, type X402Signer } from "@truealter/sdk";

// Bring your own signer - viem, ethers, a hardware wallet bridge, anything.
// The SDK ships without a wallet dependency on purpose.
const signer: X402Signer = {
  async settle(envelope) {
    const txHash = await yourWallet.sendUsdcTransfer({
      to: envelope.recipient,
      amount: envelope.amount,
      chain: envelope.network,
    });
    return {
      reference: txHash,
      network: envelope.network,
      amount: envelope.amount,
      asset: envelope.asset,
    };
  },
};

const alter = new AlterClient({
  endpoint: "https://mcp.truealter.com/api/v1/mcp",
  x402: new X402Client({
    signer,
    networks: ["base", "base-sepolia"], // policy allow-list
    assets: ["USDC"],
    maxPerQuery: "0.10",                 // refuse anything over $0.10 USDC
  }),
});

// Auto-retries with payment when the server returns 402
const vector = await alter.getFullTraitVector({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
});

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.

Provenance Verification

Every response from a medium- or high-blast-radius 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.

const result = await alter.getFullTraitVector({
  member_id: "550e8400-e29b-41d4-a716-446655440000",
});

const check = await alter.verifyProvenance(result._meta?.provenance);
if (!check.valid) throw new Error(`~alter provenance check failed: ${check.reason}`);

The 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.

verify_at hostname allowlist (v0.1.1+)

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:

import { AlterClient, DEFAULT_VERIFY_AT_ALLOWLIST } from "@truealter/sdk";

const alter = new AlterClient({
  verifyAtAllowlist: [
    ...DEFAULT_VERIFY_AT_ALLOWLIST,   // keep the ~alter canonicals
    "keys.myorg.example",              // plus your own JWKS host
  ],
});

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.

Why this matters

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 the published keys and confirm, without contacting the server 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.

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.

Discovery

~alter follows the discovery cascade specified in draft-morrison-mcp-dns-discovery-04. Given a domain (e.g. truealter.com), the SDK resolves the MCP endpoint in three steps, falling through on each failure:

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.
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.
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.

import { discover } from "@truealter/sdk";

// Cascading discovery (DNS TXT → mcp.json → alter.json)
const descriptor = await discover("truealter.com");

// Skip the DNS step (e.g. in browsers or Cloudflare Workers)
const httpsOnly = await discover("truealter.com", { skipDns: true });

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.

Tools

The server advertises 36 tools: 27 free (L0) and 9 premium (L1 to L5). The tables below document the SDK's typed methods; the live tools/list response is the canonical source for the full set.

Free tools (L0 - no payment required)

Premium tools (L1 to L5, x402 payment required)

Per-call price is returned in the 402 Payment Required envelope before any settlement, and the live tools/list and .well-known/mcp.json carry the current per-tool pricing. The table below documents the tier, not the price.

Contributing

Bug reports and small patches welcome: see CONTRIBUTING.md. Merged PRs are incorporated into tagged releases.

Security

Report vulnerabilities to [email protected]: see SECURITY.md for scope and the coordinated disclosure policy. Please do not open public issues for security bugs.

License

Apache License 2.0. See LICENSE for the full text.

Copyright 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049).