Skip to main content

Overview

The acn-agent CLI is an NPX tool for scaffolding agent projects, running agent tasks, and testing ACN interactions — all with a beautiful terminal UI.
npx acn-agent <command>
No installation required. Just run with npx.

Commands

create — Scaffold a New Agent

npx acn-agent create my-agent
Interactive wizard that:
  1. Asks you to choose an agent framework (Claude or LangChain)
  2. Configures your LLM API key
  3. Sets up your wallet for X402 payments
  4. Connects to the ACN marketplace
  5. Sets spending limits
Generated project structure:
my-agent/
├── src/
│   └── index.ts          # Agent entry point (framework-specific template)
├── agent.config.json     # MCP servers + LLM configuration
├── .env                  # API keys, wallet key (gitignored)
├── .env.example          # Template without secrets
├── .gitignore
├── package.json
└── tsconfig.json

run — Execute a Task

npx acn-agent run "Find the current ETH price and email it to me@example.com"
Runs your agent with a real-time TUI showing:
  • Agent reasoning steps
  • Discovery results with provider pricing
  • Payment signing and confirmation
  • API call execution and response
  • Cost summary

Interactive Mode

npx acn-agent run -i
Opens an interactive REPL where you can issue tasks one at a time and see the agent work in real time.

discover — Test Discovery

npx acn-agent discover "send transactional emails"
Quickly test what services ACN returns for a query without executing anything. Useful for exploring the marketplace.

balance — Check Balance

npx acn-agent balance
Shows your current ACN balance.

providers — List Providers

npx acn-agent providers
Lists all available providers on the network with their categories, endpoints, and pricing.

history — Call History

npx acn-agent history
Shows your recent API calls with provider, endpoint, cost, latency, and status.

config — View Configuration

npx acn-agent config
Displays your current resolved agent configuration with secrets masked.

wallet-server — Start Wallet MCP Server

npx acn-agent wallet-server
Starts the local wallet MCP server on stdio, powered by Coinbase AgentKit. Use this to add wallet capabilities to any MCP-compatible agent (Claude Desktop, Cursor, etc.):
{
  "mcpServers": {
    "acn-wallet": {
      "command": "npx",
      "args": ["acn-agent", "wallet-server"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "CHAIN_ID": "8453"
      }
    }
  }
}

Configuration

The CLI reads configuration from agent.config.json in the current directory, merged with environment variables from .env.
{
  "name": "my-agent",
  "version": "1.0.0",
  "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,
    "preferCheapestProvider": true
  }
}

Environment Variables

VariableDescription
LLM_API_KEYLLM provider API key (Anthropic, OpenAI, etc.)
ANTHROPIC_API_KEYAnthropic API key (alternative to LLM_API_KEY)
WALLET_PRIVATE_KEYWallet private key for X402 payments
ACN_API_KEYACN API key (optional, for authenticated access)
ACN_NETWORKNetwork: mainnet or testnet
CHAIN_IDChain ID: 8453 (Base) or 84532 (Base Sepolia)
ACN_MCP_URLOverride ACN MCP server URL

Config Resolution Order

  1. agent.config.json in current directory
  2. .env file in current directory
  3. Environment variables (override file values)
  4. CLI flags (override everything)

Spending Limits

The CLI supports built-in spending controls via the acn config:
SettingDescription
maxCostPerTaskMaximum total spend for a single task run
autoApprovePaymentsWhether to auto-approve payments (default: true)
preferCheapestProviderPrefer cheapest provider when multiple match (default: true)
These limits protect against runaway agent spending during development and testing.

Networks

NetworkMCP URLChain
Mainnetmcp.acn.exchange/mcpBase (8453)
Testnettestnet.acn.exchange/mcpBase Sepolia (84532)