AgentSphere

Decentralized AI agent marketplace: multiple agents run a pipeline off-chain, then the orchestrator settles outcomes on Avalanche Fuji and optionally records x402-style payment references on an X402PaymentRegistry.

---

Repository layout

Path	Role
Backend/	Express API, orchestration, ethers integration (npm run dev)
smartcontract/	Solidity (AgentRegistry, TaskManager, optional Payment, mocks), Hardhat
frontend/	Next.js UI (optional)

---

Deployed contracts (Avalanche Fuji, chain ID 43113)

These are the current project defaults for local configuration. If you redeploy, update Backend/.env (see Backend/.env.example).

Contract	Address	Notes
AgentRegistry	0xdB34E8611333Fd6dd3a57C59F125ebA8878378Cd	Agent metadata, pricing, reputation
TaskManager	0xB818Da67ccb75651556Fd301BCE23c6d094EFD0b	Tasks, orchestrator settlement, paymentRef hashes
X402PaymentRegistry	0xadC69eC5Ab0E2f37191B8528f5eb4629552D30B2	Optional attestation: PaymentRecorded events; registrar must equal backend PRIVATE_KEY address

Explorers (Fuji C-Chain) — paste an address or tx hash:

• Snowtrace Testnet

Source verification — contracts may appear on Sourcify for chain 43113.

Contracts in-repo without a fixed Fuji address here

Artifact	Purpose
Payment.sol	USDC escrow helper (optional; wire your own USDC + deploy if used)
MockUSDC.sol	Local / test token

---

Backend setup

1. Install and configure

cd Backend
cp .env.example .env
# Edit .env: FUJI_RPC_URL, PRIVATE_KEY, TASK_MANAGER_ADDRESS, AGENT_REGISTRY_ADDRESS,
# AGENT_ID_* (after registering agents), optional X402_PAYMENT_REGISTRY_ADDRESS
npm install

2. Required environment (summary)

Variable	Description
FUJI_RPC_URL	Fuji JSON-RPC, e.g. https://api.avax-test.network/ext/bc/C/rpc
PRIVATE_KEY	Orchestrator wallet — must match TaskManager.orchestrator() and X402 registrar
TASK_MANAGER_ADDRESS	See table above
AGENT_REGISTRY_ADDRESS	See table above
AGENT_ID_RESEARCH, AGENT_ID_SENTIMENT, AGENT_ID_ANALYSIS	On-chain agent IDs for the pipeline
X402_PAYMENT_REGISTRY_ADDRESS	Optional; omit to skip registry calls
X402_NETWORK_LABEL	e.g. fuji — must match string used in x402 refs
CHAIN_ID	43113 for Fuji

Full list and comments: Backend/.env.example.

3. Run the server

npm run dev

4. Integration checks (no HTTP)

npm run test:integration

Confirms RPC, orchestrator alignment, optional X402 registrar, and that configured agent IDs resolve on-chain.

---

Smart contracts (Hardhat)

cd smartcontract
cp env.example .env   # set FUJI_RPC_URL, PRIVATE_KEY for deploy scripts
npm install
npx hardhat compile

Deploy scripts live under smartcontract/scripts/ (e.g. deploy.js). After deploying, copy addresses into Backend/.env.

---

Payments and x402 flow

1. Preflight — preflightCheck(taskId, agentIds) ensures on-chain task budget covers the sum of agent pricePerTask values.
2. Execution — Agents run off-chain; each successful step gets an x402-style paymentRef derived from X402_NETWORK_LABEL and a unique payment id.
3. Settlement — settleTaskFromBackend on TaskManager records payouts and refs.
4. Registry (optional) — If X402_PAYMENT_REGISTRY_ADDRESS is set and X402_RECORD_PAYMENTS is not false, recordPayments is called on X402PaymentRegistry (same refs as settlement).

---

API quick test

Create an on-chain task with budget ≥ sum of the three agents’ prices (example: 500000 in the same raw units as on-chain), then execute:

curl -s -X POST "http://localhost:8080/api/tasks/execute" \
  -H "Content-Type: application/json" \
  -d '{"chainTaskId": 39, "prompt": "Your prompt here"}'

Use your real on-chain task id as the numeric chainTaskId (the example 39 is illustrative only).

A successful run returns status: "COMPLETED", settlementTxHash, and optionally x402RegistryTxHash when the registry is configured.

---

Tech stack

• Backend: Node.js, Express, ethers v6
• Chain: Avalanche Fuji (testnet)
• Contracts: Solidity 0.8.x, Hardhat, OpenZeppelin

---

License

See repository root for license information (if provided).