Starknet Agentic

# Starknet Agentic [](https://github.com/keep-starknet-strange/starknet-agentic/actions/workflows/ci.yml) [](https://github.com/keep-starknet-strange/starknet-agentic/actions/workflows/codeql.yml) [](./LICENSE) Infrastructure for the Starknet agent economy: contracts, runtimes, and skills to run self-custodial AI agents with on-chain identity, policy-enforced execution, and composable tool access. ## Why This Exists Most agent stacks treat wallets as add-ons. `starknet-agentic` treats wallets, identity, and execution policy as first-class system boundaries. This repo gives you: - account-level control rails (session keys, spending policy, revoke paths) - ERC-8004 identity, reputation, and validation registries on Starknet - MCP and A2A integration packages for agent runtimes - reusable skills and end-to-end examples ## Fastest Path If you just want Starknet agent capabilities now: ```bash npx create-starknet-agent@latest ``` Sanity check (npm availability): ```bash npm view create-starknet-agent version ``` The scaffolder detects your environment (OpenClaw/MoltBook, Claude Code, Cursor, or standalone) and wires Starknet integration automatically. ## Install & Use Use the path that matches your runtime: ```bash # Full project scaffold npx create-starknet-agent@latest ``` ```bash # Codex (public GitHub install, cairo-auditor) skill-installer install https://github.com/keep-starknet-strange/starknet-agentic/tree/main/skills/cairo-auditor # Restart Codex, then run /skills and invoke cairo-auditor ``` ```bash # Codex (reproducible install pinned to a released tag) skill-installer install https://github.com/keep-starknet-strange/starknet-agentic/tree/v0.2.2/skills/cairo-auditor ``` ```bash # Claude Code marketplace /plugin marketplace add keep-starknet-strange/starknet-agentic /plugin install starknet-agentic-skills@starknet-agentic-skills --scope local /reload-plugins /plugin menu /starknet-agentic-skills:cairo-auditor ``` ```bash # Individual skill install via Agent Skills CLI npx skills add keep-starknet-strange/starknet-agentic/skills/cairo-auditor ``` For deterministic install/usage guidance, see: - [skills/QUICKSTART_2MIN.md](./skills/QUICKSTART_2MIN.md) - [skills/TROUBLESHOOTING.md](./skills/TROUBLESHOOTING.md) - [docs/CLAUDE_MARKETPLACE_SUBMISSION.md](./docs/CLAUDE_MARKETPLACE_SUBMISSION.md) For the full skill catalog and Cairo migration notes, see [skills/README.md](./skills/README.md) and [docs/CAIRO_SKILLS_MIGRATION.md](./docs/CAIRO_SKILLS_MIGRATION.md). ## System Requirements - CLI users (`npx create-starknet-agent@latest`): Node.js `>=18.0.0` - Contributors from source (this monorepo): - Node.js `>=20.9.0` - `pnpm` `>=10.28.2` (workspace package manager) - Scarb `>=2.14.0` + Starknet Foundry (`snforge`) `>=0.54.1` (for Cairo builds/tests) ## Choose Your Path | Goal | Start here | |---|---| | Add Starknet tools to an existing agent | [`packages/create-starknet-agent`](./packages/create-starknet-agent/) | | Run local no-backend onboarding demo | [`examples/onboard-agent`](./examples/onboard-agent/) | | Run autonomous loop with MCP tools | [`examples/full-stack-swarm`](./examples/full-stack-swarm/) | | Integrate on-chain identity/reputation | [`contracts/erc8004-cairo`](./contracts/erc8004-cairo/) | | Build production signer boundary | [`packages/starknet-mcp-server`](./packages/starknet-mcp-server/) + external signer (proxy mode) | ## Architecture ```mermaid flowchart TB A["Agent Runtime<br/>(OpenClaw, Claude Code, custom app)"] --> B["MCP / A2A Layer<br/>starknet-mcp-server, starknet-a2a, skills"] B --> C["Signer Boundary<br/>direct (dev) or proxy (prod)"] C --> D["Starknet Contracts"] D --> D1["Agent-account stack<br/>owner controls + spending policy enforcement"] D --> D2["ERC-8004 Registries<br/>Identity, Reputation, Validation"] D --> D3["Session-account primitives<br/>session-key account modules"] ``` ## No-Backend Trust Model (Recommended Launch Profile) Default launch profile is self-custodial and no-backend: - users run agent runtime locally or on their own infra - transaction policy is enforced on-chain by account contracts - no central signer or shared custody by this project For production environments, use MCP proxy signer mode rather than raw in-process private keys. ## Core Components ### Contracts | Component | Path | What it does | |---|---|---| | Agent account contracts | [`contracts/agent-account`](./contracts/agent-account/) | Session keys, policy enforcement, ownership controls | | ERC-8004 Cairo registries | [`contracts/erc8004-cairo`](./contracts/erc8004-cairo/) | Identity, reputation, validation primitives | | Session-account primitives | [`contracts/session-account`](./contracts/session-account/) | Session-key account modules for policy-centric execution | | Huginn registry | [`contracts/huginn-registry`](./contracts/huginn-registry/) | Additional registry primitives used by ecosystem demos | ### Packages | Package | Path | Purpose | |---|---|---| | `create-starknet-agent` | [`packages/create-starknet-agent`](./packages/create-starknet-agent/) | Scaffolds/installs Starknet agent integration | | `@starknet-agentic/mcp-server` | [`packages/starknet-mcp-server`](./packages/starknet-mcp-server/) | Starknet operations over MCP | | `@starknet-agentic/a2a` | [`packages/starknet-a2a`](./packages/starknet-a2a/) | A2A protocol adapter | | `@starknet-agentic/agent-passport` | [`packages/starknet-agent-passport`](./packages/starknet-agent-passport/) | ERC-8004 capability metadata helpers | | `@starknet-agentic/prediction-arb-scanner` | [`packages/prediction-arb-scanner`](./packages/prediction-arb-scanner/) | Signals-only prediction market arb scanner output model | | `x402-starknet` (internal) | [`packages/x402-starknet`](./packages/x402-starknet/) | Internal workspace package for Starknet payment signing utilities | | `@starknet-agentic/onboarding-utils` | [`packages/starknet-onboarding-utils`](./packages/starknet-onboarding-utils/) | Shared onboarding helpers | ### Skills Skill packs live in [`skills/`](./skills/). Browse full catalog and install flows in [`skills/README.md`](./skills/README.md). Cairo migration notes and legacy mapping live in [`docs/CAIRO_SKILLS_MIGRATION.md`](./docs/CAIRO_SKILLS_MIGRATION.md). Install one skill: ```bash npx skills add keep-starknet-strange/starknet-agentic/skills/starknet-wallet ``` ## Standards and Interop | Standard | Purpose | Implementation | |---|---|---| | [MCP](https://modelcontextprotocol.io/) | Agent tool interface | `packages/starknet-mcp-server` | | [A2A](https://a2a-protocol.org/) | Agent-to-agent messaging/workflows | `packages/starknet-a2a` | | [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) | Agent identity/reputation/validation | `contracts/erc8004-cairo` | Parity and Starknet-specific behavior for ERC-8004 is documented in [`docs/ERC8004-PARITY.md`](./docs/ERC8004-PARITY.md). ## Quickstart From Source (Contributors) ### 1) Install ```bash pnpm install ``` ### 2) Build and test JS/TS workspace (packages, examples, website) ```bash # full workspace pnpm build pnpm test # packages only (faster path when you do not need example/website checks) pnpm -r --filter "./packages/*" build pnpm -r --filter "./packages/*" test ``` ### 3) Run Cairo checks ```bash failed=0 for dir in contracts/erc8004-cairo contracts/huginn-registry contracts/agent-account contracts/session-account; do if ! (cd "$dir" && scarb build && snforge test); then echo "Cairo checks failed in $dir" failed=1 break fi done [ "$failed" -eq 0 ] ``` ### 4) Run a minimal E2E demo Before running, configure the required environment in: [`exam