Stateset iCommerce

The SQLite of Commerce - An embedded, zero-dependency commerce engine for autonomous AI agents.

AI agents that reason, decide, and execute—replacing tickets, scripts, and manual operations across your entire commerce stack.

Looking to accept ChatGPT checkout? iCommerce 1.0 pairs with stateset-acp-handler as the reference implementation of the Agentic Commerce Protocol. One container, 60 seconds: npx create-acp-commerce@latest my-store.

🆕 Intelligent Commerce Protocol (ICP). This repo also hosts the open spec and reference implementations of ICP-1.0 — the operational lifecycle layer (quote, escrow, fulfillment, dispute, settlement) that sits between checkout protocols (ACP/AP2) and payment rails (x402/USDC). 40+ end-to-end tests pass on every CI run across HTTP handler, MCP server (Claude Desktop / Cursor / Windsurf), on-chain custody contract, off-chain Settler daemon, and a cross-language conformance suite. Start at ICP.md or jump to the partnership packet.

Install:

cargo add stateset-sdk --features full   # Rust (recommended)
pip install stateset-embedded==1.6.0     # Python
npm install @stateset/[email protected]     # Node.js
npm install -g @stateset/[email protected]       # CLI
gem install stateset_embedded -v 1.6.0   # Ruby

Zero to commerce in 5 lines:

use stateset_sdk::prelude::*;

let commerce = Commerce::new("store.db")?;
let customer = commerce.customers().create(CreateCustomer {
    email: "[email protected]".into(),
    first_name: "Alice".into(),
    last_name: "Smith".into(),
    ..Default::default()
})?;
let order = commerce.orders().create(CreateOrder {
    customer_id: customer.id,
    items: vec![CreateOrderItem {
        sku: "WIDGET-001".into(),
        name: "Widget".into(),
        quantity: 2,
        unit_price: rust_decimal_macros::dec!(29.99),
        ..Default::default()
    }],
    ..Default::default()
})?;
println!("Order {} — ${}", order.order_number, order.total_amount);

No database setup. No config files. No migrations to run. It just works.

10-Minute Quickstart → | API Reference | OpenAPI Spec | Security | Trust Foundation

Why iCommerce

Most commerce platforms expose APIs that AI agents can call. iCommerce is built for AI agents — with the protocol, runtime, and economic primitives that autonomous agents actually need to transact safely:

• 🤝 Agent-to-Agent (A2A) Commerce — agents negotiate, quote, escrow, and settle directly. Reputation and verification built in. Splits, subscriptions, conditional payments, webhook events.
• 💳 x402 Payment Protocol — cryptographically verifiable AI-agent payment intents (Ed25519, replay-protected nonces, optional PQC). On-chain settlement on Solana, SET Chain, Base, Ethereum, Arbitrum.
• 🧠 Autonomous Engine — scheduled jobs, state-machine workflows, policy-as-code rules, webhook event handlers, and human-in-the-loop approvals. One stack to run a business unattended.
• 📜 Policy DSL — declarative, deny-overrides rules with explainable denials. Block agents from writes when limits are exceeded; record the reason for every decision.
• 🛠️ 700+ MCP Tools across 63 domain modules — the largest known domain-specific MCP surface. Discoverable, payable per call via Machine Payments Protocol, replayable, audit-logged.
• 🔐 Verifiable Encrypted Signatures (VES v1.0) — Merkle-anchored event log with Ed25519 + ML-DSA-65 hybrid signatures and X25519 + ML-KEM-768 hybrid encryption. Every state change is signed and reconstructable.
• ⚙️ Embedded engine, not a service — single-process SQLite by default, PostgreSQL when you scale up. No separate database to provision. No network hops between agent and runtime.

Most of the differentiators above are not "coming soon" — they're shipping in v1.0.x. See AGENTIC_COMMERCE.md for the full A2A case study and TRUST_FOUNDATION.md for the security and verification architecture (including the explicit gap inventory: PQC hard finality and SOC 2 are honest "in progress" items, not aspirational claims).

Engine-First Adoption

If the bet is the engine, the primary product surface is the embedded runtime:

• embed @stateset/embedded or stateset-sdk inside the agent host process
• expose tools through @stateset/embedded/openai, @stateset/embedded/generic, @stateset/embedded/langchain, or @stateset/embedded/vercel-ai
• integrate with agent frameworks through native adapters or OpenAI-compatible tool schemas
• treat the MCP server as a distribution path for MCP-native clients, not as the center of the product

Today the embedded toolkit supports:

• OpenAI Responses / Chat Completions style tool loops via @stateset/embedded/openai
• Vercel AI SDK via @stateset/embedded/vercel-ai
• LangChain / LangGraph JS via @stateset/embedded/langchain
• framework-neutral runtimes via @stateset/embedded/generic
• Python agent runtimes via create_embedded_agent_toolkit() in stateset_embedded
• Python framework helpers via create_langchain_tools(), create_crewai_tools(), and create_autogen_tools()
• Python OpenAI helper surface via create_openai_tools() and execute_openai_tool_call()
• Python framework-neutral helper surface via create_tool_descriptors(), create_callable_registry(), and execute_tool()
• Python framework modules via stateset_embedded.langchain, stateset_embedded.crewai, and stateset_embedded.autogen
• MCP-native clients like Claude Desktop / Cursor / Windsurf via the CLI server

For Python ecosystems such as CrewAI or AutoGen, the native Python toolkit now covers core embedded commerce operations with OpenAI-compatible tool schemas, framework-neutral descriptors, and framework adapter helpers. Install stateset-embedded[agents] when you want the optional Python framework dependencies in one step. Use the JS toolkit or MCP server when you need the full registry-generated CLI surface, policy runtime, or priced-tool helpers. The repo also includes dedicated Python example entry points for stateset_embedded.generic, stateset_embedded.openai, stateset_embedded.langchain, stateset_embedded.crewai, and stateset_embedded.autogen under examples/python/, and the shared check:engine-examples gate now exercises both the JS and Python engine examples before release.

Embedded Agent Toolkit (OpenAI / LangGraph / server-side agents)

Use the embedded toolkit when your agent runtime lives inside your application process and wants JSON-schema tools instead of stdio MCP.

npm install @stateset/[email protected] @stateset/[email protected]

import { Commerce } from '@stateset/embedded';
import { createOpenAITools, executeOpenAIToolCall } from '@stateset/embedded/openai';

const commerce = new Commerce('./store.db');
const tools = createOpenAITools(commerce, {
  filter: ['list_customers'],
});
const execution = await executeOpenAIToolCall(commerce, {
  call_id: 'demo_call_1',
  function: {
    name: 'list_customers',
    arguments: '{}',
  },
});
// execution.result.status === 'success'

If your runtime should fan out to specialist agents, pass an autonomousEngine and enable writes for delegation:

const delegatedToolkit = createEmbeddedAgentToolkit({
  commerce,
  allowApply: true,
  autonomousEngine,
});

await delegatedToolkit.executeTool('delegate_to_agent', {
  agent_name: 'orders',
  task_description: 'Review pending orders over $500',
  context: { limit: 10 },
});

delegate_to_agent follows the same safety model as other write tools, so it stays in preview mode until allowApply is enabled.

For OpenAI Responses API loops, executeOpenAIToolCall() returns a ready-to-send function_call_output payload:

const execution = await toolkit.executeOpenAIToolCall(toolCall);

await client.responses.create({
  model: 'gpt-4.1',
  previous_response_id: response.id,
  input: [execution.outputMessage],
  tools,
});

For framework-native and framework-neutral adapters:

import { createVercelAITools } from '@stateset/embedded/vercel-ai';
import { createLangChainTools } from '@stateset/embedded/langchain';
import { createToolDescriptors } from '@stateset/embedded/generic';

const vercelTools = createVercelAITools(commerce, { tool });
const langChainTools = createLangChainTools(commerce, { DynamicStructuredTool });
const genericTools = createToolDescriptors(commerce);

createToolDescriptors() is the lowest-common-denominator adapter surface for runtimes that want { name, description, schema, execute } objects instead of a framework-specific wrapper.

For priced tools and remote MPP-enabled HTTP services, the same toolkit also exposes payment-aware helpers such as getPayableToolCatalog(), prepareToolPayment(), executePaidTool(), discoverRemotePaymentService(), and createRemoteHttpToolDescriptors().

For contract-aware or replay-aware agents, the toolkit also exposes getRuntimeContract(), simulatePlan(), executePlan(), replayMutation(), and getReplayLog().

Use simulateMutation() or executePlan({ dryRun: true, ... }) before enabling writes, then turn on allowApply only for agents that should mutate commerce state.

MCP Server (Claude Desktop / Cursor / Windsurf)

StateSet exposes hundreds of commerce tools via the Model Context Protocol. Add it to your AI editor in one step. The exact current count and policy-domain breakdown are generated from code in the MCP Tool Inventory.

One-command onboarding (including OpenClaw):

npx -y @stateset/cli@latest stateset-setup --yes --quickstart --db ./store.db

This writes an MCP config at .openclaw/mcp.json and wires stateset-mcp-events automatically. It also installs starter guardrail policies + an agent prompt pack under ./.stateset/. --quickstart enables: --demo --agent openclaw --starter-pack ops --agent-only --verify. It also generates ./.stateset/agent-starters/start-mcp.sh and check-mcp.sh for launch + health checks. For a fully explicit run, use:

npx -y @stateset/cli@latest stateset-setup --yes --demo --agent openclaw --starter-pack ops --print-handoff --verify --db ./store.db

Use --agent claude, --agent cursor, or --agent windsurf for those clients, or pass --mcp-config <path> for any MCP-compatible agent runtime. Use --starter-pack support or --starter-pack checkout for different operating modes. Use --agent-only when you only need MCP onboarding and don't want to require a local Anthropic key. Use --verify-strict in CI to fail setup if any readiness warnings are present.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "stateset-commerce": {
      "command": "npx",
      "args": ["-y", "@stateset/cli@latest", "stateset-mcp-events"],
      "env": { "DB_PATH": "./store.db" }
    }
  }
}

Cursor — add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "stateset-commerce": {
      "command": "npx",
      "args": ["-y", "@stateset/cli@latest", "stateset-mcp-events"],
      "env": { "DB_PATH": "./store.db" }
    }
  }
}

This gives your AI assistant access to the full commerce stack: orders, inventory, customers, products, payments, returns, subscriptions, analytics, promotions, manufacturing, A2A commerce, stablecoin payments, and more.

Development toolchain (repo root):

nvm use                      # uses .nvmrc / .node-version (20.20.0)
rustup show active-toolchain # dev toolchain pinned by rust-toolchain.toml (1.90.0)
npm run check                # developer gate for the core workspace surfaces
npm run check:release        # release preflight before cutting a tag

The authoritative remote release gate is the GitHub Actions CI Success job in .github/workflows/ci.yml. A release tag should only be cut from a commit that passes both npm run check:release locally and CI Success remotely.

CI also verifies the workspace MSRV on Rust 1.85 and runs the wider binding and admin surfaces under the same pinned Node 20.20.0 runtime.

What's New in v1.6.0

v1.6.0 completes three-language SDK symmetry on the ICP trust primitives. The Rust and Python SDKs gain verify_settlement_receipt (mirroring the JS helper byte-for-byte), all three first-party SDKs now ship registerWebhook + verifyWebhook + fetchChannelEvents + verifySettlementReceipt, and operator-facing integration guides land under icp-spec/guides/ (merchant integration, Settler implementation, ICPIP-0005 quickstart). See CHANGELOG.md for the full entry.

ICP-1.0 ships all seven core intent verbs — 100% of the addressable commerce verb surface:

• inventory.query — discovery (read-only, highest call volume)
• purchase.create — one-shot retail
• subscription.create — recurring revenue (SaaS, streaming, B2B services)
• subscription.cancel — signed, auditable subscription termination
• purchase.return — returns / refunds with max_refund ceiling
• quote.request — B2B wholesale RFQ (non-binding PriceProposal)
• payout.request — marketplace seller payouts (inverted signing)

The HTTP handler and the MCP server accept all seven; the HTTP handler additionally accepts the channel.register extension verb (ICPIP-0005 push channels).

v1.1.0 introduced the Intelligent Commerce Protocol (ICP) reference implementation set: normative spec, four cross-language conformance IUTs (JavaScript / Rust / Go / Python — all byte-identical), HTTP and MCP transports, on-chain custody contract (15/15 Foundry tests), off-chain Settler daemon, Docker Compose deployment package, Foundation charter, LOI template, and a partnership packet. See CHANGELOG.md for the full release history.

Start at ICP.md for the discoverable entry point.

The 250k-LOC commerce engine continues to ship unchanged — ICP is additive infrastructure, not a refactor.

Documentation

• mdBook docs live in docs/ (see docs/README.md).
• API reference pointers per binding: docs/src/api/.
• End-to-end examples and workflows: examples/.
• Release history: CHANGELOG.md.
• Security policy: SECURITY.md.

Support Matrix

Ruby and PHP are kept in-repo but intentionally excluded from default workspace membership because they require host runtimes or headers that are often unavailable in local dev. They are still exercised in dedicated CI lanes and must not be released from a commit without a green CI Success aggregate.

Release Gate

• Local preflight: npm run check:release
• Remote tag gate: green CI Success in .github/workflows/ci.yml
• Local git hooks are convenience checks only; the release authority is the checked command above plus the protected CI aggregate

Production note: use config/stateset.production.properties as the baseline for secure defaults.

Architecture

This repository is best understood as a platform monorepo with a layered Rust kernel and two large outer product surfaces: language bindings and the Node-based operator runtime.

The current workspace manifests form this dependency direction:

stateset-primitives | stateset-crypto | stateset-pricing | stateset-observability
stateset-policy | stateset-authz | stateset-a2a | stateset-jobs
stateset-migrations | stateset-macros
        ->
stateset-core | stateset-sync
        ->
stateset-db
        ->
stateset-embedded
        ->
stateset-http | stateset-sdk | bindings/*
        ->
admin | cli

What Each Layer Does

Binding Topology

• bindings/node is the shared JS-facing native layer and links directly to stateset-embedded, stateset-core, stateset-db, and stateset-crypto.
• The admin app and CLI both consume @stateset/embedded directly rather than going through stateset-sdk.
• Python and the compiled language bindings also link directly to stateset-embedded and stateset-core; they are not all routed through stateset-ffi.
• stateset-sdk is the Rust-facing facade for consumers that want one dependency with feature-gated re-exports.
• stateset-ffi is an optional C-ABI oriented interop surface, not the mandatory substrate for every binding in this repository.

Operational Surfaces

• cli/ is a large Node 20.20+ runtime with the MCP server, tool registry, sync/x402 logic, agent routing, messaging channels, and scaffolding flows.
• admin/ is a Next.js surface that depends on the local Node binding package and loads @stateset/embedded at runtime.
• The root npm run check pipeline validates release hygiene, Rust fmt/tests/lints/feature-matrix checks, shell scripts, the Node binding, the admin app, and the CLI.
• npm run check:release is the authoritative local release preflight; it extends npm run check with doc-tool validation and generated inventory checks before a tag is cut.

Recommended Onboarding Order

1. stateset-core
2. stateset-db
3. stateset-embedded
4. stateset-sync, stateset-policy, stateset-authz, stateset-pricing
5. stateset-http
6. bindings/node and then admin/ or cli/

For a manifest-grounded dependency walkthrough, see Dependency Direction.

Quick Start

Rust

use stateset_sdk::prelude::*;
use rust_decimal_macros::dec;

// Initialize with a local database file
let commerce = Commerce::new("./store.db")?;

// Create a customer
let customer = commerce.customers().create(CreateCustomer {
    email: "[email protected]".into(),
    first_name: "Alice".into(),
    last_name: "Smith".into(),
    ..Default::default()
})?;

// Create inventory
commerce.inventory().create_item(CreateInventoryItem {
    sku: "SKU-001".into(),
    name: "Widget".into(),
    initial_quantity: Some(dec!(100)),
    ..Default::default()
})?;

// Create an order
let order = commerce.orders().create(CreateOrder {
    customer_id: customer.id,
    items: vec![CreateOrderItem {
        sku: "SKU-001".into(),
        name: "Widget".into(),
        quantity: 2,
        unit_price: dec!(29.99),
        ..Default::default()
    }],
    ..Default::default()
})?;

// Ship the order
commerce.orders().ship(order.id, Some("FEDEX123456".into()))?;

Node.js

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

async function main() {
  const commerce = new Commerce('./store.db');

  // Create a cart and checkout
  const cart = await commerce.carts.create({
    customerEmail: '[email protected]',
    customerName: 'Alice Smith'
  });

  await commerce.carts.addItem(cart.id, {
    sku: 'SKU-001',
    name: 'Widget',
    quantity: 2,
    unitPrice: 29.99
  });

  const result = await commerce.carts.complete(cart.id);
  console.log(`Order created: ${result.orderNumber}`);

  // Convert currency
  const conversion = await commerce.currency.convert({
    from: 'USD',
    to: 'EUR',
    amount: 100
  });
  console.log(`$100 USD = €${conversion.convertedAmount} EUR`);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Python

from stateset_embedded import Commerce

commerce = Commerce('./store.db')

# Get analytics
summary = commerce.analytics.sales_summary(period='last30days')
print(f"Revenue: ${summary.total_revenue}")
print(f"Orders: {summary.order_count}")

# Forecast demand
forecasts = commerce.analytics.demand_forecast(days_ahead=30)
for f in forecasts:
    if f.days_until_stockout and f.days_until_stockout < 14:
        print(f"WARNING: {f.sku} will stock out in {f.days_until_stockout} days")

Other bindings

Same Commerce API surface, idiomatic per language. Expand any block to see the snippet — all ten bindings ship from the same Rust core and pass the same cross-binding parity tests.

require 'stateset_embedded'

commerce = StateSet::Commerce.new('./store.db')

customer = commerce.customers.create(
  email: '[email protected]', first_name: 'Alice', last_name: 'Smith'
)
order = commerce.orders.create(
  customer_id: customer.id,
  items: [{ sku: 'SKU-001', name: 'Widget', quantity: 2, unit_price: 29.99 }]
)
plan = commerce.subscriptions.create_plan(name: 'Pro', price: 29.99, interval: 'month')
commerce.subscriptions.subscribe(plan_id: plan.id, customer_id: customer.id)

<?php
use StateSet\Commerce;

$commerce = new Commerce('./store.db');
$customer = $commerce->customers()->create(
    email: '[email protected]', firstName: 'Alice', lastName: 'Smith'
);
$order = $commerce->orders()->create(
    customerId: $customer->getId(),
    items: [['sku' => 'SKU-001', 'name' => 'Widget', 'quantity' => 2, 'unit_price' => 29.99]]
);
$tax = $commerce->tax()->calculate(amount: 100.00, jurisdictionId: $jur->getId());

import com.stateset.embedded.*;

try (Commerce commerce = new Commerce("./store.db")) {
    Customer customer = commerce.customers().create("[email protected]", "Alice", "Smith");
    Order order = commerce.orders().create(customer.getId(), "USD");
    commerce.payments().recordPayment(order.getId(), order.getTotalAmount(), "card", "txn_123");
    SalesSummary s = commerce.analytics().salesSummary(30);
    System.out.println("Revenue: $" + s.getTotalRevenue());
}

import com.stateset.embedded.*

val commerce = StateSetCommerce("./store.db")
val customer = commerce.customers.create(
    email = "[email protected]", firstName = "Alice", lastName = "Smith"
)
val product = commerce.products.create(name = "Widget", sku = "SKU-001", price = 29.99)
commerce.orders.create(
    customerId = customer.id,
    items = listOf(OrderItem(product.id, "SKU-001", "Widget", 2, "29.99")),
    currency = "USD",
)
commerce.close()

import StateSet

let commerce = try StateSetCommerce(path: "./store.db")
defer { commerce.close() }

let customer = try commerce.customers.create(
    email: "[email protected]", firstName: "Alice", lastName: "Smith"
)
let product = try commerce.products.create(name: "Widget", sku: "SKU-001", price: 29.99)
let order = try commerce.orders.create(
    customerId: customer.id,
    items: [OrderItem(productId: product.id, sku: "SKU-001", name: "Widget", quantity: 2, unitPrice: "29.99")],
    currency: "USD",
)
try commerce.orders.updateStatus(id: order.id, status: .shipped)

using StateSet;

using var commerce = new StateSetCommerce("./store.db");
var customer = commerce.Customers.Create(
    email: "[email protected]", firstName: "Alice", lastName: "Smith"
);
var product = commerce.Products.Create(name: "Widget", sku: "SKU-001", price: 29.99m);
commerce.Orders.Create(
    customerId: customer.Id,
    items: new[] {
        new OrderItem { ProductId = product.Id, Sku = "SKU-001", Name = "Widget", Quantity = 2, UnitPrice = "29.99" }
    },
    currency: "USD",
);

package main

import (
    "fmt"
    "github.com/stateset/stateset-icommerce/bindings/go/stateset"
)

func main() {
    commerce, _ := stateset.New("./store.db")
    defer commerce.Close()

    customer, _ := commerce.Customers().Create("[email protected]", "Alice", "Smith", "")
    product, _ := commerce.Products().Create("Widget", "SKU-001", 29.99, "")
    items := []stateset.OrderItem{{ProductID: product.ID, SKU: "SKU-001", Name: "Widget", Quantity: 2, UnitPrice: "29.99"}}
    order, _ := commerce.Orders().Create(customer.ID, items, "USD")
    fmt.Printf("Order: %s\n", order.OrderNumber)
}

CLI (AI-Powered)

Tip: ss is a shorthand alias for stateset.

# Natural language interface
stateset "show me pending orders"
stateset "what's my revenue this month?"
stateset "convert $100 USD to EUR"

# Execute operations (requires --apply)
stateset --apply "create a cart for [email protected]"
stateset --apply "ship order #12345 with tracking FEDEX123"
stateset --apply "approve return RET-001"

# Tax calculation
stateset "calculate tax for an order shipping to California"
stateset "what's the VAT rate for Germany?"

# Promotions
stateset --apply "create a 20% off promotion called Summer Sale"
stateset "is coupon SAVE20 valid?"
stateset --apply "apply promotions to cart CART-123"

# Subscriptions
stateset "show me all subscription plans"
stateset --apply "create a monthly plan called Pro at $29.99"
stateset --apply "subscribe customer [email protected] to the Pro plan"

# Payments & Refunds
stateset "list payments for order #12345"
stateset --apply "create payment for order #12345 amount $99.99 via card"
stateset --apply "refund payment PAY-001 amount $25.00"

# Shipments
stateset --apply "create shipment for order #12345 via FedEx tracking FEDEX123"
stateset --apply "mark shipment SHIP-001 as delivered"

# Supply Chain
stateset "list purchase orders"
stateset --apply "create purchase order for supplier SUP-001"
stateset --apply "approve purchase order PO-001"

# Invoices (B2B)
stateset "show overdue invoices"
stateset --apply "create invoice for customer CUST-001"
stateset --apply "record payment on invoice INV-001"

# Warranties
stateset "list warranties for customer CUST-001"
stateset --apply "create warranty for product SKU-001"
stateset --apply "file warranty claim for warranty WRN-001"

# Manufacturing
stateset "list bills of materials"
stateset --apply "create BOM for product WIDGET-ASSEMBLED"
stateset --apply "add component SKU-PART-A quantity 2 to BOM-001"
stateset --apply "create work order from BOM-001 quantity 50"
stateset --apply "complete work order WO-001 with 48 units produced"

Agent-to-Agent (A2A) Commerce

AI agents can pay, quote, subscribe, and negotiate with each other autonomously.

# Direct agent-to-agent payment
stateset --apply "pay 10 USDC to 0x1234...5678 on Set Chain"

# Request payment from another agent
stateset --apply "request 50 USDC from 0xBuyer for API credits"

# Quotes — request, provide, accept
stateset --apply "request quote from data provider for 100 API credits"
stateset --apply "provide quote of $150 for premium data access"
stateset --apply "accept quote QT-001 and pay"

# Recurring subscriptions between agents
stateset --apply "create monthly subscription for 0xSubscriber at $49.99 with 14-day trial"
stateset "list active a2a subscriptions"
stateset --apply "pause a2a subscription SUB-001"
stateset --apply "cancel a2a subscription SUB-001"

# Split payments (multi-party)
stateset --apply "create split payment of $100: 70% to 0xSeller, 20% to 0xAffiliate, 10% platform fee"
stateset --apply "execute split paym