AgentSourcing — Autonomous Research Agent Network

AI agents hire AI agents. They pay each other in USDC. On-chain. In seconds.

---

💡 What Is AgentSourcing?

AgentSourcing is an autonomous multi-agent research network where AI agents hire other AI agents and pay each other in real-time USDC on the Arc blockchain via Circle Nanopayments.

A user submits a research task for $0.05 USDC. A Manager Agent breaks it into sub-tasks, hires 6 Specialist Agents at $0.002 USDC each, and they in turn call premium data APIs at $0.0005 USDC per call — all settled on-chain, autonomously.

---

🏗️ Tech Stack

Layer	Technology	Why
Blockchain	Arc (EVM-compatible, USDC gas)	Sub-cent gas fees — makes $0.002 payments viable
Payments	Circle Programmable Wallets (Developer-Controlled)	Automated agent treasury, no key management
Payment Standard	x402 / Circle Nanopayments	Per-API-call monetisation at $0.0005 each
Currency	USDC	Stable, no volatility risk for agent commerce
Reputation	ERC-8004 Trust Layer (Vyper)	On-chain agent trust scores for agent selection
Smart Contracts	Vyper 0.4.3 on Arc Testnet	Escrow + reputation + payment release logic
AI / LLM	Featherless.ai (LLaMA 3.1 70B, Qwen, Mistral, DeepSeek)	Per-agent specialised model routing
Backend	FastAPI + Python 3.12 + SSE	Real-time event streaming to UI
Frontend	React + TypeScript + Tailwind CSS (Vite)	Glassmorphism dashboard with real-time SSE feed

---

⚡ Why Arc + Circle Nanopayments?

Network	Gas per Tx	Our Payment	Gas as %	Viable?
Ethereum Mainnet	$2 – $8	$0.002	100,000%+	❌ Impossible
Polygon / L2	$0.01 – $0.05	$0.002	500–2,500%	❌ Unprofitable
Arc + Nanopayments	$0.000x	$0.002	< 1%	✅ Fully viable

The math is simple: every other blockchain makes sub-cent agent payments economically impossible. Arc + Circle fix this.

---

🚀 Quick Start

Prerequisites

• Python 3.12+
• Node.js 18+ (for building the React frontend)
• Circle Developer Account (free sandbox)
• Featherless.ai API Key (for LLM inference)
• MetaMask wallet funded from Arc Testnet Faucet

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/AgentSourcing.git
cd AgentSourcing

2. Install dependencies

pip install -r requirements.txt

# Build the frontend UI
cd frontend && npm install && npm run build && cd ..

3. Configure environment

# Windows
copy .env.example .env

# Linux / Mac
cp .env.example .env

Edit .env with your API keys — see Setup Guide for full instructions.

4. Generate Circle entity secret

# Step 1: Generate and save to .env as CIRCLE_ENTITY_SECRET
python circle/entity_secret.py generate

# Step 2: Get cipher text and register at console.circle.com
# → Developer Controlled Wallets → Configurator → paste cipher text
python circle/entity_secret.py ciphertext

5. Create agent wallets on Arc Testnet

python circle/setup.py
# Prints all wallet IDs and addresses — copy to .env

6. Fund the Manager wallet

Visit faucet.circle.com → send test USDC to your Manager wallet address.

7. Deploy ERC-8004 Vyper contract (optional)

python scripts/deploy_contract.py
# Saves contract address to .env as ERC8004_CONTRACT_ADDRESS

8. Start the server

python main.py
# Open: http://localhost:8000

---

📁 Project Structure

AgentSourcing/
│
├── main.py                    # FastAPI app — all routes, SSE streaming, x402 endpoints
├── config.py                  # Centralised config loaded from .env
├── requirements.txt
├── .env.example               # ← copy this to .env and fill in your keys
│
├── agents/
│   ├── base_agent.py          # Abstract base — timing, ERC-8004 hooks, x402 integration
│   ├── llm_client.py          # Featherless.ai LLM wrapper with per-agent model routing
│   ├── manager_agent.py       # Tier-1 — orchestrator, hires specialists, pays USDC
│   ├── scraper_agent.py       # Tier-2 — real-time web research (DuckDuckGo + BS4)
│   ├── analyst_agent.py       # Tier-2 — market data analysis and trend detection
│   ├── summarizer_agent.py    # Tier-2 — executive summaries and report writing
│   ├── fact_checker_agent.py  # Tier-2 — claim verification and source checking
│   ├── translator_agent.py    # Tier-2 — multilingual output + cultural relevance
│   ├── validator_agent.py     # Tier-2 — LLM-powered quality validation
│   └── data_agent.py          # Tier-3 — x402 nanopayment data fetcher
│
├── circle/
│   ├── entity_secret.py       # RSA-OAEP entity secret generation and encryption
│   ├── wallet_manager.py      # Wallet set / wallet CRUD + USDC balance queries
│   ├── payment_processor.py   # USDC transfers + fee estimation + Arc explorer links
│   ├── setup.py               # One-time provisioning of 8 agent wallets
│   ├── x402_client.py         # x402 payment protocol client for data API calls
│   └── wallets.json.example   # Example wallet structure (real wallets.json in .gitignore)
│
├── reputation/
│   ├── erc8004.py             # ERC-8004 reputation scoring (in-memory + on-chain)
│   ├── erc8004.vy             # Vyper 0.4.3 smart contract — deployed on Arc Testnet
│   └── erc8004_abi.json       # Contract ABI for Web3 integration
│
├── frontend/
│   ├── src/
│   │   ├── App.tsx            # Main app — SSE streaming, payment events, routing
│   │   ├── components/        # AgentRoster, ReportViewer, TransactionFeed, etc.
│   │   └── index.css          # Tailwind + glassmorphism design system
│   └── dist/                  # Production build (served by FastAPI)
│
├── docs/
│   ├── setup_guide.md         # Full setup walkthrough
│   ├── agent_workflow.md      # How agents collaborate
│   ├── agent_economy.md       # Circle wallets and payment architecture
│   ├── architecture.md        # System architecture overview
│   └── api_reference.md       # Full API endpoint reference
│
├── scripts/
│   ├── deploy_contract.py     # Deploy Vyper contract to Arc Testnet
│   ├── generate_wallet.py     # Generate new Circle wallets
│   ├── check_deploy_ready.py  # Pre-deployment readiness check
│   └── test_*.py              # Test scripts for individual components

---

📡 API Reference

Method	Endpoint	Description
GET	/	Dashboard UI
GET	/api/health	System health + config status
POST	/api/research	Submit a research task
GET	/api/research/{id}/stream	SSE real-time event stream
GET	/api/research/{id}/result	Full research result
GET	/api/research	List all runs
GET	/api/agents	All agent ERC-8004 reputation profiles
GET	/api/agents/{id}	Single agent profile
POST	/api/agents/register-wallet	Register agent wallet address
GET	/api/wallets	List Circle wallets
GET	/api/wallets/{id}/balance	Wallet USDC balance
GET	/api/transactions/{id}	Circle transaction status
GET	/api/x402/payments	All x402 nanopayment records
GET	/api/x402/endpoints	13 available premium data APIs
GET	/data/{slug}	x402-gated data endpoint (402 → pay → 200)

Interactive docs: http://localhost:8000/api/docs

🏅 ERC-8004 Reputation Formula

Agents build trust scores over time based on their track record:

score = 50
      + (completion_rate × 25)     # reliability  → max +25
      + (avg_quality / 10 × 20)    # output quality → max +20
      + min(completions, 10)        # experience    → max +10
      − (failures × 5)             # failure penalty
      − min(avg_latency_s, 5)      # speed penalty

Score clamped to [0, 100]. Manager uses scores to select best available agent per task.

---

🌍 Supported Languages (Translator Agent)

English · French · German · Hindi · Italian · Portuguese · Spanish · Thai

---

📚 Documentation

• Setup Guide — Full step-by-step setup
• Agent Workflow — How agents collaborate
• Agent Economy & Circle Wallets — Payment architecture
• System Architecture — Technical architecture overview
• API Reference — All endpoints

---

🔒 Security Notes

• Never commit .env — it is in .gitignore
• Your CIRCLE_ENTITY_SECRET and ARC_DEPLOYER_PRIVATE_KEY must stay local
• Use Circle sandbox environment for development (no real money)
• Rotate your API keys immediately if accidentally exposed

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push: git push origin feature/my-feature
5. Open a Pull Request

---

📄 License

Proprietary License — All rights reserved.

---

AgentSourcing — Built with ❤️ for the Agentic Economy on Arc

Powered by Arc + Circle + Featherless.ai