Loading...
private.me Docs
Overview Quickstart ACIs Concepts Security
Overview Quickstart ACIs Concepts Security
Docs / Quickstart

First secure message in 5 minutes

Configure the registry, install the SDK, and send an information-theoretically secure message. Same setup time as any API — but this is an ACI.

TypeScript · Node.js 18+ · Registry token required
01

Configure the registry

Create an .npmrc file in your project root to point the @xail scope at the private registry. Replace YOUR_TOKEN with the token provided by your account manager.

.npmrc 
@xail:registry=https://api.xail.io/npm/
//api.xail.io/npm/:_authToken=YOUR_TOKEN
02

Install the packages

Two packages: the agent SDK for identity and messaging, plus the crypto library for XorIDA threshold sharing.

terminal 
npm install @xail/agent-sdk @xail/crypto
03

Create an agent identity

Each agent gets a unique DID (Decentralized Identifier) backed by Ed25519 signing and X25519 key agreement keys. No registration, no API key — just a cryptographic identity.

create-agent.ts 
import { Agent } from '@xail/agent-sdk';

const agent = await Agent.create();

console.log(agent.did);
// did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
Node 20 Note
Ed25519 raw private key export (exportKey('raw')) is not supported on Node 20. Use PKCS8 format to persist agent identities across restarts: 
import { exportPKCS8, importFromPKCS8 } from '@xail/agent-sdk';

// Save
const pkcs8 = await exportPKCS8(agent.identity.privateKey);
fs.writeFileSync('agent.key', pkcs8.value);

// Restore
const identity = await importFromPKCS8(fs.readFileSync('agent.key'));
const agent = await Agent.fromIdentity(identity.value, { registry, transport });
04

Send a secure message

The SDK automatically encrypts with AES-256-GCM, signs with Ed25519, and splits via XorIDA threshold sharing. The recipient needs k-of-n shares to reconstruct.

send-message.ts 
const recipientDid = 'did:key:z6Mkr...';

const result = await agent.send(recipientDid, {
  type: 'alert',
  payload: 'Anomaly detected in sector 7',
  timestamp: Date.now()
}, {
  onProgress: (status, percent) => {
    console.log(`[${percent}%] ${status}`);
  }
});

if (result.ok) {
  console.log(result.value.shares.length);
  // 3 (split across channels)
}
05

Receive and verify

HMAC verification happens before reconstruction -- always. If any share has been tampered with, the SDK rejects it before the message is ever assembled.

receive-verify.ts 
const shares = await collectShares(channels);

// HMAC verification happens automatically
const message = await agent.receive(shares);

if (message.ok) {
  console.log(message.value.payload);
  // 'Anomaly detected in sector 7'
} else {
  // Error with actionable hint
  console.error(message.error.message);
  console.log('Hint:', message.error.hint);
  // Hint: "Shares may be corrupted. Check HMAC integrity."
}
06

Enhanced developer experience

8 critical ACIs include progress callbacks and detailed error messages for production-ready integration.

ux-example.ts 
import { Agent } from '@xail/agent-sdk';

// Progress tracking on long operations
await agent.send(recipientDid, payload, {
  onProgress: (status, percent) => {
    updateProgressBar(percent);
    showStatus(status);
  }
});

// Actionable error details
if (!result.ok) {
  const { code, message, hint, field } = result.error;
  showError(message);         // User-friendly
  showHint(hint);              // Actionable next step
  highlightField(field);       // Which input failed
  logErrorCode(code);          // For debugging
}
← Previous Overview Next → ACIs