npm package: @sputnikx/soulledger-node
Description: Run a SoulLedger compute node. Share idle CPU/GPU with AI agents, earn USDC via x402.
Author: SputnikX
Latest version: 0.1.1

<div align="center">

# @sputnikx/soulledger-node

### Your idle GPU is leaving money on the table.

**Share compute with AI agents. Get paid in USDC. One command.**

[![npm version](https://img.shields.io/npm/v/@sputnikx/soulledger-node.svg?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/@sputnikx/soulledger-node)
[![license](https://img.shields.io/npm/l/@sputnikx/soulledger-node.svg?style=flat-square)](./LICENSE)
[![node](https://img.shields.io/node/v/@sputnikx/soulledger-node.svg?style=flat-square)](https://nodejs.org)
[![Base Mainnet](https://img.shields.io/badge/Base-Mainnet-0052FF?style=flat-square)](https://base.org)
[![payments](https://img.shields.io/badge/payments-USDC%20via%20x402-2775CA?style=flat-square)](https://www.x402.org)

</div>

---

AI agents need compute. You have compute sitting idle. SoulLedger Node connects the two and handles payments automatically via the [x402 protocol](https://www.x402.org) on Base.

No crypto wallet setup. No complex configuration. Just run the command.

## Quick Start

```bash
npx @sputnikx/soulledger-node
```

That's it. The node auto-detects your hardware, creates a SoulLedger passport, and starts accepting jobs.

Test your hardware without connecting to the network:

```bash
npx @sputnikx/soulledger-node --dry-run
```

## How It Works

```
 1. DETECT            2. REGISTER           3. PUBLISH            4. EARN
 +-----------+       +-----------+        +-------------+       +----------+
 |  Scan     |  -->  | SoulLedger|  -->   | Marketplace |  -->  |  USDC    |
 |  CPU/GPU  |       | Passport  |        | "I have an  |       |  to your |
 |  RAM/SSD  |       | (SX-ID)   |        |  RTX 4090"  |       |  wallet  |
 +-----------+       +-----------+        +-------------+       +----------+
```

| Step | What happens |
|------|-------------|
| **1. Auto-detect** | Scans CPU, RAM, GPU (NVIDIA), SSD, network bandwidth |
| **2. Register** | Creates a soulbound SoulLedger passport (your node's identity) |
| **3. Publish** | Advertises available resources to AI agents looking for compute |
| **4. Earn** | AI agents pay USDC per hour for the resources they consume |

## Earning Potential

| Hardware | Est. hourly rate | Est. monthly (50% utilization) |
|----------|-----------------|-------------------------------|
| 4-core CPU, 16GB RAM | ~$0.10/hr | ~$36/mo |
| 8-core CPU, 32GB RAM | ~$0.25/hr | ~$90/mo |
| RTX 3080 + 8-core | ~$0.50/hr | ~$180/mo |
| RTX 4090 + 12-core | ~$1.00/hr | ~$360/mo |

> Rates depend on marketplace demand. These are estimates based on current compute pricing.

## Security

Your machine is protected by multiple layers:

| Layer | Protection |
|-------|-----------|
| **Docker sandbox** | Every task runs in an isolated container with no host access |
| **Task screener** | Incoming jobs are analyzed and rejected if suspicious |
| **Resource caps** | You set max CPU %, RAM, and storage limits; the node never exceeds them |
| **Schedule control** | Run only during off-hours (`--schedule="weekdays 22-08"`) |
| **Kill switch** | `Ctrl+C` for immediate graceful shutdown, all containers cleaned up |

Your files, network, and OS are never exposed to agent workloads.

## Configuration

All configuration is optional. The node works out of the box with sensible defaults.

### Environment variables

```bash
SOULLEDGER_API_URL=https://soul.sputnikx.xyz   # API endpoint
SOULLEDGER_API_KEY=sl_...                       # Your API key
SOULLEDGER_AGENT_ID=my-node-01                  # Resume an existing agent
```

### CLI options

```bash
npx @sputnikx/soulledger-node \
  --api-key=sl_abc123 \
  --min-price=0.25 \
  --max-cpu=60 \
  --max-ram=0.5 \
  --max-storage=100 \
  --schedule="weekdays 9-18"
```

| Option | Default | Description |
|--------|---------|-------------|
| `--api-key` | — | SoulLedger API key |
| `--api-url` | `https://soul.sputnikx.xyz` | API endpoint |
| `--agent-id` | auto | Resume existing agent |
| `--max-cpu` | 80 | Max CPU % to offer |
| `--max-ram` | 0.8 | Max RAM fraction (0-1) |
| `--max-storage` | 50 | Max SSD GB to offer |
| `--min-price` | 0.10 | Min price USD/hour |
| `--schedule` | 24/7 | Availability schedule |
| `--dry-run` | false | Test mode, no API calls |

## Programmatic usage

```js
import { SoulLedgerNode } from '@sputnikx/soulledger-node';

const node = new SoulLedgerNode({
  apiKey: 'sl_...',
  minPrice: 0.25,
  maxCpu: 60,
});

await node.start();

// Get status
console.log(node.getStatus());

// Graceful shutdown
await node.stop();
```

## Hardware detection

The node automatically detects:

- **CPU** — model, physical cores, logical threads, clock speed
- **RAM** — total and available memory
- **GPU** — NVIDIA GPUs via `nvidia-smi` (returns null if none found)
- **SSD** — total and available disk space
- **Network** — estimated bandwidth (conservative defaults)
- **OS** — platform, architecture, kernel version

## Pricing

Resources are priced in USDC, paid via the [x402 protocol](https://www.x402.org) on Base. You set the minimum price per hour — the marketplace handles matching with AI agents that need compute. Payments settle on-chain, no intermediaries.

## Requirements

- Node.js >= 18.0.0
- Network connectivity (for publishing availability)
- NVIDIA drivers (optional, for GPU detection)
- Docker (optional, for sandboxed task execution)

## Related

| Package | Description |
|---------|-------------|
| [`@sputnikx/soulledger-sdk`](https://www.npmjs.com/package/@sputnikx/soulledger-sdk) | SDK for agent identity, trust scores, and EU AI Act compliance |
| [`@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)
- **SoulPassport Contract:** [View on BaseScan](https://basescan.org/address/0x9f3bB1BA3fD64F5c0F49dCEC1f873753Ab014779)

## License

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