StateSet iCommerce Engine
The SQLite of commerce. A complete commerce runtime — orders, inventory, checkout, payments, returns, subscriptions, warehouse operations, finance — that runs inside your process against one database file. No hosted control plane, no service account, no rate limit.
For autonomous execution it adds what an AI agent needs before it may spend money: delegated identity, deny-by-default authority, exact budgets, idempotent commands, and cryptographically verifiable receipts.
Start here
Scaffold a working storefront:
npm create stateset-app@latest my-store
Then run it:
cd my-store
cp .env.example .env.local
npm run seed # 10 products, stock, a demo catalog in ./store.db
npm run dev # http://localhost:3000
That is a Next.js storefront with a real commerce engine behind it — the generator and the seed step are covered end to end by the Storefront Golden Path CI job.
Give an AI agent a commerce sandbox
For Claude Desktop, Cursor, Windsurf, or any MCP client:
{
"mcpServers": {
"stateset-commerce": {
"command": "npx",
"args": ["-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--profile", "core"]
}
}
}
Writes are preview-only by default. The core profile — the default —
exposes only the smoke-gated core tier (196 tools); finance, operations,
agents, and all open it up, and --domains a2a,x402 adds individual
domains. Each tool's tier (core, extended, experimental) is listed in
cli/docs/TOOLS.md. Give an agent apply
authority only through operator-owned files, never through tool arguments:
{
"args": [
"-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--apply",
"--kernel-policy", "./kernel-policy.json",
"--kernel-principal", "./kernel-principal.json",
"--kernel-store-id", "store:production"
]
}
For hosted deployments, stateset-mcp-http serves the same tools over MCP
Streamable HTTP (protocol revision 2026-07-28), stateless by construction — no
session ids, a fresh server per request, so it scales across replicas:
npx -y -p @stateset/cli stateset-mcp-http --db ./store.db --port 8090
Add --host 0.0.0.0 to expose it, --read-only to disable writes at the
transport boundary, or --strict-protocol to refuse pre-2026-07-28 clients.
Install
The Ruby and WASM bindings have published packages that are not kept current:
RubyGems stateset_embedded is at 0.1.9 and npm @stateset/embedded-wasm at
0.7.22, both far behind 1.40.0. PHP, Java, Kotlin, Swift, .NET, and Go have no
published package at all — build those from source, and see
docs/src/api/ for each binding's API and install snippet.
Use it
import { Commerce } from '@stateset/embedded';
const commerce = new Commerce('./store.db');
const customer = await commerce.customers.create({
email: '[email protected]',
firstName: 'Ada',
lastName: 'Lovelace',
});
use stateset_sdk::prelude::*;
let commerce = Commerce::new("store.db")?;
let customer = commerce.customers().create(CreateCustomer {
email: "[email protected]".into(),
first_name: "Ada".into(),
last_name: "Lovelace".into(),
..Default::default()
})?;
Amounts are exact decimal values end to end. Every mutation is auditable.
Rust Quickstart → · CLI Quickstart → · Getting Started (all languages) →
Serve a REST API
stateset-http is an embeddable layer, started from your Rust application. It
binds 127.0.0.1:3000 by default and serves the OpenAPI 3.1 spec at
/api/v1/openapi.json, with an interactive reference at /api/v1/docs. Auth
is on by default: the server generates a token that can be read with
bearer_auth_token() before serve(); logs show only a redacted preview.
A non-loopback bind requires an explicit operator-owned bearer token,
authorization, and rate limiting (or an explicitly trusted gateway). See
step 4 of the Rust quickstart.
Why iCommerce
Most commerce APIs answer "what endpoint can the model call?" StateSet answers the harder question: "how can this actor commit resources safely, recover from failure, and prove what happened?"
- State, not chat history. Orders, inventory, balances, approvals, and workflows survive process restarts and evolve through guarded state machines.
- Authority, not model confidence. The agent proposes an intent; an operator-owned, deny-by-default policy decides whether it may execute.
- Transactions, not tool-call optimism. Domain state, budgets, events, and idempotency records commit atomically or roll back together.
- Receipts, not unverifiable narration. Consequential actions return a sealed record of actor, principal, intent, policy decision, observed result, audit anchor, and settlement evidence.
- A small public vocabulary over deep machinery. Agents reason in
quote,buy,sell,pay,fulfill,return_order,refund, andsubscribewhile the engine keeps its full domain API and generated MCP catalog. - Embedded by default. SQLite is the zero-infrastructure path; PostgreSQL is there when multiple workers need a shared backend.
Kernel-executed commerce
The kernel is the boundary between a model suggesting an action and software being allowed to perform it:
objective → typed intent → authenticated agent → delegated authority
→ policy + budget → atomic domain command → economic receipt
Identity and policy are trusted runtime inputs. They are never accepted from a model-authored tool call. Monetary limits use decimal strings; non-fiat assets use separate asset identifiers; inventory commands bind the authorized quantity to the executor-observed quantity.
Details: Kernel Execution · Trust Foundation (security model and its explicit gap inventory) · Kernel Roadmap
Agent frameworks
If your agent runtime lives inside your application process and wants JSON-schema tools rather than stdio MCP, use the embedded toolkit:
Install the Python framework extras in one step with
pip install "stateset-embedded[agents]==1.40.0".
The toolkit also exposes payment-aware helpers (getPayableToolCatalog(),
executePaidTool(), discoverRemotePaymentService()) and contract/replay
helpers (getRuntimeContract(), simulatePlan(), executePlan(),
replayMutation()). Call simulateMutation() or
executePlan({ dryRun: true }) before enabling writes, then set allowApply
only on agents that should mutate commerce state.
Working examples: Embedded Agent Toolkit · AI Agents
Agent-to-agent commerce
Direct agent-to-agent payments, quotes and negotiation, escrow with conditional release, split payments, subscriptions, discovery and reputation, and signed event streaming are first-class. See Intelligent Commerce Protocol, A2A Protocol Overview, and x402.
The deterministic multi-agent marketplace demo puts a buyer, three merchants, and a payment agent on one Ed25519-signed, totally ordered message board, where the winning award crosses two independent kernel boundaries:
(cd bindings/node && npm run build)
node examples/sequencer-marketplace/demo.mjs --self-test --kernel
Architecture
A layered Rust kernel with two outer product surfaces: language bindings, and the Node-based operator runtime.
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
Read it in this order: stateset-core, stateset-db, stateset-embedded,
then stateset-sync/stateset-policy/stateset-authz/stateset-pricing,
then stateset-http, then bindings/node and admin/ or cli/.
Full walkthrough: Architecture · Dependency Direction · Workspace Inventory (generated)
Development
nvm use # .nvmrc / .node-version (20.20.0)
rustup show active-toolchain # pinned by rust-toolchain.toml (1.90.0)
npm run check # developer gate across the core workspace surfaces
npm run check:release # release preflight; run before cutting a tag
Per-surface loops:
cargo test -p stateset-core -p stateset-db -p stateset-embedded
npm --prefix cli test
npm --prefix admin test
npm --prefix bindings/node run check
The authoritative remote gate is CI on master. CI also verifies the workspace
MSRV on Rust 1.85 and runs the binding and admin surfaces on the same pinned
Node 20.20.0.
Contributing: CONTRIBUTING.md · Releasing: RELEASING.md · Security: SECURITY.md
Documentation
- The book — concepts, every commerce domain, A2A,
payments, security, policy, adapters, operations, and the API reference.
Build it locally with
mdbook serve docs. - Tool catalog — generated, authoritative list of the MCP/CLI tool surface (923 tools across 87 domains today).
- API reference per binding — Rust, Node, Python, Go, Java, Kotlin, Swift, .NET, Ruby, PHP, WASM.
- Examples — runnable end-to-end programs.
- Rust API docs on docs.rs.
- CHANGELOG.md — release history.
llms.txt— a machine-readable index for agents; AGENTS.md is the short orientation for an agent working against this repo.
License
Dual-licensed under MIT or Apache-2.0, at your option.
