StateSet iCommerce Engine

Infrastructure for autonomous commerce. Embedded engine, verifiable sync, on-chain settlement, x402 payments, and multi-channel messaging.

Skill Files

File	URL
SKILL.md (this file)	`https://docs.stateset.com/stateset-icommerce-skill.md`
QUICKSTART.md	`https://docs.stateset.com/stateset-icommerce-quickstart.md`

Or just read them from the URLs above! Check for updates: Re-fetch these files anytime to see new features!

API Base URLs

Service	Base URL	Purpose
Commerce Engine	Local (embedded)	Core commerce operations (orders, products, customers)
Sequencer	`https://api.sequencer.stateset.com/api/v1`	VES event ordering, proofs, commitments
VES (Sequencer)	`https://api.sequencer.stateset.com/api/v1/ves`	VES v1.0 protocol endpoints
x402 Payments	`https://api.sequencer.stateset.com/api/v1/x402`	Payment intents, batches, settlements

Environment Variables:

export STATESET_API_KEY=sk_live_xxx
export STATESET_SEQUENCER_URL=https://api.sequencer.stateset.com/api/v1

Architecture Overview

StateSet iCommerce is a five-layer infrastructure stack:

Layer	Component	Function
Compute	stateset-embedded	In-process commerce engine
Coordination	stateset-sequencer	Distributed event ordering
Settlement	Set Chain (L2)	On-chain verification
Payments	x402 Protocol	HTTP-native stablecoin payments
Communication	Messaging Gateway	9-channel agent interaction

Install the CLI

npm install -g @stateset/cli

Verify installation:

stateset --version

Recommended: Save your credentials to ~/.config/stateset/config.json:

{
  "api_key": "sk_live_xxx",
  "tenant_id": "your-tenant-id",
  "store_id": "your-store-id",
  "database_path": "~/.stateset/commerce.db"
}

Initialize the Engine

Create a new commerce database:

stateset init --demo

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

SQLite database with 70+ tables
Demo data (customers, products, inventory)
Sync outbox ready for VES

Without demo data:

stateset init

Authentication

Commerce operations run locally via the embedded engine. Sequencer API requests require your API key:

curl https://api.sequencer.stateset.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY"

For CLI operations:

export STATESET_API_KEY=sk_live_xxx
stateset orders list        # Local embedded engine
stateset sync push          # Syncs to sequencer API

Agent Registration

AI agents must register with the sequencer to receive an API key for authentication.

Register a New Agent

curl -X POST https://api.sequencer.stateset.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-commerce-agent",
    "description": "Autonomous commerce agent for order processing"
  }'

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 - it cannot be retrieved later."
}

Important: Store the apiKey securely. It is only returned once and cannot be retrieved later.

Registration Options

Field	Type	Description
`name`	string	Human-readable agent name (required)
`description`	string	Agent purpose description
`tenantId`	UUID	Join existing tenant (optional)
`storeIds`	UUID[]	Restrict to specific stores
`readOnly`	boolean	Read-only permissions (default: false)
`admin`	boolean	Admin permissions (default: false)
`rateLimit`	number	Requests per minute limit

Get Agent Details

curl https://api.sequencer.stateset.com/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Additional API Keys

curl -X POST https://api.sequencer.stateset.com/api/v1/agents/{agent_id}/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "readOnly": true
  }'

List API Keys

curl https://api.sequencer.stateset.com/api/v1/agents/{agent_id}/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Revoke an API Key

curl -X DELETE https://api.sequencer.stateset.com/api/v1/agents/{agent_id}/api-keys/{key_prefix} \
  -H "Authorization: Bearer YOUR_API_KEY"

Register Signing Key (for VES Events)

After registration, agents should register an Ed25519 signing key for VES event signatures:

curl -X POST https://api.sequencer.stateset.com/api/v1/agents/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "keyId": 1,
    "publicKey": "0x1234567890abcdef...",
    "validFrom": "2026-01-30T00:00:00Z",
    "validTo": "2027-01-30T00:00:00Z"
  }'

Core Operations

Customers

# List customers
stateset customers list

# Create customer
stateset customers create --email "alice@example.com" --name "Alice Smith"

# Get customer by email
stateset customers get --email "alice@example.com"

Embedded API (local):

const customer = commerce.customers.create({
  email: 'alice@example.com',
  name: 'Alice Smith'
});

Products

# List products
stateset products list

# Create product
stateset products create --sku "SHOE-001" --name "Running Shoes" --price 99.99

# Get product by SKU
stateset products get --sku "SHOE-001"

Inventory

# Check stock
stateset inventory get --sku "SHOE-001"

# Adjust inventory
stateset inventory adjust --sku "SHOE-001" --quantity 100 --reason "Initial stock"

# Reserve inventory
stateset inventory reserve --sku "SHOE-001" --quantity 5 --reference "ORD-123"

Orders

# List orders
stateset orders list

# Create order
stateset orders create --customer-email "alice@example.com" --items '[{"sku":"SHOE-001","qty":2}]'

# Get order
stateset orders get --id "ord_xxx"

# Ship order
stateset orders ship --id "ord_xxx" --carrier "fedex" --tracking "1234567890"

Returns

# Create return
stateset returns create --order-id "ord_xxx" --reason "Defective" --items '[{"sku":"SHOE-001","qty":1}]'

# Approve return
stateset returns approve --id "ret_xxx"

# Complete return
stateset returns complete --id "ret_xxx"

Checkout Flow

Cart Operations

# Create cart
stateset carts create --customer-email "alice@example.com"

# Add item to cart
stateset carts add-item --cart-id "cart_xxx" --sku "SHOE-001" --quantity 2

# Get cart
stateset carts get --id "cart_xxx"

# Checkout
stateset carts checkout --id "cart_xxx" --payment-method "card"

Complete Checkout Flow

# 1. Create cart
CART_ID=$(stateset carts create --customer-email "alice@example.com" --json | jq -r '.id')

# 2. Add items
stateset carts add-item --cart-id $CART_ID --sku "SHOE-001" --quantity 2

# 3. Apply promotion (optional)
stateset carts apply-coupon --cart-id $CART_ID --code "SAVE10"

# 4. Calculate tax
stateset carts calculate-tax --cart-id $CART_ID

# 5. Checkout
stateset carts checkout --cart-id $CART_ID --payment-method "card"

x402 Payments

HTTP-native stablecoin micropayments between AI agents.

Supported Networks

Network	Chain ID	Assets	Status
Set Chain	84532001	ssUSD, USDC	Production
Base	8453	USDC	Production
Ethereum	1	USDC, USDT	Production
Arbitrum	42161	USDC	Production
Optimism	10	USDC	Production
Solana	—	USDC	Production

Create Payment Intent

stateset-pay create \
  --amount "10.00" \
  --asset "USDC" \
  --network "base" \
  --recipient "0x..."

Check Balance

stateset-pay balance --network base

Payment Flow

1. GET /api/products/123
   → HTTP 402 Payment Required
   → { asset: "USDC", amount: "0.001", network: "set-chain", recipient: "0x..." }

2. Agent signs PaymentIntent (Ed25519)

3. GET /api/products/123
   X-Payment: <signed intent>
   → 200 OK
   X-Payment-Receipt: <receipt>

Verifiable Event Sync (VES)

Multi-agent coordination with cryptographic proofs.

Check Sync Status

stateset sync status

Response:

{
  "local_head": 1523,
  "remote_head": 1520,
  "pending_events": 3,
  "last_sync": "2026-01-30T10:15:00Z"
}

Push Events

stateset sync push

Pull Events

stateset sync pull

Full Sync

stateset sync full

View Outbox

stateset sync outbox

Entity History

stateset sync history --entity-type order --entity-id "ord_xxx"

Sequencer API Reference

The StateSet Sequencer provides deterministic event ordering with cryptographic proofs for multi-agent coordination. Base URL: https://api.sequencer.stateset.com

Authentication

All sequencer requests require Bearer token authentication:

curl https://api.sequencer.stateset.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY"

Event Ingestion

Legacy Event Ingestion (without signatures)

curl -X POST https://api.sequencer.stateset.com/api/v1/events/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "events": [{
      "tenant_id": "YOUR_TENANT_ID",
      "store_id": "YOUR_STORE_ID",
      "event_id": "unique-event-uuid",
      "entity_type": "order",
      "entity_id": "ord_001",
      "event_type": "order.created",
      "payload": {
        "order_id": "ord_001",
        "customer_id": "cust_001",
        "total": 99.99,
        "currency": "USD",
        "status": "pending"
      },
      "payload_hash": "sha256_hash_of_canonical_json_payload",
      "timestamp": "2026-01-30T10:00:00Z",
      "created_at": "2026-01-30T10:00:00Z",
      "source_agent": "YOUR_AGENT_ID",
      "version": 1
    }]
  }'

Response:

{
  "batch_id": "81baf3bd-05b3-47f3-9a85-251c0f84e807",
  "events_accepted": 1,
  "events_rejected": 0,
  "assigned_sequence_start": 1,
  "assigned_sequence_end": 1,
  "head_sequence": 1
}

Required Event Fields:

Field	Type	Description
`tenant_id`	UUID	Your tenant ID from registration
`store_id`	UUID	Store identifier
`event_id`	UUID	Unique event identifier
`entity_type`	string	Entity type (order, customer, product, etc.)
`entity_id`	string	Entity identifier
`event_type`	string	Event type (order.created, order.shipped, etc.)
`payload`	object	Event data
`payload_hash`	string	SHA-256 hash of canonical JSON payload
`timestamp`	ISO-8601	Event timestamp
`created_at`	ISO-8601	Creation timestamp
`source_agent`	UUID	Agent ID that created the event
`version`	number	Event version (typically 1)

Computing Payload Hash:

# Canonical JSON (alphabetically sorted keys, no whitespace)
PAYLOAD='{"currency":"USD","customer_id":"cust_001","order_id":"ord_001","status":"pending","total":99.99}'
HASH=$(echo -n "$PAYLOAD" | sha256sum | cut -d' ' -f1)

VES Event Ingestion (with Ed25519 signatures)

POST https://api.sequencer.stateset.com/api/v1/ves/events/ingest

Requires registered signing key. See “Register Signing Key” section above.

Events & Head

# List events
GET https://api.sequencer.stateset.com/api/v1/events

# Get head sequence number
GET https://api.sequencer.stateset.com/api/v1/head

# Get entity history
GET https://api.sequencer.stateset.com/api/v1/entities/{entity_type}/{entity_id}

VES Commitments

# List all commitments
GET https://api.sequencer.stateset.com/api/v1/ves/commitments

# Create new commitment
POST https://api.sequencer.stateset.com/api/v1/ves/commitments

# Create and anchor commitment
POST https://api.sequencer.stateset.com/api/v1/ves/commitments/anchor

# Get specific commitment
GET https://api.sequencer.stateset.com/api/v1/ves/commitments/{batch_id}

VES Validity Proofs (STARK ZK Proofs)

# Get public inputs for proof generation
GET https://api.sequencer.stateset.com/api/v1/ves/validity/{batch_id}/inputs

# List proofs for batch
GET https://api.sequencer.stateset.com/api/v1/ves/validity/{batch_id}/proofs

# Submit external STARK proof
POST https://api.sequencer.stateset.com/api/v1/ves/validity/{batch_id}/proofs
Content-Type: application/json
{
  "proof_data": "base64_encoded_proof",
  "prover": "agent_address"
}

# Get specific proof
GET https://api.sequencer.stateset.com/api/v1/ves/validity/proofs/{proof_id}

# Verify proof
GET https://api.sequencer.stateset.com/api/v1/ves/validity/proofs/{proof_id}/verify

VES Compliance Proofs (Per-Event Encrypted)

# Get compliance inputs for event
POST https://api.sequencer.stateset.com/api/v1/ves/compliance/{event_id}/inputs

# List compliance proofs for event
GET https://api.sequencer.stateset.com/api/v1/ves/compliance/{event_id}/proofs

# Submit compliance proof
POST https://api.sequencer.stateset.com/api/v1/ves/compliance/{event_id}/proofs

# Get specific compliance proof
GET https://api.sequencer.stateset.com/api/v1/ves/compliance/proofs/{proof_id}

# Verify compliance proof
GET https://api.sequencer.stateset.com/api/v1/ves/compliance/proofs/{proof_id}/verify

Inclusion Proofs

# Get inclusion proof for sequence number
GET https://api.sequencer.stateset.com/api/v1/ves/proofs/{sequence_number}

# Verify inclusion proof
POST https://api.sequencer.stateset.com/api/v1/ves/proofs/verify
Content-Type: application/json
{
  "sequence_number": 1523,
  "merkle_proof": {...}
}

On-Chain Anchoring

# Anchor commitment to Set Chain L2
POST https://api.sequencer.stateset.com/api/v1/ves/anchor
Content-Type: application/json
{
  "batch_id": "batch_xxx"
}

# Verify on-chain anchor
GET https://api.sequencer.stateset.com/api/v1/ves/anchor/{batch_id}/verify

Agent Key Management

# Register agent signing key
POST https://api.sequencer.stateset.com/api/v1/agents/keys
Content-Type: application/json
{
  "agent_id": "agent_xxx",
  "public_key": "ed25519_pubkey",
  "permissions": ["read", "write"]
}

Schema Registry

# List all schemas
GET https://api.sequencer.stateset.com/api/v1/schemas

# Register new schema
POST https://api.sequencer.stateset.com/api/v1/schemas
Content-Type: application/json
{
  "event_type": "order.created",
  "schema": {...}
}

# Validate payload against schema
POST https://api.sequencer.stateset.com/api/v1/schemas/validate

# Get schema by ID
GET https://api.sequencer.stateset.com/api/v1/schemas/{schema_id}

# Update schema status
PUT https://api.sequencer.stateset.com/api/v1/schemas/{schema_id}/status

# Delete schema
DELETE https://api.sequencer.stateset.com/api/v1/schemas/{schema_id}

# List schemas by event type
GET https://api.sequencer.stateset.com/api/v1/schemas/event-type/{event_type}

# Get latest schema for event type
GET https://api.sequencer.stateset.com/api/v1/schemas/event-type/{event_type}/latest

x402 Payment Protocol

The x402 protocol enables agent-to-agent stablecoin payments with off-chain signing and batched on-chain settlement.

Payment Flow Overview

Agent generates Ed25519 signing key
Agent registers public key with sequencer
Agent creates and signs payment intent
Sequencer validates signature and sequences payment
Payments are batched and committed (Merkle root computed)
Batch is settled on Set Chain L2
Agent retrieves receipt with inclusion proof

Step 1: Generate and Register Signing Key

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization

# Generate Ed25519 key pair
private_key = Ed25519PrivateKey.generate()
public_key = private_key.public_key()

# Get raw public key bytes (32 bytes)
public_key_bytes = public_key.public_bytes(
    encoding=serialization.Encoding.Raw,
    format=serialization.PublicFormat.Raw
)
public_key_hex = public_key_bytes.hex()

# Register public key with sequencer
curl -X POST https://api.sequencer.stateset.com/api/v1/agents/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "YOUR_TENANT_ID",
    "agentId": "YOUR_AGENT_ID",
    "keyId": 1,
    "publicKey": "PUBLIC_KEY_HEX"
  }'

Step 2: Compute Signing Hash

The signing hash must be computed exactly as the sequencer expects:

import hashlib
import struct

def compute_x402_signing_hash(
    payer_address: str,
    payee_address: str,
    amount: int,           # In smallest units (e.g., 1 USDC = 1000000)
    asset: str,            # "usdc", "usdt", "ssusd"
    network: str,          # "set_chain", "base", "ethereum"
    chain_id: int,         # 84532001 for Set Chain
    valid_until: int,      # Unix timestamp
    nonce: int
) -> bytes:
    hasher = hashlib.sha256()
    hasher.update(b"X402_PAYMENT_V1")           # Domain separator
    hasher.update(payer_address.encode())       # Payer address string
    hasher.update(payee_address.encode())       # Payee address string
    hasher.update(struct.pack(">Q", amount))    # u64 big-endian
    hasher.update(asset.encode())               # Asset string
    hasher.update(network.encode())             # Network string
    hasher.update(struct.pack(">Q", chain_id))  # u64 big-endian
    hasher.update(struct.pack(">Q", valid_until))  # u64 big-endian
    hasher.update(struct.pack(">Q", nonce))     # u64 big-endian
    return hasher.digest()

Step 3: Sign and Submit Payment Intent

import time
import requests

# Payment parameters
payer_address = "0x..."  # Your wallet address
payee_address = "0x..."  # Recipient wallet address
amount = 1000000         # 1 USDC (6 decimals)
asset = "usdc"
network = "set_chain"
chain_id = 84532001
valid_until = int(time.time()) + 3600  # Valid for 1 hour
nonce = 1

# Compute signing hash
signing_hash = compute_x402_signing_hash(
    payer_address, payee_address, amount, asset,
    network, chain_id, valid_until, nonce
)

# Sign with Ed25519 private key
signature = private_key.sign(signing_hash)

# Submit payment intent
response = requests.post(
    "https://api.sequencer.stateset.com/api/v1/x402/payments",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "tenant_id": TENANT_ID,
        "store_id": STORE_ID,
        "agent_id": AGENT_ID,
        "payer_address": payer_address,
        "payee_address": payee_address,
        "amount": amount,
        "asset": asset,
        "network": network,
        "valid_until": valid_until,
        "nonce": nonce,
        "signing_hash": f"0x{signing_hash.hex()}",
        "payer_signature": f"0x{signature.hex()}",
        "payer_public_key": f"0x{public_key_hex}",
        "description": "Payment for services",
        "idempotency_key": "unique-payment-id"
    }
)

# Response:
# {
#   "intent_id": "c0dbf4b1-b281-41d4-88c4-5839bc3761f0",
#   "status": "sequenced",
#   "sequence_number": 1,
#   "sequenced_at": "2026-01-30T20:36:40Z"
# }

Step 4: Create and Commit Batch

curl -X POST https://api.sequencer.stateset.com/api/v1/x402/batches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT_ID",
    "store_id": "YOUR_STORE_ID",
    "network": "set_chain"
  }'

# Response:
# {
#   "batch_id": "92905fab-faff-4440-9d79-2d6d6de8c98b",
#   "status": "committed",
#   "payment_count": 1,
#   "merkle_root": "0xe747946052625166d51d89b7d3da000fed1577dcc8f11231982de13b3b916cf8",
#   "sequence_range": [1, 1]
# }

Step 5: Settle Batch On-Chain

curl -X POST https://api.sequencer.stateset.com/api/v1/x402/batches/settle \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "92905fab-faff-4440-9d79-2d6d6de8c98b"
  }'

# Response:
# {
#   "batch_id": "92905fab-faff-4440-9d79-2d6d6de8c98b",
#   "status": "submitted",
#   "tx_hash": "0x...",
#   "message": "Batch settlement initiated"
# }

Step 6: Get Payment Receipt

curl https://api.sequencer.stateset.com/api/v1/x402/payments/{intent_id}/receipt \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "receipt": {
#     "receipt_id": "ee5876bc-f728-4049-9769-7ad81313bd1f",
#     "intent_id": "c0dbf4b1-b281-41d4-88c4-5839bc3761f0",
#     "sequence_number": 1,
#     "batch_id": "92905fab-faff-4440-9d79-2d6d6de8c98b",
#     "merkle_root": "0xe747946052625166d51d89b7d3da000fed1577dcc8f11231982de13b3b916cf8",
#     "inclusion_proof": [...],
#     "leaf_index": 0,
#     "payer_address": "0x...",
#     "payee_address": "0x...",
#     "amount": 1000000,
#     "asset": "usdc",
#     "tx_hash": "0x..."
#   }
# }

x402 API Reference

Method	Endpoint	Description
POST	`/api/v1/x402/payments`	Submit payment intent
GET	`/api/v1/x402/payments`	List payment intents
GET	`/api/v1/x402/payments/{id}`	Get payment status
GET	`/api/v1/x402/payments/{id}/receipt`	Get payment receipt
POST	`/api/v1/x402/batches`	Create and commit batch
GET	`/api/v1/x402/batches/{id}`	Get batch status
POST	`/api/v1/x402/batches/settle`	Settle batch on-chain

Supported Networks

Network	Chain ID	Description
`set_chain`	84532001	Set Chain L2 (primary)
`set_chain_testnet`	84532002	Set Chain testnet
`base`	8453	Base L2
`base_sepolia`	84532	Base testnet
`ethereum`	1	Ethereum mainnet
`arbitrum`	42161	Arbitrum One
`optimism`	10	Optimism

Supported Assets

Asset	Description
`usdc`	USD Coin
`usdt`	Tether
`ssusd`	StateSet USD (yield-bearing)
`wssusd`	Wrapped StateSet USD (ERC-4626)
`dai`	DAI Stablecoin

Complete Agent-to-Agent Payment Example

"""
Complete x402 payment flow between two AI agents.
Agent A pays Agent B 1 USDC for services rendered.
"""
import hashlib
import struct
import time
import requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization

# ============================================================
# Step 1: Register Agent A (if not already registered)
# ============================================================
registration = requests.post(
    "https://api.sequencer.stateset.com/api/v1/agents/register",
    json={"name": "agent-a", "description": "Payer agent"}
)
agent_a = registration.json()
# agent_a = {"agentId": "...", "tenantId": "...", "apiKey": "ss_..."}

# ============================================================
# Step 2: Generate and register signing key for Agent A
# ============================================================
private_key = Ed25519PrivateKey.generate()
public_key_bytes = private_key.public_key().public_bytes(
    encoding=serialization.Encoding.Raw,
    format=serialization.PublicFormat.Raw
)

requests.post(
    "https://api.sequencer.stateset.com/api/v1/agents/keys",
    headers={"Authorization": f"Bearer {agent_a['apiKey']}"},
    json={
        "tenantId": agent_a["tenantId"],
        "agentId": agent_a["agentId"],
        "keyId": 1,
        "publicKey": public_key_bytes.hex()
    }
)

# ============================================================
# Step 3: Create and sign payment intent
# ============================================================
payer_address = "0xAgentAWalletAddress1234567890abcdef"
payee_address = "0xAgentBWalletAddress1234567890abcdef"
amount = 1000000  # 1 USDC
valid_until = int(time.time()) + 3600
nonce = 1

# Compute signing hash (must match sequencer's format exactly)
hasher = hashlib.sha256()
hasher.update(b"X402_PAYMENT_V1")
hasher.update(payer_address.encode())
hasher.update(payee_address.encode())
hasher.update(struct.pack(">Q", amount))
hasher.update(b"usdc")
hasher.update(b"set_chain")
hasher.update(struct.pack(">Q", 84532001))  # chain_id
hasher.update(struct.pack(">Q", valid_until))
hasher.update(struct.pack(">Q", nonce))
signing_hash = hasher.digest()

signature = private_key.sign(signing_hash)

# ============================================================
# Step 4: Submit payment intent
# ============================================================
payment = requests.post(
    "https://api.sequencer.stateset.com/api/v1/x402/payments",
    headers={"Authorization": f"Bearer {agent_a['apiKey']}"},
    json={
        "tenant_id": agent_a["tenantId"],
        "store_id": "00000000-0000-0000-0000-000000000001",
        "agent_id": agent_a["agentId"],
        "payer_address": payer_address,
        "payee_address": payee_address,
        "amount": amount,
        "asset": "usdc",
        "network": "set_chain",
        "valid_until": valid_until,
        "nonce": nonce,
        "signing_hash": f"0x{signing_hash.hex()}",
        "payer_signature": f"0x{signature.hex()}",
        "payer_public_key": f"0x{public_key_bytes.hex()}",
        "description": "Payment from Agent A to Agent B"
    }
).json()
# payment = {"intent_id": "...", "status": "sequenced", "sequence_number": 1}

# ============================================================
# Step 5: Create and commit batch
# ============================================================
batch = requests.post(
    "https://api.sequencer.stateset.com/api/v1/x402/batches",
    headers={"Authorization": f"Bearer {agent_a['apiKey']}"},
    json={
        "tenant_id": agent_a["tenantId"],
        "store_id": "00000000-0000-0000-0000-000000000001",
        "network": "set_chain"
    }
).json()
# batch = {"batch_id": "...", "status": "committed", "merkle_root": "0x..."}

# ============================================================
# Step 6: Settle batch on-chain
# ============================================================
settlement = requests.post(
    "https://api.sequencer.stateset.com/api/v1/x402/batches/settle",
    headers={"Authorization": f"Bearer {agent_a['apiKey']}"},
    json={"batch_id": batch["batch_id"]}
).json()

# ============================================================
# Step 7: Get payment receipt with inclusion proof
# ============================================================
receipt = requests.get(
    f"https://api.sequencer.stateset.com/api/v1/x402/payments/{payment['intent_id']}/receipt",
    headers={"Authorization": f"Bearer {agent_a['apiKey']}"}
).json()

print(f"Payment complete!")
print(f"Intent ID: {payment['intent_id']}")
print(f"Batch ID: {batch['batch_id']}")
print(f"Merkle Root: {batch['merkle_root']}")
print(f"Receipt ID: {receipt['receipt']['receipt_id']}")

Health & Status

# Basic health check
GET https://api.sequencer.stateset.com/health

# Readiness check (includes DB)
GET https://api.sequencer.stateset.com/ready

# Detailed component health
GET https://api.sequencer.stateset.com/health/detailed

Legacy Endpoints

# Legacy commitments
GET https://api.sequencer.stateset.com/api/v1/commitments
POST https://api.sequencer.stateset.com/api/v1/commitments
GET https://api.sequencer.stateset.com/api/v1/commitments/{batch_id}

# Legacy proofs
GET https://api.sequencer.stateset.com/api/v1/proofs/{sequence_number}
POST https://api.sequencer.stateset.com/api/v1/proofs/verify

# Legacy anchoring
GET https://api.sequencer.stateset.com/api/v1/anchor/status
POST https://api.sequencer.stateset.com/api/v1/anchor
GET https://api.sequencer.stateset.com/api/v1/anchor/{batch_id}/verify

Agent Integration Patterns

Full Sync Flow for Agents

# 1. Ingest local commerce events to sequencer
curl -X POST https://api.sequencer.stateset.com/api/v1/ves/events/ingest \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "event_id": "evt_001",
      "event_type": "order.created",
      "entity_type": "order",
      "entity_id": "ord_xxx",
      "payload": {"customer_id": "cust_xxx", "total": 99.99}
    }]
  }'

# 2. Get sequencer receipt with sequence number
# Response includes: sequence_number, merkle_root, signature

# 3. Create commitment batch
curl -X POST https://api.sequencer.stateset.com/api/v1/ves/commitments \
  -H "Authorization: Bearer $STATESET_API_KEY"

# 4. Anchor to Set Chain
curl -X POST https://api.sequencer.stateset.com/api/v1/ves/anchor \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -d '{"batch_id": "batch_xxx"}'

# 5. Verify on-chain
curl https://api.sequencer.stateset.com/api/v1/ves/anchor/batch_xxx/verify \
  -H "Authorization: Bearer $STATESET_API_KEY"

Multi-Agent Coordination

// Agent A: Create order and sync
const order = await commerce.orders.create({...});
const receipt = await fetch('https://api.sequencer.stateset.com/api/v1/ves/events/ingest', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: JSON.stringify({
    events: [{
      event_type: 'order.created',
      entity_type: 'order',
      entity_id: order.id,
      payload: order
    }]
  })
}).then(r => r.json());

// Agent B: Pull events and verify
const head = await fetch('https://api.sequencer.stateset.com/api/v1/head', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
}).then(r => r.json());

const proof = await fetch(`https://api.sequencer.stateset.com/api/v1/ves/proofs/${receipt.sequence_number}`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
}).then(r => r.json());

MCP Tool Integration

The CLI exposes 700+ commerce operations via MCP for AI agents.

Start MCP Server

stateset mcp serve

Tool Categories

Domain	Examples
Customers	list_customers, get_customer, create_customer
Orders	create_order, ship_order, cancel_order
Products	list_products, create_product
Inventory	get_stock, adjust_inventory, reserve_inventory
Returns	create_return, approve_return
Carts	create_cart, add_cart_item, checkout
Payments	create_payment, process_refund
Analytics	get_sales_summary, get_demand_forecast
Sync	sync_status, sync_push, sync_pull

Permission Model

# Read operations - always allowed
stateset "list orders"

# Write operations - blocked by default
stateset "create an order"
# → Shows preview, does not execute

# Write operations - enabled with --apply
stateset --apply "create an order for alice@example.com"
# → Executes operation

Multi-Channel Messaging

Supported Channels

Channel	Protocol	Status
WhatsApp	Cloud API	GA
Telegram	Bot API	GA
Discord	Gateway + REST	GA
Slack	Events + Web API	GA
Signal	signal-cli	GA
Google Chat	Spaces API	GA
WebChat	WebSocket	GA
iMessage	AppleScript	Experimental
Teams	Bot Framework	Experimental

Launch Channels

# All configured channels
stateset-channels

# Specific channels
stateset-whatsapp
stateset-discord
stateset-telegram
stateset-slack

Configuration

Create ~/.stateset/channels.json:

{
  "whatsapp": {
    "enabled": true,
    "phone_number_id": "xxx",
    "access_token": "xxx"
  },
  "discord": {
    "enabled": true,
    "bot_token": "xxx",
    "guild_id": "xxx"
  }
}

Warehouse Operations

Warehouse Management

# Create warehouse
stateset warehouse create --name "Main DC" --address "123 Warehouse Ave"

# Add zone
stateset warehouse add-zone --warehouse-id "wh_xxx" --name "Picking Zone A"

# Add location
stateset warehouse add-location --zone-id "zone_xxx" --name "A-01-01"

Fulfillment

# Create wave
stateset fulfillment create-wave --warehouse-id "wh_xxx" --orders '["ord_xxx", "ord_yyy"]'

# Assign pick task
stateset fulfillment assign-pick --task-id "pick_xxx" --picker "user_xxx"

# Complete pick
stateset fulfillment complete-pick --task-id "pick_xxx"

# Pack
stateset fulfillment pack --wave-id "wave_xxx"

# Ship
stateset fulfillment ship --wave-id "wave_xxx"

Receiving

# Create receipt
stateset receiving create --po-id "po_xxx" --expected-date "2026-02-01"

# Receive items
stateset receiving receive-items --receipt-id "rec_xxx" --items '[{"sku":"SHOE-001","qty":100}]'

# Put away
stateset receiving put-away --receipt-id "rec_xxx" --location "A-01-01"

Financial Operations

General Ledger

# Create account
stateset gl create-account --number "1000" --name "Cash" --type "asset"

# Post journal entry
stateset gl post-entry --debit '{"account":"1000","amount":100}' --credit '{"account":"4000","amount":100}'

# Trial balance
stateset gl trial-balance

# Close period
stateset gl close-period --period "2026-01"

Accounts Receivable

# AR aging
stateset ar aging

# Apply payment
stateset ar apply-payment --customer-id "cust_xxx" --amount 500 --invoice-id "inv_xxx"

# Generate statement
stateset ar generate-statement --customer-id "cust_xxx"

Accounts Payable

# Create bill
stateset ap create-bill --supplier-id "sup_xxx" --amount 1000 --due-date "2026-02-15"

# Schedule payment
stateset ap schedule-payment --bill-id "bill_xxx" --date "2026-02-10"

# AP aging
stateset ap aging

Vector Search

Hybrid semantic + BM25 search across commerce entities.

# Index products
stateset vector index-products

# Search products
stateset vector search --query "red running shoes under $100" --limit 10

# Index customers
stateset vector index-customers

# Search customers
stateset vector search-customers --query "enterprise accounts in California"

Heartbeat Monitor

Proactive health checking for commerce operations.

Built-in Checkers

Checker	Trigger	Action
`low-stock`	Stock below threshold	Alert, auto-reorder
`abandoned-carts`	Cart idle > timeout	Recovery notification
`revenue-milestone`	Target reached/missed	Dashboard alert
`pending-returns`	Return aging > days	Escalation
`overdue-invoices`	Invoice past due	Collection notification
`subscription-churn`	Cancellation spike	Retention campaign

CLI

# Health status
stateset heartbeat status

# Trigger check
stateset heartbeat run low-stock

# Enable/disable checker
stateset heartbeat enable low-stock
stateset heartbeat disable low-stock

Skills System

38 built-in skills covering the full commerce lifecycle.

Install Skills

npm install -g @stateset/icommerce-skills
icommerce-skills list
icommerce-skills install

Skill Categories

Core Commerce:

commerce-engine-setup
commerce-embedded-sdk
commerce-customers
commerce-products
commerce-orders
commerce-checkout
commerce-payments

Inventory & Fulfillment:

commerce-inventory
commerce-shipments
commerce-returns
commerce-backorders
commerce-fulfillment
commerce-receiving
commerce-warehouse
commerce-lots-and-serials

Financial:

commerce-invoices
commerce-tax
commerce-currency
commerce-accounts-payable
commerce-accounts-receivable
commerce-cost-accounting
commerce-credit
commerce-general-ledger

Platform:

commerce-sync
commerce-autonomous-engine
commerce-vector-search
commerce-mcp-tools

Language Bindings

The Rust core compiles to 10 target runtimes:

Runtime	Technology	Use Case
Native Rust	Direct linking	High-performance backends
Node.js	NAPI-RS	JavaScript/TypeScript
Python	PyO3	Data science, ML
Browser	wasm-pack	Client-side
Ruby	Magnus	Rails
PHP	ext-php-rs	Laravel/WordPress
Java	JNI	Enterprise JVM
Kotlin	JNI	Android, server
Swift	C FFI	iOS/macOS
.NET/C#	P/Invoke	ASP.NET, Unity
Go	cgo	Go microservices

Node.js Example

const { Commerce } = require('@stateset/embedded');

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

// Create customer
const customer = commerce.customers.create({
  email: 'alice@example.com',
  name: 'Alice Smith'
});

// Create order
const order = commerce.orders.create({
  customerId: customer.id,
  items: [{ sku: 'SHOE-001', quantity: 2 }]
});

console.log(`Order created: ${order.id}`);

Python Example

from stateset_embedded import Commerce

commerce = Commerce('~/.stateset/commerce.db')

# Create customer
customer = commerce.customers.create(
    email='alice@example.com',
    name='Alice Smith'
)

# Create order
order = commerce.orders.create(
    customer_id=customer.id,
    items=[{'sku': 'SHOE-001', 'quantity': 2}]
)

print(f'Order created: {order.id}')

Response Format

Success:

{"success": true, "data": {...}}

Error:

{"success": false, "error": "Description", "hint": "How to fix"}

Rate Limits

Limit	Value
API requests	1000/minute
Write operations	100/minute
Sync operations	10/minute
Vector search	100/minute

System Statistics

Component	Metric	Value
stateset-core	Lines of Code	~45,000
stateset-db	Lines of Code	~55,000
stateset-embedded	Lines of Code	~39,000
stateset-sequencer	Lines of Code	~33,000
Total Rust	Lines of Code	~172,000
Domain Modules	Count	32
Domain Types	Count	400+
Database Tables	Count	70+
Commerce API Methods	Count	700+
Sequencer API Endpoints	Count	40+
Language Bindings	Count	10
Commerce Skills	Count	38
Messaging Channels	Count	9

Everything You Can Do

Action	What it does
Create orders	Process commerce transactions
Manage inventory	Track stock, reservations, adjustments
Process returns	Handle RMAs and refunds
Run fulfillment	Pick, pack, ship workflows
Accept payments	x402 stablecoin payments
Sync events	VES multi-agent coordination via sequencer
Generate proofs	Merkle inclusion + STARK ZK proofs
Anchor on-chain	Set Chain L2 commitment anchoring
Register schemas	Event type validation
Search products	Hybrid semantic + keyword search
Message customers	9-channel omnichannel support
Run analytics	Sales reports, forecasts
Manage finances	GL, AP, AR, tax

Quick Reference

CLI Commands

# Engine
stateset init [--demo]
stateset status

# Customers
stateset customers list|get|create|update|delete

# Products
stateset products list|get|create|update|delete

# Inventory
stateset inventory get|adjust|reserve|release

# Orders
stateset orders list|get|create|ship|cancel

# Returns
stateset returns list|get|create|approve|complete

# Sync
stateset sync status|push|pull|full|outbox

# Payments
stateset-pay create|balance|verify

# Channels
stateset-channels
stateset-whatsapp|discord|telegram|slack

Sequencer API Quick Reference

# Base URL: https://api.sequencer.stateset.com

# Agent Registration (start here!)
POST   /api/v1/agents/register              # Register agent, get API key
GET    /api/v1/agents/{agent_id}            # Get agent details
POST   /api/v1/agents/{agent_id}/api-keys   # Create additional API key
GET    /api/v1/agents/{agent_id}/api-keys   # List agent's API keys
DELETE /api/v1/agents/{agent_id}/api-keys/{pfx} # Revoke API key

# Agent Signing Keys (for VES)
POST   /api/v1/agents/keys                  # Register Ed25519 signing key

# Event Ingestion
POST   /api/v1/events/ingest                # Ingest events (legacy)
POST   /api/v1/ves/events/ingest            # Ingest VES events (signed)
GET    /api/v1/events                       # List events
GET    /api/v1/head                         # Get head sequence
GET    /api/v1/entities/{type}/{id}         # Entity history

# VES Commitments
GET    /api/v1/ves/commitments              # List commitments
POST   /api/v1/ves/commitments              # Create commitment
POST   /api/v1/ves/commitments/anchor       # Commit and anchor
GET    /api/v1/ves/commitments/{batch_id}   # Get commitment

# VES Validity Proofs
GET    /api/v1/ves/validity/{batch_id}/inputs   # Get proof inputs
GET    /api/v1/ves/validity/{batch_id}/proofs   # List proofs
POST   /api/v1/ves/validity/{batch_id}/proofs   # Submit proof
GET    /api/v1/ves/validity/proofs/{id}/verify  # Verify proof

# VES Compliance Proofs
POST   /api/v1/ves/compliance/{event_id}/inputs  # Get inputs
GET    /api/v1/ves/compliance/{event_id}/proofs  # List proofs
POST   /api/v1/ves/compliance/{event_id}/proofs  # Submit proof

# Inclusion Proofs
GET    /api/v1/ves/proofs/{sequence_number}     # Get proof
POST   /api/v1/ves/proofs/verify                # Verify proof

# Anchoring
POST   /api/v1/ves/anchor                       # Anchor to chain
GET    /api/v1/ves/anchor/{batch_id}/verify     # Verify on-chain

# Schemas
GET    /api/v1/schemas                          # List schemas
POST   /api/v1/schemas                          # Register schema
POST   /api/v1/schemas/validate                 # Validate payload
GET    /api/v1/schemas/event-type/{type}/latest # Latest schema

# x402 Payments
POST   /api/v1/x402/payments                # Submit intent
GET    /api/v1/x402/payments/{id}           # Get status
GET    /api/v1/x402/payments/{id}/receipt   # Get receipt
POST   /api/v1/x402/batches/settle          # Settle batch

# Health
GET    /health                              # Basic health
GET    /ready                               # Readiness
GET    /health/detailed                     # Component health

Ideas to Try

Register your AI agent with the sequencer to get an API key
Set up the embedded engine with demo data
Create a multi-step order flow with cart → checkout → fulfillment
Configure VES sync between multiple agents using the sequencer
Enable x402 payments for agent-to-agent commerce
Ingest events and generate inclusion proofs via sequencer API
Anchor commitments on-chain and verify with STARK proofs
Register custom event schemas for domain-specific events
Set up WhatsApp or Discord for customer support
Run vector search for product discovery
Configure heartbeat monitors for low-stock alerts
Build a storefront with stateset scaffold

StateSet iCommerce v1.22.0 July 2026

Sync Server gRPC Dispatch Flow StateSet Sandbox Skill

​StateSet iCommerce Engine

​Skill Files

​API Base URLs

​Architecture Overview

​Install the CLI

​Initialize the Engine

​Authentication

​Agent Registration

​Register a New Agent

​Registration Options

​Get Agent Details

​Create Additional API Keys

​List API Keys

​Revoke an API Key

​Register Signing Key (for VES Events)

​Core Operations

​Customers

​Products

​Inventory

​Orders

​Returns

​Checkout Flow

​Cart Operations

​Complete Checkout Flow

​x402 Payments

​Supported Networks

​Create Payment Intent

​Check Balance

​Payment Flow

​Verifiable Event Sync (VES)

​Check Sync Status

​Push Events

​Pull Events

​Full Sync

​View Outbox

​Entity History

​Sequencer API Reference

​Authentication

​Event Ingestion

​Events & Head

​VES Commitments

​VES Validity Proofs (STARK ZK Proofs)

​VES Compliance Proofs (Per-Event Encrypted)

​Inclusion Proofs

​On-Chain Anchoring

​Agent Key Management

​Schema Registry

​x402 Payment Protocol

​Payment Flow Overview

​Step 1: Generate and Register Signing Key

​Step 2: Compute Signing Hash

​Step 3: Sign and Submit Payment Intent

​Step 4: Create and Commit Batch

​Step 5: Settle Batch On-Chain

​Step 6: Get Payment Receipt

​x402 API Reference

​Supported Networks

​Supported Assets

​Complete Agent-to-Agent Payment Example

​Health & Status

​Legacy Endpoints

​Agent Integration Patterns

​Full Sync Flow for Agents

​Multi-Agent Coordination

​MCP Tool Integration

​Start MCP Server

​Tool Categories

​Permission Model

​Multi-Channel Messaging

​Supported Channels

​Launch Channels

​Configuration

​Warehouse Operations

​Warehouse Management

​Fulfillment

​Receiving

​Financial Operations

​General Ledger

​Accounts Receivable

​Accounts Payable

StateSet iCommerce Engine

Skill Files

API Base URLs

Architecture Overview

Install the CLI

Initialize the Engine

Authentication

Agent Registration

Register a New Agent

Registration Options

Get Agent Details

Create Additional API Keys

List API Keys

Revoke an API Key

Register Signing Key (for VES Events)

Core Operations

Customers

Products

Inventory

Orders

Returns

Checkout Flow

Cart Operations

Complete Checkout Flow

x402 Payments

Supported Networks

Create Payment Intent

Check Balance

Payment Flow

Verifiable Event Sync (VES)

Check Sync Status

Push Events

Pull Events

Full Sync

View Outbox

Entity History

Sequencer API Reference

Authentication

Event Ingestion

Events & Head

VES Commitments

VES Validity Proofs (STARK ZK Proofs)

VES Compliance Proofs (Per-Event Encrypted)

Inclusion Proofs

On-Chain Anchoring

Agent Key Management

Schema Registry

x402 Payment Protocol

Payment Flow Overview

Step 1: Generate and Register Signing Key

Step 2: Compute Signing Hash

Step 3: Sign and Submit Payment Intent

Step 4: Create and Commit Batch

Step 5: Settle Batch On-Chain

Step 6: Get Payment Receipt

x402 API Reference

Supported Networks

Supported Assets

Complete Agent-to-Agent Payment Example

Health & Status

Legacy Endpoints

Agent Integration Patterns

Full Sync Flow for Agents

Multi-Agent Coordination

MCP Tool Integration

Start MCP Server

Tool Categories

Permission Model

Multi-Channel Messaging

Supported Channels

Launch Channels

Configuration

Warehouse Operations

Warehouse Management

Fulfillment

Receiving

Financial Operations

General Ledger

Accounts Receivable

Accounts Payable