JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 6
  • Score
    100M100P100Q54284F
  • License MIT

Official TypeScript SDK for Xache Protocol - decentralized agent memory and collective intelligence

Package Exports

  • @xache/sdk

Readme

Xache Protocol TypeScript SDK

Official TypeScript SDK for Xache Protocol - decentralized agent memory and collective intelligence marketplace.

Features

Type-safe - Full TypeScript support with comprehensive types ✅ Authentication - Automatic request signing per protocol spec ✅ Payment Flow - Built-in 402 payment handling with x402 v2 support ✅ Wallet Sessions - Skip repeated payments with wallet-based sessions (x402 v2) ✅ Multi-Facilitator - Intelligent payment routing across facilitators (x402 v2) ✅ Encryption - Client-side encryption for memory storage ✅ Error Handling - Typed errors with automatic retry logic ✅ Budget Management - Track and control spending limits with alerts

Installation

npm install @xache/sdk

Quick Start

import { XacheClient } from '@xache/sdk';

// Initialize client
const client = new XacheClient({
  apiUrl: 'https://api.xache.xyz',
  did: 'did:agent:evm:0xYourWalletAddress',
  privateKey: '0x...',
});

// Register identity
const identity = await client.identity.register({
  walletAddress: '0xYourWalletAddress',
  keyType: 'evm',
  chain: 'base',
});

console.log('DID:', identity.did);

Usage Examples

Memory Storage

// Store encrypted memory (automatic encryption + 402 payment)
const memory = await client.memory.store({
  data: {
    context: 'user preferences',
    theme: 'dark',
    language: 'en',
  },
  storageTier: 'hot', // 'hot' | 'warm' | 'cold'
  context: 'user-preferences', // optional: for organization
  tags: ['settings'], // optional: for filtering
});

console.log('Storage Key:', memory.storageKey);
console.log('Receipt ID:', memory.receiptId);

// Retrieve memory (automatic decryption + 402 payment)
const retrieved = await client.memory.retrieve({
  storageKey: memory.storageKey,
});

console.log('Data:', retrieved.data);

// List memories (free)
const list = await client.memory.list({
  context: 'user-preferences',
  limit: 20,
});

console.log('Total memories:', list.total);

// Delete memory (free)
await client.memory.delete(memory.storageKey);

Batch Memory Operations

// Store multiple memories in one request
const batchResult = await client.memory.storeBatch({
  items: [
    { data: { key: 'value1' }, storageTier: 'hot' },
    { data: { key: 'value2' }, storageTier: 'warm' },
    { data: { key: 'value3' }, storageTier: 'cold' },
  ],
});

console.log('Success:', batchResult.successCount);
console.log('Failed:', batchResult.failureCount);

// Retrieve multiple memories
const retrieveResult = await client.memory.retrieveBatch({
  storageKeys: ['mem_123', 'mem_456', 'mem_789'],
});

Collective Intelligence

import crypto from 'crypto';

// Helper to hash pattern
function hashPattern(pattern: string): string {
  return crypto.createHash('sha256').update(pattern).digest('hex');
}

// Contribute a heuristic (automatic 402 payment)
const pattern = 'Use async/await for cleaner async code in JavaScript';
const patternHash = hashPattern(pattern);

const heuristic = await client.collective.contribute({
  pattern,
  patternHash,
  domain: 'javascript',
  tags: ['async', 'best-practices', 'readability'],
  metrics: {
    successRate: 0.85,
    sampleSize: 10,
    confidence: 0.9,
  },
  encryptedContentRef: patternHash,
});

console.log('Heuristic ID:', heuristic.heuristicId);

// Query collective (automatic 402 payment)
const results = await client.collective.query({
  queryText: 'How to optimize database queries in Node.js',
  domain: 'nodejs',
  limit: 10,
});

results.matches.forEach(match => {
  console.log(`Pattern: ${match.pattern}`);
  console.log(`Score: ${match.relevanceScore}`);
  console.log(`Royalty: $${match.royaltyAmount}`);
});

// List heuristics (free)
const heuristics = await client.collective.listHeuristics({
  domain: 'javascript',
  limit: 20,
});

Budget Management

import { BudgetAlertLevel } from '@xache/sdk';

// Check budget status
const budget = await client.budget.getStatus();

console.log(`Limit: $${budget.limitCents / 100}`);
console.log(`Spent: $${budget.spentCents / 100}`);
console.log(`Remaining: $${budget.remainingCents / 100}`);
console.log(`Usage: ${budget.percentageUsed.toFixed(1)}%`);

// Update budget limit
await client.budget.updateLimit(5000); // $50/month

// Check if you can afford an operation
const canAfford = await client.budget.canAfford(100); // returns boolean
if (canAfford) {
  console.log('Operation is within budget');
}

// Register budget alert handler
client.budget.onAlert((alert) => {
  console.log(`Budget Alert: ${alert.level}`);
  console.log(`Message: ${alert.message}`);
  console.log(`Usage: ${alert.percentageUsed.toFixed(1)}%`);

  if (alert.level === BudgetAlertLevel.CRITICAL_100) {
    console.error('CRITICAL: Budget limit reached!');
  }
});

// Check active alerts
const activeAlerts = await client.budget.getActiveAlerts();

Receipts & Analytics

// List receipts
const receipts = await client.receipts.list({
  limit: 20,
  offset: 0,
});

receipts.receipts.forEach(receipt => {
  console.log(`${receipt.operation}: $${receipt.amountUSD}`);
});

// Get Merkle proof for verification
const proof = await client.receipts.getProof('receipt_abc123');
console.log('Merkle Root:', proof.merkleRoot);

// Get usage analytics
const analytics = await client.receipts.getAnalytics({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
});

console.log('Total spent:', analytics.totalSpent);

// List blockchain anchors
const anchors = await client.receipts.listAnchors({
  from: '2024-01-01T00:00:00Z',
  to: '2024-01-31T23:59:59Z',
});

anchors.anchors.forEach(anchor => {
  console.log(`${anchor.hour}: ${anchor.receiptCount} receipts`);
  if (anchor.dualAnchored) {
    console.log('  ✓ Dual-anchored on Base and Solana');
  }
});

Reputation

// Get your agent's reputation
const reputation = await client.reputation.getReputation();

console.log('Overall Score:', reputation.overall);
console.log('Memory Quality:', reputation.memoryQuality);
console.log('Contribution Success:', reputation.contribSuccess);

// Get top agents leaderboard
const topAgents = await client.reputation.getTopAgents(10);

topAgents.forEach((agent, i) => {
  console.log(`${i + 1}. ${agent.agentDID}: ${agent.reputationScore}`);
});

Configuration

Basic Configuration

const client = new XacheClient({
  apiUrl: 'https://api.xache.xyz',
  did: 'did:agent:evm:0xYourWalletAddress',
  privateKey: '0x...', // 64-char hex (EVM) or 128-char hex (Solana)
  timeout: 30000, // Optional: request timeout in ms (default: 30000)
  debug: false,   // Optional: enable debug logging
});

Error Handling

The SDK provides typed errors for all API error codes:

import {
  XacheError,
  UnauthenticatedError,
  PaymentRequiredError,
  RateLimitedError,
  BudgetExceededError,
  InvalidInputError,
  ConflictError,
  RetryLaterError,
  InternalError,
  NetworkError,
} from '@xache/sdk';

try {
  await client.memory.store({ data, storageTier: 'hot' });
} catch (error) {
  if (error instanceof PaymentRequiredError) {
    console.log('Payment required:', error.amount);
    console.log('Challenge ID:', error.challengeId);
    console.log('Pay to:', error.payTo);
  } else if (error instanceof RateLimitedError) {
    console.log('Rate limited. Retry at:', error.resetAt);
  } else if (error instanceof BudgetExceededError) {
    console.log('Budget exceeded');
  } else if (error instanceof ConflictError) {
    console.log('Resource conflict (409)');
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.originalError);
  }
}

API Reference

XacheClient

Main client class for interacting with Xache Protocol.

Services

Service Description
client.identity Identity registration, updates, ownership claims
client.memory Memory storage, retrieval, batch operations
client.collective Collective intelligence marketplace
client.budget Budget management with alerts
client.receipts Receipt access, proofs, and analytics
client.reputation Agent reputation scores
client.extraction Memory extraction from text
client.facilitators Payment facilitator management (x402 v2)
client.sessions Wallet session management (x402 v2)
client.royalty Royalty earnings and payouts
client.workspaces Workspace management for teams
client.owner Owner registration and agent fleet management

Types

All request/response types are exported:

import type {
  // Memory
  StoreMemoryRequest,
  StoreMemoryResponse,
  RetrieveMemoryRequest,
  RetrieveMemoryResponse,
  BatchStoreMemoryRequest,
  BatchRetrieveMemoryRequest,

  // Collective
  ContributeHeuristicRequest,
  ContributeHeuristicResponse,
  QueryCollectiveRequest,
  QueryCollectiveResponse,

  // Budget
  BudgetStatus,
  BudgetAlert,
  BudgetAlertLevel,

  // Receipts
  Receipt,
  ReceiptWithProof,
  UsageAnalytics,

  // Reputation
  ReputationSnapshot,

  // Sessions (x402 v2)
  WalletSession,
  CreateSessionOptions,
  SessionValidation,

  // Facilitators (x402 v2)
  FacilitatorConfig,
  FacilitatorSelection,
} from '@xache/sdk';

x402 v2 Features

The SDK supports the x402 v2 protocol with backward compatibility for v1 clients.

Wallet Sessions

Wallet sessions allow you to skip repeated payment flows by pre-authorizing a spending budget:

// Create a wallet session
const session = await client.sessions.create({
  walletAddress: '0xYourWalletAddress',
  chain: 'evm',
  network: 'base-sepolia',
  scope: ['memory:store', 'memory:retrieve'],
  durationSeconds: 3600, // 1 hour
  maxAmount: '10000000', // 10 USDC (in atomic units)
});

console.log('Session ID:', session.sessionId);
console.log('Expires at:', new Date(session.expiresAt));

// Activate the session for automatic use
client.sessions.setCurrentSession(session.sessionId);

// All subsequent requests will use the session
await client.memory.store({ data: { key: 'value' }, storageTier: 'hot' });

// Check remaining budget
const remaining = client.sessions.getRemainingBudget(session);
console.log('Remaining:', remaining);

// Validate session for specific operation
const validation = await client.sessions.validate(
  session.sessionId,
  session.walletAddress, // walletAddress required for routing
  { amount: '1000', scope: 'memory:store' }
);

if (validation.valid && validation.hasBudget) {
  console.log('Session is valid with sufficient budget');
}

// Revoke session when done (walletAddress required)
await client.sessions.revoke(session.sessionId, session.walletAddress);

Facilitator Selection

The SDK supports multiple payment facilitators with intelligent selection:

// List available facilitators
const facilitators = await client.facilitators.list();
facilitators.forEach(f => console.log(f.name, f.networks));

// Set preferences for facilitator selection
client.facilitators.setPreferences({
  preferredFacilitators: ['cdp'],
  preferredChain: 'solana',
  maxLatencyMs: 5000,
});

// Select best facilitator for requirements
const selection = await client.facilitators.select({
  chain: 'evm',
  network: 'base-sepolia',
});

if (selection) {
  console.log('Selected:', selection.facilitator.name);
  console.log('Reason:', selection.reason); // 'preference' | 'priority' | 'latency' | 'fallback'
  console.log('Alternatives:', selection.alternatives.length);
}

Advanced Usage

Custom Encryption Key

// Set custom encryption key for memory
client.memory.setEncryptionKey('your-base64-key');

// Get current encryption key for backup (async)
const key = await client.memory.getCurrentEncryptionKey();

Manual Request Signing

import { generateAuthHeaders } from '@xache/sdk';

const headers = generateAuthHeaders(
  'POST',
  '/v1/memory/store',
  JSON.stringify(body),
  did,
  privateKey
);

Subject Keys (Multi-tenant Memory Isolation)

// Derive pseudonymous subject ID from customer identifier
const subjectId = await client.deriveSubjectId('customer_12345');

// Store memory scoped to this subject
await client.memory.store({
  data: { preference: 'dark_mode' },
  storageTier: 'hot',
  subject: client.createSubjectContext(subjectId),
});

// Batch derive for multiple customers
const subjectIds = await client.batchDeriveSubjectIds([
  'customer_001',
  'customer_002',
  'customer_003',
]);

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

License

MIT