acn-agent

CLI tool for building and running ACN-connected AI agents.

Scaffold agent projects, discover APIs, run tasks with a live TUI, and manage your wallet — all from the terminal.

Install

npx acn-agent --help

Or install globally:

npm install -g acn-agent

Quick Start

1. Create a new agent project

npx acn-agent create my-agent

This launches an interactive wizard that:

• Selects your agent framework (Claude or LangChain)
• Configures your LLM API key
• Sets up your wallet for X402 payments
• Connects to the ACN marketplace

2. Run a task

cd my-agent
npx acn-agent run "Find the current price of Bitcoin"

The run command launches a live terminal UI showing:

• LLM reasoning
• Discovery results from the ACN marketplace
• Payment signing and confirmation
• API call execution and response
• Cost summary

3. Interactive mode

npx acn-agent run -i

Opens an interactive REPL where you can enter tasks one at a time.

Commands

| Command | Description | |---------|-------------| | create <name> | Scaffold a new agent project | | run [task] | Run the agent with a task (TUI) | | run -i | Interactive REPL mode | | discover <query> | Search ACN for services | | balance | Check wallet balance | | providers | List all ACN providers | | history | Show recent API calls | | config | View current agent config | | wallet-server | Start the wallet MCP server (stdio) |

Configuration

Agent projects use an agent.config.json file:

{
  "name": "my-agent",
  "mcpServers": {
    "acn": {
      "type": "url",
      "url": "https://mcp.acn.exchange/mcp"
    },
    "wallet": {
      "type": "stdio",
      "command": "npx",
      "args": ["acn-agent", "wallet-server"],
      "env": {
        "WALLET_PRIVATE_KEY": "${WALLET_PRIVATE_KEY}",
        "CHAIN_ID": "8453"
      }
    }
  },
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "acn": {
    "network": "mainnet",
    "maxCostPerTask": "1.000000",
    "autoApprovePayments": true
  }
}

Environment variables (.env):

LLM_API_KEY=sk-ant-...
WALLET_PRIVATE_KEY=0x...
ACN_API_KEY=acn_sk_...         # optional
CHAIN_ID=8453                  # Base Mainnet (default) or 84532 (Base Sepolia)

Wallet MCP Server

The wallet-server command starts a local MCP server powered by Coinbase AgentKit using ViemWalletProvider. Your private key never leaves your machine.

Use it standalone with Claude Desktop, Cursor, or any MCP-compatible client:

{
  "mcpServers": {
    "acn-wallet": {
      "type": "stdio",
      "command": "npx",
      "args": ["acn-agent", "wallet-server"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "CHAIN_ID": "8453"
      }
    }
  }
}

Available wallet tools

| Tool | Description | |------|-------------| | get_wallet_details | Wallet address, chain, balance | | get_balance | Native + ERC20 token balances | | transfer | Send native or ERC20 tokens | | sign_message | EIP-191 personal sign |

Architecture

acn-agent CLI
├── ACN MCP Server (remote: mcp.acn.exchange)
│   ├── acn_discover — find APIs by natural language
│   ├── acn_providers — list all providers
│   ├── acn_submit_payment — complete X402 payments
│   └── {provider}__{endpoint} — call provider APIs
└── Wallet MCP Server (local: Coinbase AgentKit)
    ├── get_wallet_details — wallet info
    ├── get_balance — token balances
    ├── transfer — send tokens
    └── sign_message — sign for auth

Supported Frameworks

The create command generates ready-to-run projects for:

• Claude (Anthropic Claude + MCP) — recommended
• LangChain / LangGraph

More frameworks coming soon (CrewAI, Google ADK, OpenAI).

Networks

| Network | URL | Chain | |---------|-----|-------| | Mainnet | mcp.acn.exchange | Base (8453) | | Testnet | testnet.acn.exchange | Base Sepolia (84532) |

Documentation

• ACN Docs
• CLI Reference
• Agent Frameworks

License

MIT