npm package: @sputnikx/soulledger-sdk
Description: Trust scores for AI agents on Base chain. 130K+ agents indexed. Zero dependencies.
Author: SputnikX
Latest version: 1.0.1

<div align="center">

# @sputnikx/soulledger-sdk

### ERC-8004 is DNS. SoulLedger is Google.

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

[![npm version](https://img.shields.io/npm/v/@sputnikx/soulledger-sdk.svg?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/@sputnikx/soulledger-sdk)
[![license](https://img.shields.io/npm/l/@sputnikx/soulledger-sdk.svg?style=flat-square)](./LICENSE)
[![node](https://img.shields.io/node/v/@sputnikx/soulledger-sdk.svg?style=flat-square)](https://nodejs.org)
[![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square)](./package.json)
[![Base Mainnet](https://img.shields.io/badge/Base-Mainnet-0052FF?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAiIGhlaWdodD0iMjAiIHZpZXdCb3g9IjAgMCAyMCAyMCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMCIgY3k9IjEwIiByPSIxMCIgZmlsbD0id2hpdGUiLz48L3N2Zz4=)](https://basescan.org/address/0x9f3bB1BA3fD64F5c0F49dCEC1f873753Ab014779)
[![agents indexed](https://img.shields.io/badge/agents_indexed-130%2C000%2B-blueviolet?style=flat-square)](https://soul.sputnikx.xyz)

</div>

---

SoulLedger is the first open protocol for AI agent identity and trust on [Base chain](https://base.org). 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`](https://basescan.org/address/0x9f3bB1BA3fD64F5c0F49dCEC1f873753Ab014779) |
| **Standard** | ERC-8004 (Soulbound Agent NFT) |
| **Explorer** | [View on BaseScan](https://basescan.org/address/0x9f3bB1BA3fD64F5c0F49dCEC1f873753Ab014779) |

## Quick Start

```bash
npm install @sputnikx/soulledger-sdk
```

```js
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:

```bash
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](https://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.

```js
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) |

```js
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.

```js
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.

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

#### `soul.getCharacter(agentId)`

Get character DNA — archetype, strengths, blindspots.

```js
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.

```js
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 |

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

#### `soul.getPassport(sxId)`

Get passport details by SX ID.

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

#### `soul.getStats()`

Get SoulLedger platform statistics.

```js
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 |

```js
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.

```js
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.

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

#### `soul.getMapping()`

Get the Article 12 compliance mapping.

```js
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'` |

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

---

### Standalone Clients

You can also use `IdentityClient` and `ComplianceClient` separately:

```js
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:

```js
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](https://github.com/drivenbymyai-max/granulas/issues) to get listed here.

---

## Related

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

- **SoulLedger API:** [soul.sputnikx.xyz](https://soul.sputnikx.xyz)
- **Agent Card:** [sputnikx.xyz/.well-known/agent-card.json](https://sputnikx.xyz/.well-known/agent-card.json)
- **SoulPassport Contract:** [View on BaseScan](https://basescan.org/address/0x9f3bB1BA3fD64F5c0F49dCEC1f873753Ab014779)

## License

[MIT](./LICENSE) --- [SputnikX](https://sputnikx.xyz)