Skip to main content

​
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

npm install -g @stateset/cli
Verify installation: 
stateset --version

​
Step 2: Register Your Agent

Register with the sequencer to get an API key for multi-agent coordination: 
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: 
{
  "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

# 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: 
{
  "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: 
stateset-sync status

​
Step 5: Run Your First Agent Command

​
Read-Only Query

stateset "List all customers"

​
Write Operation

stateset --apply "Create a customer named Alice Smith with email [email protected]"

​
With Sync (Multi-Agent)

stateset --apply --sync "Create an order for customer [email protected]"

​
Step 6: Start Autonomous Engine

Run the full autonomous engine with scheduled jobs and workflows: 
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

stateset "List customers"
stateset --apply "Create customer John Doe with email [email protected]"
stateset "Get customer by email [email protected]"

​
Order Operations

stateset "List pending orders"
stateset --apply "Create order for customer [email protected] with SKU-001 quantity 2"
stateset --apply "Ship order ORD-123 with tracking 1Z999AA10123456784"

​
Inventory Operations

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

stateset "List pending returns"
stateset --apply "Create return for order ORD-123 reason defective"
stateset --apply "Approve return RET-456"

​
Sync Operations

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)

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 [email protected]",
  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: 
export STATESET_AGENT_NAME="order-agent"
stateset-autonomous start --db ./order-agent.db --port 3001
Terminal 2 - Inventory Agent: 
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

# 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

JobScheduleDescription
process-ordersEvery 5 minProcess pending orders
check-inventoryHourlyCheck low stock levels
sync-eventsEvery 10 minSync with sequencer
cleanup-cartsDailyAbandon 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

# 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

stateset init --demo

​
Sync not connecting

# Check config
cat ~/.stateset/sync-config.json

# Test connection
stateset-sync status

​
Agent not responding

# 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

CommandDescription
stateset initInitialize 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 startStart autonomous engine
stateset-sync statusCheck sync health
stateset-sync pushPush events to sequencer
stateset-sync pullPull events from sequencer

​
API Endpoints

EndpointPurpose
POST /api/v1/agents/registerRegister new agent
POST /api/v1/ves/events/ingestIngest VES events
GET /api/v1/eventsList events
POST /api/v1/ves/commitmentsCreate commitment
GET /healthHealth check
Base URL: https://api.sequencer.stateset.app
StateSet iCommerce Engine v0.3.2 January 2026