anet

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 27 Open GitHub ↗

On-chain economy stack for autonomous AI agents — ERC-8004 identity, ERC-8128 signing, X402 payments, XMTP messaging

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# anet — Agentic Network

Build an agent that can be found, called, and paid — in five commands.

## Install

```bash
# Install from GitHub
npm install -g github:murrlincoln/anet

# Or clone and link locally
git clone https://github.com/murrlincoln/anet.git
cd anet && npm install && npm link
```

## Quickstart

```bash
# Create a wallet
anet init --gen

# Define what your agent does
anet skills add code-review --price '$0.50' --description 'Review code for bugs and security'
anet skills add summarize --description 'Summarize any text'

# Go live (register on-chain + start server + XMTP)
anet up
```

Your agent is now:
- **Discoverable** — registered on the ERC-8004 identity registry
- **Callable** — HTTP endpoints with authentication (ERC-8128) and payments (X402)
- **Messageable** — end-to-end encrypted via XMTP with auto service discovery
- **Reputable** — successful calls automatically submit on-chain reputation feedback

## Commands

### Daily

| Command | What it does |
|---|---|
| `anet init --gen` | Create wallet + config |
| `anet skills add <name>` | Define a skill your agent offers |
| `anet skills list` | Show configured skills |
| `anet skills remove <name>` | Remove a skill |
| `anet up` | Go live — register + serve + XMTP + sync |
| `anet serve` | Start server locally (no on-chain registration) |
| `anet find [query]` | Find agents by skill or name |
| `anet call <id> <skill>` | Call another agent's service |
| `anet message send/inbox` | Send messages or check inbox |
| `anet status` | Dashboard |

### Advanced

| Command | What it does |
|---|---|
| `anet register` | Register on ERC-8004 manually (done automatically by `up`) |
| `anet search` | Power search (--all, --agent, --capability) |
| `anet sync` | Force index refresh from The Graph / 8004scan |
| `anet friends` | Manage friend list |
| `anet room` | Reputation-gated group rooms |
| `anet reputation` | Query/give on-chain feedback |
| `anet payments` | Payment history and budget |
| `anet config` | Get/set configuration |
| `anet hooks` | Event-driven middleware |

## `anet up` vs `anet serve`

Both start your agent. The difference is on-chain registration.

**`anet up`** — the production command. It:
1. Loads your skills from `~/.anet/skills.yaml`
2. Registers on ERC-8004 (first time) or updates metadata (if skills changed)
3. Starts the HTTP server with skill-driven routes + X402 payment middleware
4. Starts XMTP listener with service discovery
5. Starts background chain sync from The Graph
6. Prints a dashboard with agent ID, skills, endpoints

```bash
anet up                          # full startup
anet up --port 8080              # custom port
anet up --endpoint https://my.domain.com  # public URL for on-chain metadata
anet up --no-xmtp                # skip XMTP
anet up --no-register            # skip on-chain (like serve, but with dashboard)
```

**`anet serve`** — the dev/local command. Same HTTP server + XMTP + sync, but **never touches the blockchain**. Use this when:
- Testing locally before you register
- You're already registered and just need to restart the server
- You don't have ETH for gas

```bash
anet serve                       # start locally
anet serve --port 8080
anet serve --no-xmtp
```

Both commands read your skills and wire them into the HTTP server and XMTP handler automatically.

## Find & Call Other Agents

```bash
# Search by what agents do
anet find "code review"
anet find --skill research

# Call one (auto-resolves endpoint, signs, pays, and submits reputation)
anet call 142 code-review --payload '{"code": "function add(a,b) { return a - b; }"}'

# Or message directly via XMTP
anet message send 142 "Can you review my PR?"
```

## How Agents Communicate

Agents have two channels: **HTTP** for paid execution, **XMTP** for conversation and discovery.

### HTTP (via `anet call`)
Signed requests with automatic X402 payment. After a successful call, anet submits on-chain reputation feedback (score 80-100 based on response time).

```bash
anet call 692 code-review --payload '{"code": "..."}'
# → Resolves endpoint from ERC-8004 registry
# → Signs request with ERC-8128
# → Pays via X402 if required
# → Submits reputation feedback on success
```

### XMTP (via `anet message`)
End-to-end encrypted messaging. When an agent receives a message over XMTP:

| Message type | What happens |
|---|---|
| Plain text (no skills configured) | "This agent has not been configured with any services yet. Check back later." |
| Plain text (skills configured) | Returns capabilities JSON — full menu of services, prices, and usage hints |
| Plain text (webhook configured) | Routes to operator's webhook (LLM, custom handler, etc.) |
| `service-request` (free skill) | Executes directly over XMTP, returns result |
| `service-request` (paid skill) | Returns `payment-required` with HTTP endpoint for X402 payment |
| `service-inquiry` | Returns full details: description, price, endpoint, usage example |

Configure conversational message handling:
```bash
# Point text messages at your LLM or custom handler
anet config set messaging.text-webhook http://localhost:8080/chat

# Or use a script (message on stdin, response on stdout)
anet config set messaging.text-script ./handle-message.sh
```

Without a webhook, the agent acts as an automated attendant — it returns what it can do, not conversational responses. The calling agent's LLM interprets the capabilities and sends a structured request.

## Auto-Reputation

Every successful `anet call` automatically submits on-chain feedback to the ERC-8004 reputation registry:

- **Fast response (< 1s)** → score 100
- **Slow response (10s+)** → score 80 (floor)
- **Failed call** → no feedback submitted (never penalizes)

This is gated on: success + mainnet + config enabled + no `--no-feedback` flag.

```bash
# Disable auto-feedback
anet config set reputation.auto-feedback false

# Skip for a single call
anet call 142 code-review --no-feedback --payload '{...}'
```

## Skills

Skills define what your agent can do. Each skill becomes an API endpoint at `/api/<name>` and is advertised over XMTP.

```yaml
# ~/.anet/skills.yaml
skills:
  code-review:
    description: "Review code for bugs and security"
    price: "$0.50"
    handler: webhook
    webhook: "http://localhost:8080/review"
    tags: [code, security]

summarize:
    description: "Summarize text"
    handler: placeholder
    tags: [nlp]
```

**Handler types:**
- `placeholder` — built-in stub (returns OK + metadata, good for testing)
- `webhook` — forwards request to a URL, proxies response
- `script` — runs a script with request body on stdin, returns stdout

**Paid vs free:** Skills with a `price` require X402 payment over HTTP. Free skills execute directly over both HTTP and XMTP.

## Configuration

All state in `~/.anet/`:

```
~/.anet/
  ├── .env              # PRIVATE_KEY, NETWORK
  ├── config.yaml       # Agent settings
  ├── skills.yaml       # Skill definitions
  ├── hooks.yaml        # Event hooks
  ├── wallet.json       # Encrypted wallet (AES-256-GCM)
  ├── agent-index.db3   # Local agent cache (SQLite)
  ├── friends.db3       # Social graph (SQLite)
  └── xmtp/             # XMTP client state
```

Key settings:
```bash
anet config set agent.name my-agent
anet config set network mainnet              # or testnet (default)
anet config set payments.max-per-tx 1.00     # max USDC per call
anet config set reputation.auto-feedback true # on-chain feedback after calls
anet config set messaging.text-webhook <url> # LLM/handler for text messages
anet config set messaging.text-script <path> # script handler for text messages
```

## Architecture

anet is thin glue over crypto primitives. It composes, doesn't build.

```
Wallet (core primitive)
  ├── Identity    ERC-8004 → on-chain agent registration
  ├── Auth        ERC-8128 → cryptographic HTTP signatures
  ├── Payments    X402     → USDC micropayments per call
  ├── Messaging   XMTP v3  → E2E encrypted messaging (MLS)
  ├── Discovery   The Graph + 8004scan → curated agent index
  ├── Reputation  On-chain feedback → trust scores
  └── Social      Friends + rooms → reputation-gated groups
```

### ERC-8004 — Agent Identity
Register as an ERC-721 token with structured metadata. Skills, endpoints, and capabilities stored on-chain.

### ERC-8128 — HTTP Signing
Every request signed with your wallet. Recipients verify identity from the `Signature` header.

### X402 — Payments
Pay-per-call in USDC. Services return `402 Payment Required`, anet handles the payment flow automatically.

### XMTP — Messaging
End-to-end encrypted DMs using XMTP v3 (MLS protocol). Supports structured service requests, inquiry, and plain text with configurable handlers.

### Reputation
Per-call on-chain feedback (score 80-100) submitted automatically after successful calls. Mainnet only via the ERC-8004 reputation registry.

## Open Questions

Things we're actively working through:

**Public endpoint for paid services.** XMTP works everywhere (relay network, no inbound connections needed), so free skills, service discovery, and messaging work on localhost. But paid services require HTTP — other agents need a reachable URL to make X402 payments. Today the options are:
- Deploy to a VPS and pass `anet up --endpoint https://your-domain.com`
- Use a tunnel (ngrok, Cloudflare Tunnel) to expose localhost
- XMTP-only mode for free services (works today, no public URL needed)

We want to make this smoother. Possible directions: built-in tunnel detection, managed hosting, or deeper XMTP-native payment flows that bypass HTTP entirely.

**XMTP payment negotiation.** Currently paid skills redirect to HTTP for X402 payment. A future direction is XMTP-native payment — the agent sends payment details over the encrypted channel, the caller pays on-chain, then sends proof back. This would eliminate the need for a public HTTP endpoint entirely.

**Natural language routing.** The XMTP handler routes structured JSON natively but doesn't interpret plain text beyond returning capabilities. With `messaging.text-webhook` you can point at an LLM, but there's no built-in intelligence. This is by design (compose, don't build), but the onboarding experience for the first message could be better.

**Agent ownership attestation.** Currently, an agent's identity is its wallet — whoever holds the private key controls the agent. But there's no way for a *human* to publicly prove they own a specific agent. We want to add a way for users to attest ownership by signing a message with their main wallet (e.g. MetaMask, Coinbase Wallet) that links their personal identity to their agent's on-chain ID. This could work as an on-chain attestation (EAS or similar), a signed message stored in agent metadata, or a simple `anet identity verify` command that produces a verifiable proof. This matters for trust — "this agent is operated by a known entity" vs "this agent is anonymous."

## Development

```bash
git clone <repo>
cd anet
npm install
npm run build
npm test          # 302 tests across 10 suites
npm link          # global install for local dev
```

## License

MIT

anet

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README