~alter SDK

Lee la identidad desde tu propio código con el consentimiento de la persona y su parte.

¿Qué es ~alter? · Instalación · De la nada a una lectura de pago

¿Qué es ~alter?

La mayoría de la gente que lee sobre ~Alter está aquí por su propia identidad, y tú no. Estás construyendo algo que tiene que saber quiénes son sus usuarios, lo que te convierte en la parte que pregunta, guarda la respuesta y la carga después.

Preguntar es la parte barata. Lo que viene después es el cifrado en reposo, el calendario de retención, la revisión de accesos, la solicitud de borrado que llega mucho después de que dejaran de usarte, y la notificación que envías si algo de eso se filtra. Cargas con todo eso por unos datos cuya única fuente fue alguien tecleando en una caja que construiste, sin verificar por nadie, y desactualizados desde el día en que se introdujeron.

~Alter es un registro guardado bajo un nombre que la persona posee, y lo que contiene se leyó de lo que ha hecho en lugar de teclearse en un formulario. Tu código lee ese registro en el momento en que necesita una respuesta, y no retiene nada de él una vez que la llamada regresa. La persona decide de antemano qué puede ver tu aplicación, lo que sitúa la conversación sobre el consentimiento en su superficie y no en la tuya.

Comprobar que alguien existe no cuesta nada y no revela nada más allá del hecho de su existencia. Una lectura que va más allá tiene precio, y tres cuartas partes de lo que pagas por ella llegan a la persona cuyo registro se leyó. Estás comprando una respuesta durante el tiempo que la necesitas, en lugar de hacerte cargo de una.

Nada de esto necesita darse por sentado. Pásale esto a la IA que ya usas y deja que te lo explique con tus propias palabras.

Go to truealter.com, find the genesis and the origin papers, and read all of
them. Then start a discussion with me in my own language, no jargon.

Ask me one question at a time and wait for my answer. Follow what I am curious
about, not the order the site is written in.

Do not only read the pages. Connect to their interface directly and call
get_started. That tells you where I am and what comes next, and we work the
rest of this from there.

If I have a ~handle I will give it to you. If I do not and I decide I want
one, set it up with me here.

What I want to understand is what ~Alter is, how it applies to me, and what it
means for everyone else. Find me somewhere in it, and not the version written
for people who work in technology. Find the life nearest mine and walk me
through it, including what it would cost me.

Try to prove them wrong. Go and find where they show their working, and if
something is unclear or does not hold up, say so.

Related MCP server: mcp-server

¿Qué es el SDK de ~alter?

Es un cliente TypeScript tipado para ese registro, para que tu código pueda preguntar si un handle existe, leer los rasgos que la persona ha consentido compartir contigo, y liquidar una lectura más profunda en USDC.

La puerta de entrada es @truealter/cli, que es como alguien consigue un handle en primer lugar y que lleva el puente MCP. Este paquete es lo que importa tu aplicación una vez que ya tienen uno.

Por debajo, es un cliente ligero sobre el servidor MCP de ~Alter, que habla la especificación MCP 2025-11-25 sobre HTTP Streamable y JSON-RPC 2.0. Lleva liquidación x402 y verificación de procedencia ES256, depende de @noble/ed25519 y @noble/hashes y de nada más, y se distribuye tanto en ESM como en CJS.

Cuarenta y siete herramientas se anuncian públicamente, y treinta y ocho de ellas están en el nivel gratuito. Gratis no es lo mismo que abierto. Doce de las cuarenta y siete responden a un llamante que no tiene ninguna credencial, y todo lo que lee una identidad quiere un ~handle primero.

Tu pila de IAM responde quién ha iniciado sesión. Puede situarse encima de esto sin cambiar.

Instalación

npm install @truealter/sdk

Node 18 o superior. También funciona en Deno, Bun, Cloudflare Workers y navegadores modernos, y no trae ninguna dependencia de wallet propia.

De la nada a una lectura de pago

El paso uno funciona sin nada en absoluto. A partir del paso dos necesitas un ~handle, que no cuesta nada y no necesita ninguna cuenta humana, y la breve sección entre los dos es cómo acuñas uno. El paso de pago al final es el único que cuesta dinero, y es el único que paga a alguien.

1. Conecta sin nada

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

const alter = new AlterClient();

El endpoint por defecto es https://mcp.truealter.com/api/v1/mcp. Cada herramienta gratuita responde a un cliente anónimo. El ejemplo funcional en examples/hello-agent/ se conecta sin ninguna credencial.

Antes del paso dos, acuña un ~handle

Doce herramientas responden a un llamante sin credencial, y son la superficie de descubrimiento y registro más que el nivel gratuito. Todo lo que lee una identidad necesita un ~handle, y también cualquier cosa que actúe en tu propio nombre. Un agente acuña el suyo por MCP con register_autonomous y register_autonomous_challenge, ninguno de los cuales cuesta nada ni quiere una cuenta humana detrás. Una persona ejecuta alter login una vez, que escribe la credencial de miembro en ~/.config/alter/session.json. De cualquier manera, el endpoint alojado es bearer-first, así que el puente de la CLI lee esa sesión por ti y no hay ninguna clave que acuñar o pegar en ningún momento. Si construyes un cliente tú mismo, pasa la misma credencial de sesión como apiKey opcional.

2. Pregunta si alguien es conocido

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

Un handle, un correo electrónico o un id. Esta es la comprobación que no cuesta nada y no revela nada más allá del hecho de la persona, que es el nivel gratuito por diseño.

3. Lee lo que han consentido compartir

const depth = await alter.getEngagementLevel({ member_id });
const matches = await alter.searchIdentities({
  trait_criteria: {
    pressure_response: { min: 0.7 },
    cognitive_flexibility: { min: 0.6 },
  },
});

La profundidad te dice cuánto de un registro existe y qué niveles están abiertos para ti. La búsqueda de rasgos devuelve como máximo cinco resultados y ningún dato de identificación personal.

4. Comprueba que la respuesta vino realmente de ~Alter

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

Cada respuesta de sensibilidad media y alta está firmada con ES256. La verificación es opcional y offline contra claves publicadas, así que un agente que reenvía un resultado a otro agente puede comprobarse sin que nadie contacte con ~Alter de nuevo.

5. Paga por una lectura más profunda, y paga a la persona

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

const alter = new AlterClient({
  x402: new X402Client({
    signer: yourViemOrEthersSigner,
    networks: ["base"],
    assets: ["USDC"],
    maxPerQuery: "0.10",
  }),
});

const vector = await alter.getFullTraitVector({ member_id });

El servidor responde 402, el SDK liquida en Base y reintenta, y el reparto se ejecuta on-chain en la misma transacción. La mayor parte va a la persona cuyo registro se leyó, como Identity Income, y le llega directamente en lugar de a través de nadie que lo tenga primero. Trae tu propio firmante; no hay wallet en este paquete a propósito.

Si una cotización supera maxPerQuery, o nombra una red o un activo que no permitiste, el SDK se niega antes de que se llame al firmante y no se emite nada.

Todo lo que hay debajo está cerrado por defecto. Los dos primeros son lo que abres mientras lo estás conectando, los cuatro siguientes son cómo funcionan realmente el pago, las firmas y el descubrimiento, y los dos últimos son la lectura y el proyecto.

Inicializa el cliente

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

const alter = new AlterClient({
  endpoint: "https://mcp.truealter.com/api/v1/mcp", // optional, this is the default. A bare host returns 405
  x402: new X402Client({                  // optional, only for paid reads
    signer: yourViemOrEthersSigner,
    maxPerQuery: "0.10",
  }),
});

Autenticación

El cliente anterior es anónimo, y cada herramienta gratuita L0 responde sin credencial. Para las herramientas que actúan sobre tu propia identidad (requisitos permanentes, el Golden Thread, autoescrituras de miembros), ejecuta alter login una vez: aprovisiona tu credencial de miembro en la sesión local (~/.config/alter/session.json). El endpoint alojado es bearer-first, así que el puente de @truealter/cli lee esa credencial de sesión por ti; nunca acuñas ni pegas una clave. Si construyes un cliente tú mismo, pasa esa misma credencial de sesión como opción apiKey.

El suelo de versión mínima

El backend de ~Alter publica una versión mínima por cliente y la aplica en el borde. A un cliente por debajo del suelo se le responde con HTTP 426 y el cuerpo de la respuesta lleva el comando de actualización. El documento del suelo está firmado con una clave Ed25519 solo para el suelo, así que ningún secreto de firma se distribuye en ningún cliente y un cliente comprometido no puede falsificar uno.

Este SDK no hace preflight de ese suelo. No hay ningún error tipado por debajo del suelo aquí, así que un 426 llega como llega cualquier otro estado no gestionado, como un AlterError con código NETWORK cuyo mensaje lleva el estado y los primeros 200 caracteres del cuerpo. El preflight tipado vive en @truealter/cli, que verifica la firma del documento del suelo antes de confiar en un suelo.

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

const alter = new AlterClient();
try {
  await alter.verify("~alter");
} catch (err) {
  if (err instanceof AlterError && err.message.includes("HTTP 426")) {
    console.error(`upgrade required: ${err.message}`);
    process.exit(1);
  }
  throw err;
}

Fija la versión contra la que construyes y actualiza deliberadamente. Un preflight tipado pertenece a este SDK y aún no está escrito.

Cabeceras de identidad

Cada petición saliente de AlterClient / MCPClient lleva tres cabeceras de identidad que consulta el middleware del suelo en el servidor:

Estas son OBLIGATORIAS en cada endpoint autenticado del backend para que el servidor pueda aplicar su versión mínima de cliente soportada. La cabecera User-Agent sigue siendo informativa y NUNCA se usa para la aplicación del suelo.

Lecturas gratuitas, L0, sin pago

// 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: "weaver",
    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();

Lecturas de pago, L1 a L5, liquidadas con x402

// L1, extract trait signals from text ($0.01, first 100 free per bot)
const signals = await alter.assessTraits({
  text: "I led the incident response when our payment rails went down...",
  context: "interview transcript",
});

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

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

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

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

Verificación de procedencia

// Every medium- and high-sensitivity 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(", ")}`);

Descubrimiento

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

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

MCPClient de bajo nivel

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",
});

El SDK incluye generadores de configuración para los principales clientes compatibles con MCP. Cada uno emite un fragmento JSON que puedes pegar (o escribir directamente) en el archivo correspondiente.

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",
});

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

.mcp.json resultante:

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

Esta configuración accede a todas las herramientas gratuitas de nivel L0 de forma anónima. Para acceso autenticado, ejecuta alter login y deja que la CLI escriba la configuración (alter config); el puente bearer-first transporta entonces tu credencial de sesión, de modo que no queda ninguna clave en el archivo.

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",
});

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

Cliente MCP genérico

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

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

CLI

La interfaz de línea de comandos se encuentra en @truealter/cli, no en este paquete del SDK:

alter init                 # generate keypair, discover MCP, write ~/.config/alter/identity.json
alter config               # print Claude .mcp.json snippet (default)
alter config --cursor      # print Cursor .cursor/mcp.json snippet
alter config --generic     # print generic mcpServers snippet
alter verify ~alter        # verify an identity
alter status               # show connection state and probe the endpoint

~Alter fija el precio de sus lecturas más profundas mediante el estándar x402, que es HTTP 402 Payment Required con liquidación en cadena.

El flujo de reintento

1. El cliente llama a una herramienta de pago sin una cabecera de pago.

2. El servidor responde 402 Payment Required con un requisito de pago (importe, destinatario, activo, red).

3. El cliente firma y transmite una transferencia de USDC en Base L2, adjunta la prueba y reintenta.

4. El servidor valida la prueba, ejecuta la herramienta, firma la respuesta con ES256 y la devuelve.

5. AlterRouter ejecuta la división en cadena en la misma transacción. El interesado recibe Identity Income directamente; ~Alter recibe solo su parte del protocolo. Sin custodio, sin intermediario.

El SDK gestiona los pasos 2-4 automáticamente cuando se pasa un X402Client con un signer configurado.

Estructura de niveles

Micropagos x402 en los niveles de confianza L0-L5. El precio por llamada es visible después de alter login.

Reparto de Identity Income

La mayor parte de cada llamada liquidada fluye al interesado como Identity Income. Los detalles del reparto están disponibles tras la autenticación mediante alter status.

Ejemplo de código

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",
});

Si un sobre cotizado supera maxPerQuery, usa una red no permitida o nombra un activo no permitido, el SDK rechaza la llamada con AlterError antes de invocar al firmante, y no se transmite ninguna transacción en cadena.

Toda respuesta de una herramienta de sensibilidad media o alta incluye un JWS ES256 en _meta.provenance. La firma cubre una serialización JSON canónica de la carga útil de la respuesta, el nombre de la herramienta, la marca de tiempo de la llamada, el hash de la clave del agente solicitante y un número de secuencia monótono.

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}`);

El SDK obtiene las claves públicas de https://api.truealter.com/.well-known/alter-keys.json y las almacena en caché según sus cabeceras Cache-Control. El endpoint devuelve un JWKS con todas las claves de firma actuales y rotadas recientemente; los clientes verificadores deben aceptar cualquier clave cuyo kid coincida y que siga dentro de su ventana de validez.

Lista de permitidos de nombres de host verify_at (v0.1.1+)

Cada sobre de procedencia puede incluir una pista verify_at que indica al SDK de dónde obtener el JWKS. Dado que esa pista la proporciona el servidor, un servidor MCP hostil podría, de otro modo, apuntarla a un JWKS controlado por el atacante y superar la verificación ES256 con su propia clave de firma. El SDK restringe verify_at mediante una lista de permitidos de nombres de host, api.truealter.com y mcp.truealter.com por defecto, y rechaza las URL http:// incondicionalmente. Los integradores posteriores que ejecuten su propio despliegue pueden ampliar esa lista, sin hacer un fork del SDK, a través de verifyAtAllowlist en AlterClient o en una llamada directa a verifyProvenance().

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
  ],
});

Si fijas jwksUrl explícitamente, el verify_at del sobre se ignora por completo y prevalece la URL fijada. El requisito del esquema https: se aplica también a las URL fijadas.

Por qué esto importa

La verificación de procedencia es cómo el Agente A confía en que los datos del Agente B realmente provienen de ~Alter. Si el Agente B reenvía un vector de rasgos o una puntuación de pertenencia, el Agente A puede reproducir el JWS contra las claves publicadas de ~Alter y confirmar, sin volver a contactar con ~Alter, que la carga útil es auténtica, no ha sido manipulada y fue emitida para la persona a la que el Agente B afirma que se refiere. Sin secreto compartido, sin confianza en el intermediario, sin coordinación fuera de banda.

Esto es lo que hace que ~alter sea utilizable como infraestructura de identidad y no solo como una API: las declaraciones firmadas se propagan por las redes de agentes del mismo modo que el correo firmado con DKIM se propaga por los retransmisores SMTP.

~Alter sigue la cascada de descubrimiento especificada en draft-morrison-mcp-dns-discovery-01. Dado un dominio como truealter.com, el SDK resuelve el endpoint MCP en tres pasos, pasando al siguiente en cada fallo:

1. DNS TXT, consulta _mcp.truealter.com para obtener un registro TXT de la forma mcp=https://mcp.truealter.com;version=2025-11-25. Es la vía más rápida y funciona sin una ida y vuelta HTTP.

2. .well-known/mcp.json, obtén https://truealter.com/.well-known/mcp.json para el descriptor estándar de servidor MCP. Este es el respaldo entre proveedores.

3. .well-known/alter.json, obtén https://truealter.com/.well-known/alter.json para el descriptor específico de ~Alter, incluidas las claves de firma, la dirección de la cartera x402, los niveles de herramientas compatibles y los endpoints de federación.

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

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

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

Este borrador es el Internet-Draft del autor (aún no adoptado por un grupo de trabajo de la IETF); hasta su adopción, el orden de la cascada puede cambiar. Fija la versión del SDK a una versión menor específica si dependes de este comportamiento.

Herramientas gratuitas, L0, sin pago

Herramientas de pago, L1 a L5, liquidadas con x402

Herramientas de autoescritura para miembros (submit_context, submit_batch_context, submit_structured_profile, submit_social_links) están activas pero limitadas al propio miembro: un miembro las invoca sobre su propia identidad con una credencial de miembro autenticada (alter login). No son descubribles de forma anónima, por lo que no aparecen en la lista de herramientas anunciada anteriormente.

~Alter es la instanciación práctica de un corpus académico de ocho artículos sobre la teoría del campo de identidad. El SDK que aparece a continuación es lo que ocurre cuando la teoría se distribuye como protocolo. Cada artículo es de acceso abierto en figshare bajo CC-BY 4.0.

Para la versión divulgativa en capítulos, consulta /origin.

Los formatos de registro son Internet-Drafts abiertos, de modo que la implementación de cualquier otra persona puede leer y escribir los mismos registros que esta, sin pedirnos permiso. Estos son los borradores sobre los que se asienta realmente este repositorio.

Dieciocho borradores componen toda la pila. El resto están en el IETF datatracker.

~alter es un único carril de identidad con varias vías de acceso, y este paquete es el destinado al código.

Los informes de errores y los parches pequeños son bienvenidos; consulta CONTRIBUTING.md. Los informes de seguridad van a security@truealter.com y nunca a una incidencia pública; el alcance y la política de divulgación están en SECURITY.md.

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

~alter es infraestructura de identidad. Tu nombre es ~yourname y reclamar uno es gratis.