---
name: axon-agent
description: Register and operate an AI Agent on the Axon blockchain (AI Agent Native L1, Cosmos SDK + EVM, Chain ID 9001). Use when a user wants to: (1) register an agent on Axon chain, (2) check agent on-chain status (isAgent, ONLINE, reputation), (3) set up the agent-daemon for heartbeat maintenance, (4) troubleshoot Axon agent registration or heartbeat failures. Do NOT use for general EVM/Solidity work unrelated to Axon.
---
# Axon Agent Skill
Axon is an AI Agent Native L1 blockchain. An "Agent" is an EVM address that calls `register()` with 100 AXON stake and sends periodic heartbeats to stay ONLINE.
**Official repo:** https://github.com/axon-chain/axon
**Chain params:** RPC `https://mainnet-rpc.axonchain.ai/` | Chain ID `9001` | ~5s blocks | Registry `0x0000000000000000000000000000000000000901`
**CRITICAL:** The official Python SDK has an ABI bug. Always use `scripts/register.py` instead. See `references/known-issues.md` for details.
---
## Prerequisites
- Server with Python 3.8+ and Go 1.21+
- EVM wallet private key saved to a file (e.g. `/opt/axon/private_key.txt`, chmod 600)
- Minimum 120 AXON balance (100 stake + 20 burn + gas buffer)
- `web3` Python package: `pip install web3`
---
## Phase 1: Check Balance & Status
```bash
python3 scripts/check-status.py --private-key-file /opt/axon/private_key.txt
```
If `isAgent: True` → skip to Phase 3 (daemon setup).
---
## Phase 2: Register Agent
```bash
# Dry run first
python3 scripts/register.py
--private-key-file /opt/axon/private_key.txt
--capabilities "nlp,reasoning,coding,research"
--model "claude-sonnet-4.6"
--dry-run
# Real registration
python3 scripts/register.py
--private-key-file /opt/axon/private_key.txt
--capabilities "nlp,reasoning,coding,research"
--model "claude-sonnet-4.6"
```
After success: `isAgent: True`. Note the registration block number — first heartbeat allowed ~720 blocks later (~1 hour).
**Capabilities examples:** `nlp,reasoning,coding,research` | `trading,analysis` | `vision,audio`
**Model:** Use actual model name being run (e.g. `claude-sonnet-4.6`, `glm-5`, `kimi-k2.5`)
---
## Phase 3: Build & Start Daemon
```bash
# Clone repo (if not already)
git clone https://github.com/axon-chain/axon /opt/axon
cd /opt/axon
# Build daemon
go build -o tools/agent-daemon/agent-daemon ./tools/agent-daemon/
# Start daemon
nohup /opt/axon/tools/agent-daemon/agent-daemon
--rpc https://mainnet-rpc.axonchain.ai/
--private-key-file /opt/axon/private_key.txt
--heartbeat-interval 720
--log-level info
>> /opt/axon/daemon.log 2>&1 &
echo "PID: $!"
```
Check logs: `tail -f /opt/axon/daemon.log`
Expected: `heartbeat confirmed` every ~720 blocks (~1 hour).
---
## Phase 4: Watchdog Cron
```bash
# Copy watchdog to your server (replace YOUR_SERVER and YOUR_KEY)
scp scripts/watchdog.sh user@YOUR_SERVER:/opt/axon/watchdog.sh
ssh user@YOUR_SERVER "chmod +x /opt/axon/watchdog.sh"
# Add cron (every 5 min)
ssh user@YOUR_SERVER "(crontab -l 2>/dev/null; echo '*/5 * * * * /opt/axon/watchdog.sh') | crontab -"
```
---
## Troubleshooting
See `references/known-issues.md` for:
- SDK ABI mismatch (most common failure)
- HeartbeatInterval first-heartbeat delay
- Official vs fork repo confusion
- Stake economics (20 AXON burned permanently)
**Quick diagnosis:**
```bash
# Check daemon running
pgrep -f agent-daemon && echo "running" || echo "NOT running"
# Check on-chain status
python3 scripts/check-status.py --private-key-file /opt/axon/private_key.txt
```
---
## Multi-Agent Setup
Each agent needs its own EVM wallet + 100 AXON + daemon instance. Steps are identical — run separate daemon processes with different `--private-key-file` and redirect logs to separate files (e.g. `daemon-cto.log`).
