# Starknet Agentic

Adopt this skill: https://proskills.md/skills/other/starknet-agentic

Page: https://proskills.md/skills/other/starknet-agentic
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.agents

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.agents

## File: .changeset
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.changeset

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.changeset

## File: .claude-plugin
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.claude-plugin

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.claude-plugin

## File: .coderabbit.yaml
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.coderabbit.yaml

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.coderabbit.yaml

## File: .env.example
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.env.example

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.env.example

## File: .githooks
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.githooks

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.githooks

## File: .github
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.github

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.github

## File: .gitignore
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.gitignore

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.gitignore

## File: .gitleaks.toml
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.gitleaks.toml

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.gitleaks.toml

## File: .gitmodules
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.gitmodules

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.gitmodules

## File: .greptile
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.greptile

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.greptile

## File: .nvmrc
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.nvmrc

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.nvmrc

## File: .pr_agent.toml
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.pr_agent.toml

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/.pr_agent.toml

## File: AGENTS.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/AGENTS.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/AGENTS.md

## File: CHANGELOG.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CHANGELOG.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CHANGELOG.md

## File: CLAUDE.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CLAUDE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CLAUDE.md

## File: CODE_OF_CONDUCT.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CODE_OF_CONDUCT.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CODE_OF_CONDUCT.md

## File: CONTRIBUTING.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CONTRIBUTING.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/CONTRIBUTING.md

## File: LICENSE
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/LICENSE

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/LICENSE

## File: README.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/README.md

````text
# Starknet Agentic

[![CI](https://github.com/keep-starknet-strange/starknet-agentic/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/keep-starknet-strange/starknet-agentic/actions/workflows/ci.yml)
[![CodeQL](https://github.com/keep-starknet-strange/starknet-agentic/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/keep-starknet-strange/starknet-agentic/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./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
````

## File: SECURITY.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/SECURITY.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/SECURITY.md

## File: SKILL.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/SKILL.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/SKILL.md

## File: THIRD_PARTY.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/THIRD_PARTY.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/THIRD_PARTY.md

## File: VERSIONING.md
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/VERSIONING.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/VERSIONING.md

## File: commands
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/commands

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/commands

## File: contracts
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/contracts

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/contracts

## File: datasets
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/datasets

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/datasets

## File: docs
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/docs

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/docs

## File: evals
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/evals

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/evals

## File: examples
upstream: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/examples

Content is not inlined in the catalog. Read the upstream file: https://github.com/keep-starknet-strange/starknet-agentic/blob/HEAD/examples