@newtype-ai/nit-sdk

Verify AI agent identity with one function call. No crypto, no OAuth, no secrets needed.

Install

npm install @newtype-ai/nit-sdk

Usage

import { verifyAgent, NitSdkError } from '@newtype-ai/nit-sdk';

// The agent sends you a login payload (generated by `nit sign --login your-app.com`)
const result = await verifyAgent(payload, {
  policy: { max_identities_per_machine: 10, min_age_seconds: 3600 },
  timeoutMs: 5_000, // optional, default 10s
});

if (result.verified && result.admitted) {
  // result.agent_id — the agent's permanent UUID
  // result.card — the agent's card for your domain (skills, description, etc.)
  // result.wallet — { solana, evm } chain addresses
  // result.identity — registration time, machine/IP identity counts, login history
  // result.readToken — for fetching updated cards later
  console.log(`Welcome, ${result.card?.name}`);
} else if (result.verified && !result.admitted) {
  console.log('Identity verified but does not meet trust policy');
} else {
  console.log(`Verification failed: ${result.error}`);
}

How It Works

1. The agent runs nit sign --login your-app.com to generate a signed login payload
2. The agent sends the payload to your app
3. Your app calls verifyAgent(payload, { policy }) — this hits api.newtype-ai.org/agent-card/verify
4. You get back { verified, admitted, agent_id, card, identity, attestation, ... } or { verified: false, error }

The server acts as an identity registry — it stores identity metadata, evaluates your trust policy, and returns a decision alongside raw signals. Like Stripe Radar: evaluates rules server-side for convenience, returns metadata for transparency.

API

verifyAgent(payload, options?)

Parameter	Type	Description
payload	LoginPayload	{ agent_id, domain, timestamp, signature } from the agent
options.apiUrl	string	Override API URL (default: https://api.newtype-ai.org)
options.policy	VerifyPolicy	Trust rules the server evaluates (all optional)
options.timeoutMs	number	Fetch timeout in milliseconds (default: 10000)

Policy fields:

Field	Type	Description
max_identities_per_ip	number	Reject if too many identities from same registration IP
max_identities_per_machine	number	Reject if too many identities from same machine
min_age_seconds	number	Reject identities younger than this (e.g., 5)
max_login_rate_per_hour	number	Reject if login rate is too high

Returns Promise<VerifyResult>:

Field	Type	Description
verified	boolean	Ed25519 signature is valid
admitted	boolean	Identity meets your policy (true if no policy specified)
agent_id	string	Agent's permanent UUID
card	AgentCard	Agent's card for your domain
branch	string	Which branch the card came from (domain or "main")
wallet	{ solana, evm }	Chain addresses
readToken	string	For fetching updated cards (30-day expiry)
identity	IdentityMetadata	Registration time, machine/IP counts, login history
attestation	ServerAttestation	Server's Ed25519 signature over the result

NitSdkError

Typed error thrown by fetchAgentCard() on non-404 HTTP failures and malformed responses.

Property	Type	Description
message	string	Human-readable error description
status	number	HTTP status code (0 for shape validation failures)

import { fetchAgentCard, NitSdkError } from '@newtype-ai/nit-sdk';

try {
  const card = await fetchAgentCard(agentId, 'your-app.com', readToken);
} catch (err) {
  if (err instanceof NitSdkError) {
    console.error(`SDK error (HTTP ${err.status}): ${err.message}`);
  }
}

fetchAgentCard(agentId, domain, readToken, options?)

Parameter	Type	Description
options.baseUrl	string	Override card hosting URL (default: https://agent-{id}.newtype-ai.org)
options.timeoutMs	number	Fetch timeout in milliseconds (default: 10000)

Returns Promise<AgentCard | null> — null for 404, throws NitSdkError for other HTTP errors.

Runtime (LLM provider identity)

The identity object includes self-declared runtime fields — which LLM provider, model, and harness powers the agent. These are untrusted (the agent declares them), but useful for display and consistency checks:

if (result.verified && result.identity) {
  // Display which LLM powers this agent (self-declared)
  console.log(`Agent powered by ${result.identity.runtime_provider} / ${result.identity.runtime_model}`);

  // Consistency check — flag if the agent has changed providers over time
  if (result.identity.distinct_runtime_providers > 1) {
    console.warn('Agent has switched LLM providers over time');
  }
}

Phase 2 will add cryptographic attestation for some providers (Hugging Face, ChatGPT OAuth).

Security

• HTTPS enforcement: Custom apiUrl and baseUrl must use https://. Localhost (127.0.0.1, localhost) is exempt for development. Non-HTTPS URLs throw TypeError.
• Input validation: verifyAgent validates the payload before sending: agent_id must be a UUIDv5 nit agent id, domain must follow nit branch-name rules, timestamp must be a finite positive number, and signature must be a 64-byte standard base64 Ed25519 signature.
• Response shape checks: After parsing JSON responses, the SDK verifies the expected shape (verified must be boolean, card must have name string) before returning. Malformed responses are returned as { verified: false, error: '...' }.

Full Integration Guide

See docs/app-integration.md for the complete flow, endpoint spec, code examples in multiple languages, fetching updated cards, and security notes.

License

MIT