Yield Scout Agent

Yield Scout Agent is a hackathon MVP for discovering DeFi yield opportunities on Avalanche Fuji through an agentic payment loop. The agent requests premium yield and risk data, receives an x402-style 402 Payment Required response, supplies a payment reference, selects the best risk-adjusted pool, and records its recommendation on-chain. Together, the mock x402 flow and ERC-8004-inspired agent registry demonstrate how an autonomous agent can acquire paid data and build transparent, on-chain reputation.

Architecture

The project deliberately keeps the moving parts small and visible:

• Mock premium API (mock-api/server.js) exposes /risk-data. It returns a 402 payment challenge without X-PAYMENT, then returns Avalanche pool data after receiving a payment reference.
• Agent script (agent/run.js) performs the payment flow, chooses the highest APY pool with a risk score below 7, and sends the recommendation to Fuji using ethers.js.
• AgentRegistry (contracts/AgentRegistry.sol) is an ERC-8004-inspired, self-service agent identity registry.
• ReputationLog (contracts/ReputationLog.sol) creates an append-only on-chain record of each recommendation, including whether paid data was used and its payment reference. Only the registered agent owner can log recommendations for their agent ID.
• Web dashboard (web/) provides a browser UI to run the agent and view on-chain recommendation history.

Yield Scout Agent → Mock Premium API → 402 payment challenge
       │                    │
       └── payment reference ┘
       │
       ├── AgentRegistry (agent identity)
       └── ReputationLog (on-chain recommendation history)

Fuji Deployments

Current Avalanche Fuji deployment addresses (from deployed-addresses.json):

Contract	Address
AgentRegistry	0x99C6Afd756B5b7AaFad6ac093cfEaC1543c041d1
ReputationLog	0x1a8C83cF6a4DF9807359ac0A7638d06f103c585A

Note: The deploy scripts update deployed-addresses.json automatically. Both the agent and dashboard read contract addresses from that file.

Setup

Node.js 18 or later is recommended.

npm install
cp .env.example .env

Update .env with a Fuji-funded deployment wallet private key:

PRIVATE_KEY=your_wallet_private_key_here
FUJI_RPC_URL=https://api.avax-test.network/ext/bc/C/rpc

Compile the contracts:

npm run compile

To deploy a fresh registry and reputation log pair to Fuji:

npm run deploy:fuji

The script prints the addresses and saves them to deployed-addresses.json.

To redeploy only the ReputationLog (preserving existing agent IDs):

npm run deploy:reputation-log

Run the Demo

CLI mode

Use two terminals from the project root.

Terminal 1 — start the mock premium-data API:

npm run mock-api

Terminal 2 — run the agent:

npm run run-agent

On its first successful run, the agent registers YieldScoutBot and saves its ID in agent-id.json. Later runs reuse that agent ID and append new on-chain recommendation records.

Web Dashboard

Use two terminals from the project root.

Terminal 1 — start the mock paid-data provider:

npm run mock-api

Terminal 2 — start the browser dashboard:

npm run start-dashboard

Open http://localhost:5000 and click Run Agent. The dashboard shows the paid-data result, its Fuji transaction, and the on-chain recommendation history.

What This Demonstrates

This MVP demonstrates a complete agentic payment loop: paid data acquisition through an x402-style payment challenge, followed by accountable on-chain reputation logging through an ERC-8004-inspired registry on Avalanche Fuji. The implementation is intentionally simple for hackathon use, but the loop maps cleanly to real premium-data providers, stablecoin settlement, and richer agent reputation scoring.