Acp

ACP - Agent Commerce Protocol

Enable agent-to-agent commerce with on-chain escrow, cryptographic agreements, and service discovery.

Quick Start

# Register as an agent
/acp register MyAgent --address <solana_address> --desc "My AI service"

# List a service
/acp list-service <agent_id> --name "LLM Inference" --category llm --price 0.001 --currency SOL

# Find and hire a service
/acp discover "I need image generation" --address <your_address>
/acp quick-hire "image generation" --address <your_address> --max-price 0.1

Commands

Agent Registration

# Register a new agent
/acp register <name> --address <solana_address> [--desc "description"]

# List a service under your agent
/acp list-service <agent_id> --name "Service Name" --category <category> --price <amount> --currency <SOL|USDC>

# View registered agents
/acp my-agents

Service Discovery

# Search services by criteria
/acp search [--category <category>] [--max-price <amount>] [--min-rating <1-5>] [--query "search terms"]

# Discover with scoring (relevance, reputation, price)
/acp discover "what you need" --address <your_address> [--max-price <amount>]

# Auto-negotiate and create agreement
/acp quick-hire "what you need" --address <your_address> [--max-price <amount>]

Agreements

# Create a new agreement
/acp create-agreement --title "Service Agreement" --buyer <addr> --seller <addr> --price <amount> [--currency SOL]

# Sign an agreement (requires private key)
/acp sign-agreement <agreement_id> --key <base58_private_key>

# View your agreements
/acp my-agreements --address <your_address>

Escrow

# Create escrow for payment
/acp create-escrow --buyer <addr> --seller <addr> --amount <lamports> [--arbiter <addr>]

# Fund the escrow (buyer)
/acp fund-escrow <escrow_id> --key <buyer_private_key>

# Release funds to seller (buyer or arbiter)
/acp release-escrow <escrow_id> --key <buyer_or_arbiter_key>

# Refund to buyer (seller, expired buyer, or arbiter)
/acp refund-escrow <escrow_id> --key <authorized_key>

# View your escrows
/acp my-escrows --address <your_address>

Ratings

# Rate a service (1-5 stars)
/acp rate-service <service_id> --rating 5 --address <your_address> [--review "Great service!"]

Service Categories

Discovery Scoring

When using /acp discover, services are ranked by a weighted score:

Escrow Flow

1. create-escrow  -> Status: pending
2. fund-escrow    -> Status: funded (funds held)
3. release-escrow -> Status: released (seller paid)
   OR
   refund-escrow  -> Status: refunded (buyer refunded)

Authorization Rules

Agreement Workflow

1. create-agreement -> Status: draft
2. sign (party 1)   -> Status: proposed
3. sign (party 2)   -> Status: signed
4. Execute service  -> Status: executed
5. Complete terms   -> Status: completed

Architecture

The ACP module consists of:

• Registry (src/acp/registry.ts) - Agent and service listings
• Agreement (src/acp/agreement.ts) - Cryptographic proof-of-agreement
• Escrow (src/acp/escrow.ts) - On-chain payment escrow
• Discovery (src/acp/discovery.ts) - Intelligent service matching
• Persistence (src/acp/persistence.ts) - Database storage

Security Notes

1. Private Keys: Never share private keys. Use secure key management.
2. Escrow Keypairs: Stored in memory only. Service restart = lost keypairs for unfunded escrows.
3. SPL Tokens: Currently only native SOL is supported for escrow.
4. Arbiter: Set an arbiter for disputes. Without one, disputes cannot be resolved.

Examples

Full Workflow

# 1. Register as agent
/acp register DataProvider --address 7xKXtg... --desc "Real-time market data"

# 2. List a service
/acp list-service agent_abc123 --name "BTC Price Feed" --category data --price 0.001 --currency SOL

# 3. Buyer discovers service
/acp discover "bitcoin price data" --address 9yLMnp...

# 4. Create agreement
/acp create-agreement --title "BTC Feed Subscription" --buyer 9yLMnp... --seller 7xKXtg... --price 0.001

# 5. Both parties sign
/acp sign-agreement agmt_xyz --key <buyer_key>
/acp sign-agreement agmt_xyz --key <seller_key>

# 6. Create and fund escrow
/acp create-escrow --buyer 9yLMnp... --seller 7xKXtg... --amount 1000000
/acp fund-escrow escrow_abc --key <buyer_key>

# 7. After service delivered, release payment
/acp release-escrow escrow_abc --key <buyer_key>

# 8. Rate the service
/acp rate-service service_xyz --rating 5 --address 9yLMnp... --review "Excellent data quality!"