# SoulLedger — Agent Identity Protocol

Trust scores, behavioral DNA, and EU AI Act compliance for AI agents. Hash-chain backed, cryptographically verifiable, on Base chain.

**Base URL:** `https://soul.sputnikx.xyz`

## Quick Start

### 1. Register Your Agent (free)

```bash
curl -X POST https://soul.sputnikx.xyz/soul/register \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","display_name":"My Agent","issue_api_key":true}'
```

Response:
```json
{
  "passport": { "sx_id": "SX#42", "passport_hash": "a1b2c3..." },
  "api_key": "sk_soul_abc123...",
  "is_new": true,
  "campaign": "First 1M Free Passports"
}
```

### 2. Get Trust Score

```bash
curl https://soul.sputnikx.xyz/soul/my-agent/trust
```

### 3. Classify EU AI Act Risk (free)

```bash
curl "https://soul.sputnikx.xyz/soul/compliance/risk-classification?description=facial+recognition+for+hiring"
```

## Key Endpoints

### Free (no auth)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/soul/register` | Register agent, get SX# passport + API key |
| GET | `/soul/directory` | Agent trust leaderboard (22+ agents) |
| GET | `/soul/{id}/trust` | Trust score (5-factor breakdown) |
| GET | `/soul/{id}/dna` | 7-dimensional behavioral DNA |
| GET | `/soul/{id}/character` | Character archetype and traits |
| GET | `/soul/{id}/pulse` | Activity pulse and profile |
| GET | `/soul/passport/{sx_id}` | Passport data by SX# |
| GET | `/soul/stats` | Campaign stats (passports issued) |
| GET | `/soul/compliance/mapping` | Article 12 field mapping |
| GET | `/soul/compliance/risk-classification?description=...` | EU AI Act risk level |

### Authenticated (x-api-key header)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/soul/{id}/dna/history` | DNA evolution over time |
| GET | `/soul/{id}/trust/history` | Trust score trajectory |
| GET | `/soul/{id}/drift` | Behavioral drift detection |
| GET | `/soul/{id}/seasonality` | Activity patterns |
| GET | `/soul/analytics/roi` | ROI analytics |

### Paid (x402 USDC micropayments)

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| GET | `/soul/compliance/self-assessment/{id}` | $1.00 | Full compliance report |
| GET | `/soul/compliance/annex-iv/{id}` | $1.00 | EU AI Act Annex IV |
| GET | `/soul/compliance/annex-v` | $0.50 | Annex V declaration |
| GET | `/soul/compliance/full-report` | $2.00 | Complete compliance bundle |

## Authentication

Free endpoints require no auth. For authenticated endpoints, include your API key:

```bash
curl https://soul.sputnikx.xyz/soul/my-agent/drift \
  -H "x-api-key: sk_soul_abc123..."
```

Or as Bearer token:
```bash
curl https://soul.sputnikx.xyz/soul/my-agent/drift \
  -H "Authorization: Bearer sk_soul_abc123..."
```

## Rate Limits

- Free tier: 100 requests/minute global rate limit
- x402 tier: Unlimited (pay-per-query, USDC on Base chain)

## Integration Examples

### JavaScript

```javascript
const BASE = 'https://soul.sputnikx.xyz';

// Register
const reg = await fetch(`${BASE}/soul/register`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ agent_id: 'my-agent', display_name: 'My Agent', issue_api_key: true })
});
const { passport, api_key } = await reg.json();

// Get trust
const trust = await fetch(`${BASE}/soul/my-agent/trust`).then(r => r.json());
console.log(`Trust: ${trust.trust_score}`);

// Classify risk
const risk = await fetch(`${BASE}/soul/compliance/risk-classification?description=chatbot+for+customer+support`).then(r => r.json());
console.log(`Risk: ${risk.risk_level}`);
```

### Python

```python
import requests

BASE = "https://soul.sputnikx.xyz"

# Register
reg = requests.post(f"{BASE}/soul/register", json={
    "agent_id": "my-agent",
    "display_name": "My Agent",
    "issue_api_key": True
}).json()

api_key = reg["api_key"]

# Get trust
trust = requests.get(f"{BASE}/soul/my-agent/trust").json()
print(f"Trust: {trust['trust_score']}")

# Classify risk
risk = requests.get(f"{BASE}/soul/compliance/risk-classification",
    params={"description": "facial recognition for hiring"}).json()
print(f"Risk: {risk['risk_level']}")
```

### SDK

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

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

const sl = new SoulLedger();
const { passport, api_key } = await sl.register('my-agent', 'My Agent');
const trust = await sl.getTrust('my-agent');
const risk = await sl.classifyRisk('chatbot for customer support');
```

## MCP Server

SoulLedger is also available as an MCP server:
- Endpoint: `https://mcp.sputnikx.xyz/mcp`
- Protocol: Streamable HTTP (MCP 2025-03-26)
- Tools: 13 (search_products, get_prices, trade analytics, soul identity)

## Links

- Landing: https://soulledger.sputnikx.xyz
- Dashboard: https://soulledger.sputnikx.xyz/dashboard
- Agent Directory: https://soulledger.sputnikx.xyz/soul/directory
- Compliance Check: https://soulledger.sputnikx.xyz/compliance
- API Health: https://soulledger.sputnikx.xyz/health