README.md

AgentPay

Decentralized micropayment channels for autonomous AI agents over libp2p

Quick Start · Architecture · CLI & API · Ecosystem Alignment · Contributing

---

Agents discover each other via mDNS, negotiate service terms over libp2p streams, exchange Filecoin-style signed payment vouchers off-chain, and settle on Ethereum, Algorand, or Filecoin FEVM. Built for the Filecoin Agents ecosystem and the ARIA Scaling Trust programme.

Architecture

AgentPay is structured as a modular agent runtime with six layers:

• Networking — py-libp2p 0.6.0 with TCP/WebSocket transports, Noise encryption, Yamux multiplexing, mDNS discovery, and GossipSub pubsub
• Wire Protocol — 13 message types over length-prefixed msgpack streams (/agentic-payments/1.0.0), covering payments, HTLCs, negotiations, and announcements. TaskId correlation on vouchers for per-request settlement attestation
• Payment Channels — Filecoin-style cumulative vouchers with ECDSA signatures and task correlation, HTLC multi-hop routing via reputation-weighted BFS, one-shot x402 stateless payments, and a 6-state channel lifecycle
• Settlement — Tri-chain: Ethereum (Solidity PaymentChannel.sol), Algorand (ARC-4 + box storage), and Filecoin FEVM (same contract on FEVM with f4 address support) — selectable at startup
• Identity — ERC-8004 on-chain agent registration (ERC-721 identity token), EIP-191 PeerId-to-wallet cryptographic binding, reputation sync, and discovery fallback
• Trust Layer — Reputation scoring, GossipSub peer scoring (time-in-mesh, first-delivery, app-specific weights), SLA monitoring, dynamic pricing engine, dispute detection, wallet policies, standardized payment error codes, and hash-chained signed receipt audit trails
• Storage — IPFS content-addressed pinning for receipts and capabilities, with CID-based retrieval and GossipSub broadcast
• Interfaces — Quart-Trio REST API (~50 endpoints), Typer CLI (~50 commands), and a Next.js 15 real-time dashboard

Module dependency map — interface, core, network, business, trust, and settlement layers

See ARCHITECTURE.md for the full system design with 13 architecture diagrams.

Quick Start

Prerequisites

• Python 3.12+ and uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Node.js 22+ (for the dashboard)
• Docker (optional — PostgreSQL + Anvil for on-chain settlement)

Install & Run

# Install dependencies
uv sync --group dev

# Start agents + dashboard (recommended)
./scripts/dev.sh              # 2 agents + frontend at localhost:3000
./scripts/dev.sh --agents 3   # 3 agents

# Or start manually
uv run agentpay start --port 9000 --api-port 8080

Verify

curl http://127.0.0.1:8080/health       # {"status":"ok","version":"0.1.0"}
curl http://127.0.0.1:8080/identity     # peer_id, eth_address, listen addrs
curl http://127.0.0.1:8080/peers        # discovered peers

Open a Channel & Pay

# Open a payment channel (locks 1 ETH deposit)
curl -X POST http://127.0.0.1:8080/channels \
  -H "Content-Type: application/json" \
  -d '{"peer_id":"12D3KooW...","receiver":"0xAbC...","deposit":1000000000000000000}'

# Send micropayments (off-chain, sub-millisecond)
curl -X POST http://127.0.0.1:8080/pay \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"abcdef01...","amount":100000000000000}'

Dashboard

The Next.js dashboard at localhost:3000 provides a real-time multi-agent network view.

Network Graph	Interactive force-directed graph — click nodes to open channels, click edges to send payments. Trust-colored nodes (green/amber/red).
Trust Panels	Discovery, negotiations, receipt chains, wallet policies — all in the left sidebar.
Simulation	Batch payment rounds, topology control (mesh/ring/star), success rate tracking.
Actions	Open channels, route multi-hop HTLC payments, propose service negotiations.
Monitoring	SLA violations, dispute scanning, dynamic pricing quotes, live event feed.

Payment channel lifecycle — open, pay, close, settle

CLI

agentpay start [--port 9000] [--api-port 8080] [--eth-rpc URL]   # Start agent node
agentpay identity generate                                         # Create Ed25519 keypair
agentpay channel open --peer <id> --deposit <wei>                  # Open payment channel
agentpay pay --channel <id> --amount <wei>                         # Send micropayment
agentpay negotiate propose --peer <id> --service compute           # Negotiate terms
agentpay reputation list                                           # View trust scores
agentpay dispute scan                                              # Detect stale vouchers
agentpay pricing quote --service inference                         # Dynamic price quote

Full CLI reference with all subcommands: COMMANDS.md

REST API

~50 JSON endpoints across 10 groups. CORS enabled. Default: http://127.0.0.1:8080

Group	Endpoints	Description
Core	/health /identity /peers /channels /pay /balance /graph /route-pay /connect /chain	Node identity, peer discovery, channel management, payments, routing
Discovery	/discovery/agents /discovery/resources	Agent capability registry, Bazaar-compatible resource listing
Negotiation	/negotiate /negotiations /negotiations/:id/*	Propose/counter/accept/reject service terms with SLA
Trust	/reputation /receipts /policies	Per-peer trust scores, hash-chained receipts, wallet spend policies
Pricing	/pricing/quote /pricing/config	Dynamic price quotes with trust discounts and congestion premiums
SLA	/sla/violations /sla/channels	Per-channel latency/error-rate monitoring, violation detection
Disputes	/disputes /disputes/scan /channels/:id/dispute	Stale voucher detection, dispute filing and resolution
Gateway	/gateway/resources /gateway/register /gateway/access /gateway/log /gateway/pay-oneshot	x402 payment-gated resource access, one-shot stateless payments
Roles	/role	Agent role assignment (coordinator, worker, data_provider, validator, gateway)
Work Rounds	/work-rounds	Coordinator-managed task distribution and worker assignment

Development

make ci            # Run full CI pipeline locally (lint + format + typecheck + test + frontend + contracts)
make test          # 680 tests
make lint          # ruff check
make fmt           # ruff format (auto-fix)
make typecheck     # mypy

Tests cover the protocol codec, channel state machine, voucher cryptography, REST API, Algorand settlement, SLA monitoring, dynamic pricing, disputes, reputation, multi-hop routing, EIP-191 identity binding, payment error codes, role-based coordination, and full integration flows.

Contributing

See CONTRIBUTING.md for setup instructions, branch rules, and code quality requirements. All changes require a PR with passing CI and one approving review.

Support

---