Starknet Agentic

Production-grade Starknet agent infrastructure: secure Cairo contracts, MCP/A2A runtimes, x402 payment helpers, end-to-end examples, and installable agent skills.

This repository is for developers building agents that need Starknet-native wallets, policy-enforced execution, on-chain identity, and composable tool access.

Install & Use

Scaffold a Starknet agent

npx @starknetfoundation/create-starknet-agent@latest

The scaffolder detects supported agent environments and wires Starknet integration into a new project.

Install a skill

npx skills add keep-starknet-strange/starknet-agentic/skills/cairo-auditor

Codex public GitHub install:

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo keep-starknet-strange/starknet-agentic \
  --path skills/cairo-auditor \
  --ref main

Codex reproducible install:

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo keep-starknet-strange/starknet-agentic \
  --path skills/cairo-auditor \
  --ref 

Claude Code marketplace install:

/plugin marketplace add keep-starknet-strange/starknet-agentic
/plugin install starknet-agentic-skills@starknet-agentic-skills --scope user

For Codex, Claude Code, and pinned install flows, use the deterministic skill quickstart:

• skills/QUICKSTART_2MIN.md
• skills/README.md
• skills/TROUBLESHOOTING.md

Run the MCP server from source

From a source checkout after pnpm install:

pnpm --filter @starknetfoundation/starknet-agentic-mcp-server build
node packages/starknet-mcp-server/dist/index.js

Production deployments should use proxy signer mode rather than in-process private keys. See packages/starknet-mcp-server and docs/security/SIGNER_API_SPEC.md.

What Is Included

Architecture

flowchart TB
  Agent["Agent runtime(Codex, Claude Code, OpenClaw, custom app)"] --> Tools["Tool layerMCP, A2A, skills"]
  Tools --> Signer["Signer boundarydirect for local dev, proxy for production"]
  Signer --> Starknet["Starknet"]
  Starknet --> Accounts["Agent/session accountspolicy enforcement"]
  Starknet --> Registries["ERC-8004 registriesidentity, reputation, validation"]
  Tools --> Packages["TypeScript helperspassport, onboarding, x402, scanners"]

The recommended launch profile is self-custodial and no-backend:

• users run the agent runtime locally or on their own infrastructure
• account contracts enforce transaction policy on-chain
• production signer custody lives behind an explicit proxy/KMS/HSM boundary

Core Components

Contracts

Deployment status is tracked in docs/DEPLOYMENT_TRUTH_SHEET.md. Treat that file as canonical for deployed class hashes, owners, and known drift.

Packages

Skills

The public catalog is maintained in skills/README.md and skills/manifest.json.

Examples

Requirements

Copy ./.env.example where an example or package asks for local environment variables. Never commit private keys or funded credentials.

Contributor Workflow

Install workspace dependencies:

pnpm install

Build and test TypeScript packages:

pnpm build
pnpm test

Faster package-only path:

pnpm -r --filter "./packages/*" build
pnpm -r --filter "./packages/*" test

Run Cairo checks for contract changes:

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 ]

Run skill and distribution checks for skill/install UX changes:

python3 scripts/quality/validate_skills.py
python3 scripts/skills_manifest.py --check
python3 scripts/quality/check_codex_distribution.py
python3 -m unittest scripts/quality/test_codex_distribution.py
python3 scripts/quality/validate_marketplace.py

Security and Release Integrity

• Security policy: SECURITY.md
• Production deployment runbook: docs/security/PRODUCTION_DEPLOYMENT_RUNBOOK.md
• Signer proxy rotation: docs/security/SIGNER_PROXY_ROTATION_RUNBOOK.md
• Mainnet ownership signer policy: docs/security/MAINNET_OWNERSHIP_SIGNER_POLICY.md
• External audit scope: docs/security/EXTERNAL_AUDIT_SCOPE.md

Release artifacts should be verified with GitHub attestations when available:

gh attestation verify  --repo keep-starknet-strange/starknet-agentic

Documentation

Repository Layout

starknet-agentic/
|-- .agents/        # Local agent discovery entrypoints
|-- contracts/      # Cairo contracts and tests
|-- packages/       # TypeScript packages
|-- skills/         # Installable agent skills
|-- examples/       # End-to-end demos and reference flows
|-- datasets/       # Audit/eval source datasets
|-- evals/          # Deterministic evaluation fixtures
|-- docs/           # Architecture, security, and launch docs
|-- scripts/        # Quality, release, and audit support scripts
`-- website/        # Documentation website

Contributing

See CONTRIBUTING.md. Keep changes narrow, testable, and aligned with AGENTS.md, which is the canonical workflow file for automated coding agents in this repository.

License

MIT. See LICENSE.