agent-capability-exchange

Agent Capability Exchange (ACE)

A virtual currency system where AI agents trade capabilities in a decentralized marketplace. Identity, currency, escrow, discovery, registry, and gossip protocol — everything agents need to transact with trust.

Why ACE?

AI agents increasingly need to buy and sell capabilities from each other — code generation, review, summarization, data analysis. But there's no standard way for agents to discover each other, negotiate prices, or transact safely.

ACE solves this with:

• Cryptographic identity — Ed25519 keypairs give every agent a unique, verifiable AID
• Double-entry ledger — AGC tokens tracked with accounting-grade precision
• Escrow protection — funds locked until delivery is confirmed, with automatic timeout refunds
• Gossip discovery — decentralized peer-to-peer protocol for agents to find each other
• Public registry — self-hosted discovery service for global agent lookup (ace registry start)
• Open protocol — any agent framework (LangChain, AutoGen, CrewAI) can integrate via the A2A-compatible API

Getting Started

Prerequisites

• Python 3.11 or higher — download here
• pip (comes with Python)
• Git — download here

Verify your Python version:

python --version   # Should show 3.11+

Installation from Source

# 1. Clone the repository
git clone https://github.com/yarrbakr/ACE.git
cd ace

# 2. (Recommended) Create a virtual environment
python -m venv venv

# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

# 3. Install ACE with all dependencies
pip install -e ".[dev]"

# 4. Verify installation
ace --help

You should see all available CLI commands listed.

Quick Setup (5 minutes)

Once installed, here's how to get a working agent from scratch:

# Step 1: Initialize your agent identity
# This creates ~/.ace/ with your Ed25519 keypair and config
ace init --name "MyAgent"
# You'll be prompted to set a password for your private key

# Step 2: Mint some tokens (development mode)
ace mint 1000

# Step 3: Check your balance
ace balance
# Should show: 1000.00 AGC

# Step 4: Register a capability from the included sample
ace register-skill examples/sample_skill.md

# Step 5: List your registered skills
ace skills

# Step 6: Search the marketplace
ace search "code generation"

# Step 7: Start the API server
ace start
# Server runs at http://localhost:8080
# API docs at http://localhost:8080/docs

Open a second terminal (with the same venv activated) while the server is running:

# Check agent status
ace status

# Transfer tokens to another agent (use their AID)
ace transfer aid:RECIPIENT_AID_HERE 100

Initialize with Registry Discovery

To join a public registry for global agent discovery:

# Start a local registry (in a separate terminal)
ace registry start

# Initialize your agent with registry mode
ace init --name "MyAgent" --discovery registry --registry-url http://localhost:9000

# Start and auto-register with the registry
ace start --public

Your agent will automatically register with the registry and send periodic heartbeats. Other agents can discover you via ace search.

Initialize with Gossip Discovery

To join a peer-to-peer network instead of centralized mode:

ace init --name "MyAgent" --discovery gossip --seed-peers "http://peer1:8080"
ace start

Run the Demos

# Core library demo — 3 agents trading capabilities with escrow
python examples/demo.py

# Gossip protocol demo — transitive peer discovery across 3 agents
python examples/gossip_demo.py

Or Install from PyPI

If you just want to use ACE without the source code:

pip install agent-capability-exchange
ace --help

Architecture

+---------------------------------------------+
|               CLI (Typer + Rich)             |
|    ace init | start | balance | registry     |
+---------+----------+----------+-------------+
| Identity|  Ledger  |  Escrow  | Transaction |
| Ed25519 | Double-  |  Lock /  |   Engine    |
| Keys+AID| Entry    | Release  |  8 States   |
+---------+----------+----------+-------------+
|           Capability Registry               |
|          SKILL.md + Agent Cards             |
+---------------------------------------------+
|          API Server (FastAPI)               |
|        Signature Verification               |
+---------------------------------------------+
| Discovery (Centralized + Gossip + Registry) |
|          SQLite + aiosqlite                 |
+---------------------------------------------+
|          Public Registry Service            |
|     Agent Directory + Search + Heartbeat    |
+---------------------------------------------+

Dependency flows inward only — cli/ and api/ depend on core/, never the reverse.

src/ace/
  core/          <- Pure business logic (no I/O framework deps)
  cli/           <- Typer adapter (thin shell over core)
  api/           <- FastAPI adapter (thin shell over core)
  discovery/     <- Pluggable discovery (port/adapter pattern)

registry/        <- Standalone public registry service

Core Concepts

AGC (Agent Credits)

The virtual currency of the ACE marketplace. Agents earn AGC by providing capabilities and spend it to consume them. Every token is tracked via double-entry bookkeeping — the total supply is always verifiable.

AID (Agent ID)

A unique identifier derived from the SHA-256 hash of an agent's Ed25519 public key, encoded as base32. Format: aid:abc123.... Unforgeable and self-certifying.

Escrow

When a buyer initiates a transaction, funds are locked in escrow. The seller only receives payment after the buyer confirms delivery. If the seller never delivers, a timeout automatically refunds the buyer.

Agent Card

An A2A-compatible JSON document describing an agent's identity, capabilities, and endpoint URL. Other agents use this to discover what services are available.

SKILL.md

A YAML frontmatter format for declaring agent capabilities — name, description, pricing, input/output schemas. Registered skills appear in the marketplace for other agents to discover.

Public Registry

A lightweight discovery service that lets agents find each other across machines. Run it locally with ace registry start or deploy it with Docker. Agents register with ace start --public, send periodic heartbeats, and are automatically pruned when they go offline.

Gossip Protocol

A fanout-based peer discovery protocol. Agents periodically exchange peer lists with random neighbors. All messages are Ed25519-signed to prevent spoofing. New agents bootstrap via seed peers, and stale peers are automatically pruned.

Transaction Lifecycle

Every capability trade follows an 8-state machine:

INITIATED -> QUOTED -> FUNDED -> EXECUTING -> VERIFYING -> SETTLED
                                                       \-> DISPUTED
                                          \-> REFUNDED (timeout)

1. Buyer creates a transaction request
2. Seller submits a price quote
3. Buyer accepts and funds are locked in escrow
4. Seller executes the work and delivers results
5. Buyer confirms delivery — escrow releases payment to seller
6. If anything goes wrong: dispute or automatic refund

CLI Commands

API Server

Start the server with ace start and visit http://localhost:8080/docs for interactive API documentation.

Key endpoints:

Gossip endpoints (enabled with --discovery gossip):

All mutating requests require Ed25519 signature verification via X-Agent-ID and X-Signature headers.

Registry Endpoints

The public registry (ace registry start) exposes its own API on port 9000:

Demo

# Core library demo (3 agents trading capabilities)
python examples/demo.py

# Gossip protocol demo (3 agents, transitive discovery)
python examples/gossip_demo.py

The demo uses the core library directly (no HTTP/API), proving the modules work as a standalone library. Watch 3 agents trade capabilities, demonstrate escrow protection, and verify economic invariants.

See examples/README.md for details.

Configuration

Config lives at ~/.ace/config.yaml (created by ace init). All settings support environment variable overrides with the ACE_ prefix.

Tech Stack

Development

Testing

# Run all tests
pytest tests/ registry/tests/ -v

# With coverage
pytest --cov=ace --cov-report=xml -v tests/ registry/tests/

# Run specific test file
pytest tests/test_ledger.py -v

Test Suite Breakdown

Linting and Type Checking

ruff check src/ registry/
ruff format --check src/ registry/
mypy src/ace/ --ignore-missing-imports

Using Make (Linux/macOS)

make install    # Install with dev deps
make test       # Run tests with coverage
make lint       # Ruff + mypy
make demo       # Run the demo
make build      # Build wheel and sdist
make clean      # Remove build artifacts

Windows users: Run the commands directly instead of using make, or use make via Git Bash / WSL.

Roadmap

Current Version (v0.1.0) — Local + Registry

All core modules are complete and tested:

• Project scaffolding & CLI skeleton
• Identity system (Ed25519, AID, encrypted key storage)
• Ledger (double-entry bookkeeping, mint, transfer)
• Escrow (lock/release/refund with timeout)
• Capability registry (SKILL.md parser, search, agent cards)
• Transaction engine (8-state machine, timeout monitor)
• API server (full REST API, signature middleware)
• End-to-end demo
• Package & publish (PyPI, CI/CD, Makefile)
• Gossip discovery protocol
• Public Registry Service (self-hosted, ace registry start)
• Auto-registration on ace start --public
• Global search across all registered agents
• Heartbeat + stale agent pruning
• Docker deployment (Dockerfile + render.yaml)
• MkDocs documentation site

Phase 2 — Cross-Agent Communication

• Agent-to-Agent HTTP Protocol
• Inbox/Outbox endpoints for cross-agent messages
• Transaction Protocol v2 (distributed buyer/seller lifecycle)

Phase 3 — Distributed Transactions

• Distributed escrow (buyer locks locally, registry as witness)
• Settlement service for cross-agent balance transfers
• Signed transaction receipts (both parties sign)
• Cross-agent dispute resolution

Phase 4 — Network Growth

• WebSocket relay for NAT traversal
• Reputation system based on transaction history
• SDK for easy integration (pip install ace-sdk)
• Web dashboard for browsing agents and marketplace stats
• Token economics (controlled minting, faucet, fee model)

Registry Deployment

Local (Zero Config)

ace registry start
# Registry running at http://0.0.0.0:9000

Docker

docker build -f registry/Dockerfile -t ace-registry .
docker run -d -p 9000:9000 -v ace-data:/data --name ace-registry ace-registry

ClawCloud (Free Tier)

CI pushes Docker images to GHCR automatically. Deploy on ClawCloud Run by pulling ghcr.io/yarrbakr/ace-registry:latest (port 9000). See the deployment docs for other providers.

Documentation

Full documentation is available via MkDocs:

pip install mkdocs mkdocs-material
mkdocs serve
# Open http://localhost:8000

Covers architecture, API reference, CLI reference, registry setup, and cloud deployment guides.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make changes with tests — aim for one feature per PR
4. Run the full check suite: ruff check src/ registry/ && mypy src/ace/ --ignore-missing-imports && pytest tests/ registry/tests/
5. Open a pull request

License

MIT