> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StateSet iCommerce Quickstart

> Getting started guide for AI agents using the StateSet iCommerce engine

# StateSet iCommerce Quickstart

This guide helps AI agents get up and running with the StateSet iCommerce engine in minutes.

## Overview

StateSet iCommerce provides:

* **Embedded Commerce Engine** - Local SQLite database with 70+ tables
* **Autonomous Agent Runtime** - Scheduled jobs, workflows, policies
* **Multi-Agent Coordination** - Verifiable Event Sync (VES) via sequencer
* **90+ MCP Tools** - Full commerce operations accessible to agents

## Prerequisites

* Node.js 18+
* npm or yarn
* Anthropic API key (for Claude-powered agents)

## Step 1: Install the CLI

```bash theme={null}
npm install -g @stateset/cli
```

Verify installation:

```bash theme={null}
stateset --version
```

## Step 2: Register Your Agent

Register with the sequencer to get an API key for multi-agent coordination:

```bash theme={null}
curl -X POST https://api.sequencer.stateset.app/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-commerce-agent",
    "description": "Autonomous commerce agent"
  }'
```

Response:

```json theme={null}
{
  "success": true,
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "660e8400-e29b-41d4-a716-446655440001",
  "apiKey": "ss_660e8400aBcDeFgHiJkLmNoPqRsTuVwXyZ",
  "permissions": "read_write",
  "message": "Agent registered successfully. Store your API key securely."
}
```

**Save your API key** - it's only shown once.

## Step 3: Initialize Commerce Database

```bash theme={null}
# Create database with demo data
stateset init --demo

# Or create empty database
stateset init
```

This creates `~/.stateset/commerce.db` with:

* 70+ commerce tables (orders, customers, products, inventory, etc.)
* Demo data (if `--demo` flag used)
* Sync outbox for VES events

## Step 4: Configure Sync

Create `~/.stateset/sync-config.json`:

```json theme={null}
{
  "tenantId": "<your-tenant-id>",
  "storeId": "00000000-0000-0000-0000-000000000001",
  "agentId": "<your-agent-id>",
  "sequencerEndpoint": "https://api.sequencer.stateset.app",
  "apiKey": "<your-api-key>",
  "transport": "rest",
  "conflictStrategy": "remote-wins"
}
```

Verify connection:

```bash theme={null}
stateset-sync status
```

## Step 5: Run Your First Agent Command

### Read-Only Query

```bash theme={null}
stateset "List all customers"
```

### Write Operation

```bash theme={null}
stateset --apply "Create a customer named Alice Smith with email alice@example.com"
```

### With Sync (Multi-Agent)

```bash theme={null}
stateset --apply --sync "Create an order for customer alice@example.com"
```

## Step 6: Start Autonomous Engine

Run the full autonomous engine with scheduled jobs and workflows:

```bash theme={null}
stateset-autonomous start --init-defaults --verbose
```

Output:

```
📦 Initializing commerce engine...
🚀 Starting autonomous engine...

📊 Engine Status:
   Scheduler: ✅ Running (7 jobs)
   Workflows: ✅ Ready (4 definitions)
   Policies:  ✅ Loaded (15 policy sets)
   Webhooks:  ✅ Listening on port 3000
   Approvals: ✅ Ready

✨ Autonomous engine is running!
```

***

## Agent Commands Reference

### Customer Operations

```bash theme={null}
stateset "List customers"
stateset --apply "Create customer John Doe with email john@example.com"
stateset "Get customer by email john@example.com"
```

### Order Operations

```bash theme={null}
stateset "List pending orders"
stateset --apply "Create order for customer john@example.com with SKU-001 quantity 2"
stateset --apply "Ship order ORD-123 with tracking 1Z999AA10123456784"
```

### Inventory Operations

```bash theme={null}
stateset "Check stock for SKU-001"
stateset --apply "Adjust inventory for SKU-001 add 100 units"
stateset --apply "Reserve 5 units of SKU-001 for order ORD-123"
```

### Returns Operations

```bash theme={null}
stateset "List pending returns"
stateset --apply "Create return for order ORD-123 reason defective"
stateset --apply "Approve return RET-456"
```

### Sync Operations

```bash theme={null}
stateset-sync status          # Check sync health
stateset-sync push            # Push local events to sequencer
stateset-sync pull            # Pull remote events
stateset-sync history         # View sync history
```

***

## Programmatic Usage (Node.js)

```javascript theme={null}
import { Commerce } from '@stateset/embedded';
import { runAgentLoop } from '@stateset/cli/src/claude-harness.js';

// Initialize commerce engine
const commerce = new Commerce('~/.stateset/commerce.db');

// Run agent task
const result = await runAgentLoop({
  commerce,
  request: "Create an order for alice@example.com",
  allowApply: true,      // Enable write operations
  enableSync: true,      // Capture events for sync
  autoSyncPush: true,    // Auto-push to sequencer
  maxTurns: 10
});

console.log(result.response);
```

***

## Multi-Agent Coordination

### How Agents Coordinate

```
Agent A (Orders)              Sequencer                 Agent B (Inventory)
      │                           │                           │
      │ 1. Create Order           │                           │
      │──────────────────────────>│                           │
      │                           │                           │
      │ 2. Sign & Commit          │                           │
      │──────────────────────────>│                           │
      │                           │ 3. Broadcast Event        │
      │                           │──────────────────────────>│
      │                           │                           │
      │                           │ 4. Reserve Inventory      │
      │                           │<──────────────────────────│
      │                           │                           │
      │ 5. Receive Confirmation   │                           │
      │<──────────────────────────│                           │
```

### Running Multiple Agents

**Terminal 1 - Order Agent:**

```bash theme={null}
export STATESET_AGENT_NAME="order-agent"
stateset-autonomous start --db ./order-agent.db --port 3001
```

**Terminal 2 - Inventory Agent:**

```bash theme={null}
export STATESET_AGENT_NAME="inventory-agent"
stateset-autonomous start --db ./inventory-agent.db --port 3002
```

Both agents sync through the sequencer and coordinate automatically.

***

## Autonomous Engine Features

### Scheduled Jobs

```bash theme={null}
# List jobs
stateset-autonomous jobs

# Run job manually
stateset-autonomous jobs --run process-orders

# Enable/disable job
stateset-autonomous jobs --enable low-stock-alerts
```

### Default Jobs

| Job               | Schedule     | Description            |
| ----------------- | ------------ | ---------------------- |
| `process-orders`  | Every 5 min  | Process pending orders |
| `check-inventory` | Hourly       | Check low stock levels |
| `sync-events`     | Every 10 min | Sync with sequencer    |
| `cleanup-carts`   | Daily        | Abandon old carts      |

### Workflows

Pre-configured workflows for:

* Order fulfillment lifecycle
* Return processing
* Subscription billing
* Inventory replenishment

### Policies

15 policy sets covering:

* Order value limits
* Inventory thresholds
* Return windows
* Discount rules

***

## Environment Variables

```bash theme={null}
# Required
export ANTHROPIC_API_KEY=sk-ant-...

# Optional
export STATESET_DB_PATH=~/.stateset/commerce.db
export STATESET_SYNC_ENDPOINT=https://api.sequencer.stateset.app
export STATESET_API_KEY=ss_...
export STATESET_LOG_LEVEL=info
```

***

## Troubleshooting

### Database not found

```bash theme={null}
stateset init --demo
```

### Sync not connecting

```bash theme={null}
# Check config
cat ~/.stateset/sync-config.json

# Test connection
stateset-sync status
```

### Agent not responding

```bash theme={null}
# Check API key
echo $ANTHROPIC_API_KEY

# Run with verbose
stateset "test" --verbose
```

***

## Next Steps

1. **Explore the CLI** - Run `stateset --help` for all commands
2. **Customize Agents** - Edit `.claude/agents/*.md` for agent personalities
3. **Add Workflows** - Create custom workflows in `.stateset/autonomous/`
4. **Enable Webhooks** - Configure external integrations
5. **Scale Up** - Run multiple agents with different specializations

***

## Quick Reference

| Command                          | Description                    |
| -------------------------------- | ------------------------------ |
| `stateset init`                  | Initialize commerce database   |
| `stateset "query"`               | Run agent query (read-only)    |
| `stateset --apply "task"`        | Run agent task (write enabled) |
| `stateset --apply --sync "task"` | Run with multi-agent sync      |
| `stateset-autonomous start`      | Start autonomous engine        |
| `stateset-sync status`           | Check sync health              |
| `stateset-sync push`             | Push events to sequencer       |
| `stateset-sync pull`             | Pull events from sequencer     |

***

## API Endpoints

| Endpoint                         | Purpose            |
| -------------------------------- | ------------------ |
| `POST /api/v1/agents/register`   | Register new agent |
| `POST /api/v1/ves/events/ingest` | Ingest VES events  |
| `GET /api/v1/events`             | List events        |
| `POST /api/v1/ves/commitments`   | Create commitment  |
| `GET /health`                    | Health check       |

Base URL: `https://api.sequencer.stateset.app`

***

*StateSet iCommerce Engine v0.3.2*
*January 2026*