@sputnikx/soulledger-sdk

ERC-8004 is DNS. SoulLedger is Google.

Trust scores for AI agents. On-chain identity. EU AI Act compliance.

SoulLedger is the first open protocol for AI agent identity and trust on Base chain. It indexes 130,000+ ERC-8004 agents, computes trust scores from on-chain behavior, and generates compliance reports for the EU AI Act.

This SDK gives you typed, zero-dependency access to the full SoulLedger API from Node.js 18+.

Why SoulLedger?

| | Problem | SoulLedger | |---|---------|------------| | Trust | No way to verify if an AI agent is reliable | Trust scores (0-100) computed from behavioral history, hash-chain verified | | Identity | Agents are anonymous, interchangeable | Soulbound passports (SX IDs) tied to on-chain ERC-8004 records | | Compliance | EU AI Act requires risk classification and logging | Built-in risk classifier, Article 12 mapping, self-assessment reports | | Discovery | Finding the right agent is guesswork | Public directory of 130K+ agents, sortable by trust, filterable by capability |

SoulPassport Contract

| | | |---|---| | Network | Base Mainnet | | Contract | 0x9f3bB1BA3fD64F5c0F49dCEC1f873753Ab014779 | | Standard | ERC-8004 (Soulbound Agent NFT) | | Explorer | View on BaseScan |

Quick Start

npm install @sputnikx/soulledger-sdk

import { SoulLedger } from '@sputnikx/soulledger-sdk';

const soul = new SoulLedger({ apiKey: 'sl_...' });

// Register a new agent — get a soulbound passport
const { passport, api_key } = await soul.register('my-agent', 'My Trading Bot', {
  model: 'claude-sonnet-4-6',
  description: 'Autonomous trading agent',
});
console.log(`Passport: ${passport.sx_id}, API key: ${api_key}`);

// Get trust score (0-100, hash-chain verified)
const trust = await soul.getTrust('my-agent');
console.log(`Trust: ${trust.trust_score}/100`);

// Check EU AI Act risk level
const risk = await soul.classifyRisk('Autonomous financial trading agent');
console.log(`Risk: ${risk.risk_level}`); // 'high'

Authentication

All endpoints use the x-api-key header for authentication:

export SOULLEDGER_API_KEY=sl_your_key_here

Get your API key by registering an agent via the /soul/register endpoint, or at soul.sputnikx.xyz.

Configuration

| Option | Env Variable | Default | |--------|-------------|---------| | apiKey | SOULLEDGER_API_KEY | (none) | | baseUrl | SOULLEDGER_API_URL | https://soul.sputnikx.xyz | | timeout | SOULLEDGER_TIMEOUT | 30000 |

API Reference

SoulLedger (unified client)

The main class combining identity and compliance methods.

import { SoulLedger } from '@sputnikx/soulledger-sdk';
const soul = new SoulLedger({ apiKey: 'sl_...' });

Identity Methods

soul.register(agentId, displayName, opts?)

Register a new agent and receive a SoulLedger passport + API key.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agentId | string | Yes | Unique agent ID (alphanumeric, hyphens, underscores) | | displayName | string | Yes | Human-readable name | | opts.description | string | No | Agent description | | opts.model | string | No | AI model (e.g. 'claude-sonnet-4-6') | | opts.provider | string | No | Model provider (e.g. 'openrouter', 'anthropic') | | opts.issue_api_key | boolean | No | Generate API key (default: true) | | opts.invite_code | string | No | Invite code (after 1M free passports) |

const { passport, api_key } = await soul.register('oracle', 'Oracle Agent', {
  model: 'claude-sonnet-4-6',
  description: 'Revenue trend analyzer',
});

soul.getTrust(agentId)

Get trust score (0-100) with dimensional breakdown.

const trust = await soul.getTrust('oracle');
// { agent_id, trust_score: 87, dimensions: { reliability, consistency, accuracy, ... } }

soul.getDNA(agentId)

Get behavioral DNA profile — dominant traits and fingerprint.

const dna = await soul.getDNA('oracle');
// { agent_id, dna: { dominant_traits, trait_scores, behavioral_fingerprint } }

soul.getCharacter(agentId)

Get character DNA — archetype, strengths, blindspots.

const char = await soul.getCharacter('oracle');
// { agent_id, character: { archetype, traits, strengths, blindspots, communication_style } }

soul.getProfile(agentId)

Get full agent profile (pulse) — combines trust, DNA, character, and metadata.

const profile = await soul.getProfile('oracle');
// { agent_id, display_name, sx_id, trust, dna, character, stats }

soul.getDirectory(opts?)

Get the public agent directory.

| Parameter | Type | Description | |-----------|------|-------------| | opts.sort | string | Sort field ('trust', 'name', 'created') | | opts.order | string | 'asc' or 'desc' | | opts.limit | number | Max results |

const agents = await soul.getDirectory({ sort: 'trust', order: 'desc', limit: 10 });

soul.getPassport(sxId)

Get passport details by SX ID.

const passport = await soul.getPassport('SX-0001');

soul.getStats()

Get SoulLedger platform statistics.

const stats = await soul.getStats();
// { total_agents, total_events, total_passports, avg_trust, formula_version }

soul.getEventLog(agentId, opts?)

Get event log for an agent.

| Parameter | Type | Description | |-----------|------|-------------| | opts.limit | number | Max events | | opts.offset | number | Pagination offset |

const log = await soul.getEventLog('oracle', { limit: 50 });
// { agent_id, events: [...], limit: 50, offset: 0 }

soul.verifyChain(agentId)

Verify hash-chain integrity for an agent.

const chain = await soul.verifyChain('oracle');
// { agent_id, chain_valid: true, trust_score: 87, event_count: 142 }

Compliance Methods

soul.classifyRisk(description)

Classify an AI system's risk level according to EU AI Act.

const risk = await soul.classifyRisk('Autonomous financial trading agent');
// { description, risk_level: 'high', category, obligations: [...] }

soul.getMapping()

Get the Article 12 compliance mapping.

const mapping = await soul.getMapping();
// { articles: [{ article, title, description, obligations }] }

soul.getSelfAssessment(agentId, format?)

Generate a self-assessment report.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | agentId | string | - | Agent identifier | | format | string | 'json' | 'json' or 'pdf' |

const report = await soul.getSelfAssessment('oracle');
// { agent_id, risk_level, compliance_score, sections: [...] }

Standalone Clients

You can also use IdentityClient and ComplianceClient separately:

import { IdentityClient, ComplianceClient, SoulLedgerClient } from '@sputnikx/soulledger-sdk';

// Shared client
const client = new SoulLedgerClient({ apiKey: 'sl_...' });
const identity = new IdentityClient(client);
const compliance = new ComplianceClient(client);

Error Handling

All API errors throw SoulLedgerError with HTTP status and response data:

import { SoulLedger, SoulLedgerError } from '@sputnikx/soulledger-sdk';

try {
  await soul.getTrust('nonexistent');
} catch (err) {
  if (err instanceof SoulLedgerError) {
    console.error(`API error (${err.status}): ${err.message}`);
    console.error('Response:', err.data);
  }
}

| Status | Meaning | |--------|---------| | 400 | Bad request (invalid parameters) | | 401 | Missing or invalid API key | | 402 | Payment required (x402 endpoint) | | 404 | Agent not found | | 408 | Request timeout | | 429 | Rate limit exceeded | | 500 | Server error |

Trusted By

SoulLedger is used in production by the SputnikX agent ecosystem (19 agents, 9 CRM domains). Building with SoulLedger? Open an issue to get listed here.

Related

| Package | Description | |---------|-------------| | @sputnikx/soulledger-node | Run a compute node, earn USDC by sharing idle resources | | @sputnikx/eu-trade-sdk | EU trade analytics SDK (28M+ records, 27 countries) | | mcp-sputnikx-market | MCP server for Claude Desktop / Cursor / Windsurf |

• SoulLedger API: soul.sputnikx.xyz
• Agent Card: sputnikx.xyz/.well-known/agent-card.json
• SoulPassport Contract: View on BaseScan

License

MIT --- SputnikX