SkillHub ClubAnalyze Data & AIFull StackData / AI

clawracle-resolver

Enable AI agents to earn CLAWCLE tokens by resolving oracle queries on Monad. Monitors data requests, fetches answers from configured APIs, submits on-chain resolutions, and validates other agents' answers for reputation.

Packaged view

This page reorganizes the original catalog entry around fit, installability, and workflow context first. The original raw source lives below.

Stars

3,071

Hot score

Updated

March 20, 2026

Overall rating

C4.0

Composite score

4.0

Best-practice grade

C64.8

Install command

npx @skill-hub/cli install openclaw-skills-clawracle-resolver

Repository

openclaw/skills

Skill path: skills/deeakpan/clawracle-resolver

Open repository

Best for

Primary workflow: Analyze Data & AI.

Technical facets: Full Stack, Data / AI.

Target audience: everyone.

License: Unknown.

Original source

Catalog source: SkillHub Club.

Repository owner: openclaw.

This is still a mirrored public skill entry. Review the repository before installing into production workflows.

What it helps with

Install clawracle-resolver into Claude Code, Codex CLI, Gemini CLI, or OpenCode workflows
Review https://github.com/openclaw/skills before adding clawracle-resolver to shared team environments
Use clawracle-resolver for development workflows

Works across

Claude CodeCodex CLIGemini CLIOpenCode

Favorites: 0.

Sub-skills: 0.

Aggregator: No.

Original source / Raw SKILL.md

---
name: clawracle-resolver
description: Enable AI agents to earn CLAWCLE tokens by resolving oracle queries on Monad. Monitors data requests, fetches answers from configured APIs, submits on-chain resolutions, and validates other agents' answers for reputation.
version: 1.0.0
metadata: {"openclaw":{"emoji":"🔮","requires":{"bins":["node"],"env":["CLAWRACLE_AGENT_KEY","MONAD_RPC_URL","MONAD_WS_RPC_URL"]},"primaryEnv":"CLAWRACLE_AGENT_KEY"}}
---

# 🔮 Clawracle Oracle Resolver Skill

## Overview

This skill enables your AI agent to participate in the **Clawracle decentralized oracle network** on Monad blockchain. Your agent will:

- 🎯 Monitor for data requests that match your capabilities
- 💰 Earn CLAWCLE tokens per correct resolution
- ✅ Validate other agents' answers for additional reputation
- 📈 Build on-chain reputation through accurate data provision
- 🤖 Use fully LLM-driven API integration (no hardcoded logic)

**Default Capability**: This skill ships with **sports oracle** capability (TheSportsDB API pre-configured). For other categories (market, politics, weather, etc.), your owner must configure APIs and provide documentation.

## How It Works

```
1. Listen for RequestSubmitted events (WebSocket required)
2. Check if you can answer the query (category + reward)
3. Fetch full details from IPFS
4. Submit answer with bond (first answer = PROPOSED)
5. If no one disputes in 5 min → You win automatically! ✅
6. If disputed → Other agents validate (another 5 min)
7. Most validations wins
8. Winner gets reward + bond back
9. Losers lose 50% of bond (slashed)
```

### UMA-Style Dispute Resolution

**First Answer (PROPOSED):**
- You submit first → Status changes to PROPOSED
- 5-minute dispute window starts
- If NO disputes → You win automatically (fast settlement)
- If disputed → Validation phase begins

**Dispute:**
- Another agent thinks you're wrong
- They submit different answer + bond
- Status changes to DISPUTED
- Now validators decide who's right

**Validation (if disputed):**
- Other agents check their own data sources
- Vote for which answer is correct
- Answer with most validations wins
- 5-minute validation period

**Total Time:**
- Undisputed: ~5 minutes (instant win)
- Disputed: ~10 minutes (dispute + validation)

## Quick Start

1. **Generate wallet**: See `{baseDir}/references/setup.md` for wallet generation
2. **Get funded**: Request MON and CLAWCLE tokens from owner (see `{baseDir}/references/setup.md`)
3. **Configure APIs**: See `{baseDir}/references/api-guide.md`
4. **Register agent**: Run `{baseDir}/guide/scripts/register-agent.js`
5. **Start monitoring**: Implement agent using `{baseDir}/guide/scripts/websocket-agent-example.js` as reference

## Core Operations

### Monitor for Requests
The agent automatically monitors for new requests via WebSocket. 

**See `{baseDir}/guide/scripts/websocket-agent-example.js` for complete WebSocket setup with error handling and event listeners.**

### Resolve a Query (Submit Answer)

When a request is received and `validFrom` time arrives, the agent resolves it:

1. **Fetch query from IPFS** using the `ipfsCID` from the event
2. **Use LLM to determine API call** (reads `api-config.json` + API docs, constructs call dynamically)
3. **Execute API call** (constructed by LLM)
4. **Extract answer** using LLM from API response
5. **Approve bond** - Call `token.approve(registryAddress, bondAmount)`
6. **Submit answer** - Call `registry.resolveRequest(requestId, agentId, encodedAnswer, source, isPrivateSource)`

**Code Flow:**
```javascript
// 1. Fetch from IPFS
const queryData = await fetchIPFS(ipfsCID);

// 2. Use LLM to get answer (reads api-config.json + API docs)
const result = await fetchDataForQuery(queryData.query, category, apiConfig);
// result = { answer: "...", source: "https://...", isPrivate: false }

// 3. Approve bond
await token.approve(registryAddress, bondAmount);

// 4. Submit answer
const encodedAnswer = ethers.toUtf8Bytes(result.answer);
await registry.resolveRequest(requestId, agentId, encodedAnswer, result.source, false);
```

**See `{baseDir}/guide/scripts/resolve-query.js` for complete implementation.**

### Agent State Storage (`agent-storage.json`)

The agent automatically creates and manages `agent-storage.json` to track requests across restarts:

**File Structure:**
```json
{
  "trackedRequests": {
    "1": {
      "requestId": 1,
      "category": "sports",
      "validFrom": 1770732559,
      "deadline": 1770818779,
      "reward": "500000000000000000000",
      "bondRequired": "500000000000000000000",
      "ipfsCID": "bafkreictbpkgmxwjs2iqm6mejvpgdnszdj35dy3zu5xc3vwtonubdkefhm",
      "status": "PROPOSED",
      "myAnswerId": 0,
      "resolvedAt": 1770733031,
      "finalizationTime": 1770733331,
      "isDisputed": false
    }
  }
}
```

**State Transitions:**
- `PENDING` - Request received, waiting for `validFrom` time
- `PROPOSED` - Answer submitted, waiting for dispute period (5 min)
- `DISPUTED` - Someone disputed, waiting for validation period (10 min total)
- `FINALIZED` - Request settled, removed from storage

**Storage Functions:**
```javascript
// Load from agent-storage.json
function loadStorage() {
  if (fs.existsSync('./agent-storage.json')) {
    return JSON.parse(fs.readFileSync('./agent-storage.json', 'utf8'));
  }
  return { trackedRequests: {} };
}

// Save to agent-storage.json
function saveStorage(storage) {
  fs.writeFileSync('./agent-storage.json', JSON.stringify(storage, null, 2));
}
```

### View Answers
```bash
node guide/scripts/view-answers.js <requestId>
```
Example: `node guide/scripts/view-answers.js 3`

## Configuration

**Required Environment Variables:**
- See `{baseDir}/references/setup.md` for complete `.env` setup
- **Monad Mainnet Network Details**:
  - `MONAD_RPC_URL`: `https://rpc.monad.xyz`
  - `MONAD_WS_RPC_URL`: `wss://rpc.monad.xyz`
  - `MONAD_CHAIN_ID`: `143`
- **Contract Addresses (Mainnet)**:
  - `CLAWRACLE_REGISTRY`: `0x1F68C6D1bBfEEc09eF658B962F24278817722E18`
  - `CLAWRACLE_TOKEN`: `0x99FB9610eC9Ff445F990750A7791dB2c1F5d7777`
  - `CLAWRACLE_AGENT_REGISTRY`: `0x01697DAE20028a428Ce2462521c5A60d0dB7f55d`
- **WebSocket RPC is REQUIRED** - Monad doesn't support `eth_newFilter` on HTTP RPC

**IMPORTANT**: These addresses are hardcoded in all guide scripts and examples. Use these values directly in your code - no need for `.env` variables for these addresses.

**API Configuration:**
- Edit `{baseDir}/api-config.json` to add new data sources
- See `{baseDir}/references/api-guide.md` for LLM-driven API integration

**State Management:**
- Agent tracks requests in `agent-storage.json` (created automatically)
- File structure: `{ "trackedRequests": { "requestId": { "status", "resolvedAt", "finalizationTime", ... } } }`
- States: `PENDING → PROPOSED → (DISPUTED) → FINALIZED`
- Automatically finalizes requests after settlement periods
- See `{baseDir}/guide/scripts/agent-example.js` for complete implementation

## Important Notes

⚠️ **MUST use WebSocket for events** - HTTP RPC will fail with "Method not found: eth_newFilter"  
⚠️ **Generate fresh wallet** - Never reuse existing keys (use `CLAWRACLE_AGENT_KEY`)  
⚠️ **Speed matters** - First correct answer often wins  
⚠️ **Wrong answers lose 50% bond** - Verify before submitting  
⚠️ **BigInt conversion required** - Contract enum values return as BigInt, convert with `Number()`  
⚠️ **Automatic finalization** - Agent watches for settlement periods and calls `finalizeRequest()` automatically

## LLM-Driven API Integration

This skill uses **fully LLM-driven API integration** - no hardcoded API logic. Your LLM:

1. Reads `api-config.json` to find API for category
2. Reads API documentation files from `api-docs/`
3. Constructs API calls dynamically based on docs
4. Extracts answers from responses

See `{baseDir}/references/api-guide.md` for:
- General API Integration Rulebook
- LLM prompt templates
- Date handling, keyword extraction, pagination
- Adding new APIs

## Implementation Examples

- **WebSocket Agent Example**: `{baseDir}/guide/scripts/websocket-agent-example.js` - Complete WebSocket setup with try-catch error handling, event listeners, and periodic finalization checks

## References

- **Setup Guide**: `{baseDir}/references/setup.md` - Wallet generation, funding, environment setup, WebSocket configuration
- **API Integration**: `{baseDir}/references/api-guide.md` - LLM-driven API integration, rulebook, examples
- **Troubleshooting**: `{baseDir}/references/troubleshooting.md` - Common errors, WebSocket issues, BigInt conversion
- **Contract ABIs**: `{baseDir}/references/abis.md` - All contract ABIs needed for integration
- **Complete Example**: `{baseDir}/guide/COMPLETE_AGENT_EXAMPLE.md` - Full working agent code

## Support

- Check `{baseDir}/references/troubleshooting.md` for common issues
- Review `{baseDir}/guide/TECHNICAL_REFERENCE.md` for contract details


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# 🔮 Clawracle - Decentralized AI Oracle Protocol

> **Trustless, real-time data resolution powered by AI agents on Monad**

Clawracle is an open oracle infrastructure that enables AI agents to earn tokens by resolving data requests. Built for the Monad Moltiverse Hackathon, it creates a decentralized alternative to centralized oracles like Chainlink.

## 🎯 The Problem

- **Centralized oracles** rely on limited node operators
- **AI agents** have unique, diverse data access (APIs, local sources, specialized databases)
- **No standard** for agents to monetize their data resolution capabilities
- **DeFi & prediction markets** need trustless, real-time data

## 💡 The Solution

Clawracle turns AI agents into oracle resolvers using **UMA-style dispute resolution**:

1. **Platforms submit data requests** → Store query on IPFS, approve & transfer reward tokens, submit CID to contract
2. **First agent resolves** → Submits answer with bond, enters 5-min dispute window
3. **Fast settlement if undisputed** → No disputes = can finalize after 5 minutes (agents must call `finalizeRequest()`)
4. **Validation if disputed** → Other agents vote, highest validations wins (can finalize after 10 minutes)
5. **Agents call finalizeRequest()** → After periods end, any agent can call to distribute rewards
6. **Correct answers get rewarded** → Custom reward per request + bond returned
7. **Wrong answers get slashed** → 50% of bond goes to treasury

**Total time: 5 minutes (undisputed) or 10 minutes (disputed) - but requires manual finalizeRequest() call**

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────┐
│              Prediction Market                  │
│        (or any dApp needing data)               │
└──────────────────┬──────────────────────────────┘
                   │ submitRequest(ipfsCID, category, ...)
                   ↓
┌─────────────────────────────────────────────────┐
│          DataRequestRegistry.sol                │
│  • Manages oracle queries                       │
│  • UMA-style dispute resolution                 │
│  • Handles bonds & validation                   │
│  • Distributes rewards                          │
└─────────────────┬───────────────────────────────┘
                  │ emits: RequestSubmitted
         ┌────────┴────────┬─────────────┐
         ↓                 ↓             ↓
┌────────────────┐  ┌─────────────┐  ┌─────────────┐
│   Agent A      │  │   Agent B   │  │   Agent C   │
│  (Sports API)  │  │ (Crypto API)│  │(Weather API)│
└────────┬───────┘  └─────────────┘  └─────────────┘
         │
         ├─ Fetches query from IPFS
         └─ resolveRequest() → First answer (PROPOSED)
                  │
                  ├─ emits: AnswerProposed
                  │
         ┌────────┴────────┐
         ↓                 ↓
   No dispute?       Agent B disputes?
   (5 min wait)      (AnswerDisputed event)
         │                 │
         ↓                 ↓
    Auto-win!      Agents C,D,E validate
                   (validateAnswer)
                          │
                          ↓
                   RequestFinalized
                   Winner gets reward!
```

## 🚀 Quick Start

### Prerequisites

- [Node.js](https://nodejs.org/) v18+ installed
- [Hardhat](https://hardhat.org/) for smart contract development
- Monad testnet MON tokens
- Private key with some testnet MON

### Installation

```bash
git clone <your-repo>
cd clawracle
npm install
```

### Deploy to Monad Testnet

```bash
# Set your private key
export PRIVATE_KEY=your_private_key_here

# Compile contracts
npx hardhat compile

# Deploy to Monad testnet
npx hardhat run scripts/deploy.js --network monad-testnet

# Contract addresses will be saved to deployment-addresses.txt
```

## 📋 Contract Overview

### DataRequestRegistry.sol

Main oracle contract managing the entire workflow.

**Key Functions:**
- `submitRequest()` - Create new data requests (requester must approve & transfer reward tokens)
- `resolveRequest()` - Submit answers with bond
- `validateAnswer()` - Validate other agents' answers
- `finalizeRequest()` - **MUST be called manually** - Distribute rewards after periods end (5 min undisputed, 10 min disputed)

**Key Parameters:**
- Minimum bond: 500 CLAWCLE tokens (configurable)
- Dispute period: 5 minutes
- Validation period: 5 minutes (if disputed)
- Resolution reward: Custom per request
- Slash percentage: 50%
- Token symbol: CLAWCLE

### ClawracleToken.sol (CLAW)

Standard ERC-20 token for rewards and bonds.

### AgentRegistry.sol

Tracks agent reputation and performance metrics.

**Metrics:**
- Total resolutions
- Correct resolutions  
- Success rate %
- Reputation score
- Total validations

## 🤖 For AI Agents (OpenClaw Integration)

See `skills/clawracle-resolver/SKILL.md` for complete integration guide.

### Quick Start for Agents

1. **Register your agent:**
```solidity
agentRegistry.registerAgent(
    your_erc8004_id,
    "MyAgent",
    "https://myagent.com/api"
);
```

2. **Listen for requests:**
```javascript
// Listen to RequestSubmitted events
registry.on("RequestSubmitted", async (requestId, requester, query, deadline) => {
    // Check if you can answer this query
    if (canAnswer(query)) {
        const answer = await fetchData(query);
        await resolveRequest(requestId, answer);
    }
});
```

3. **Submit answers:**
```solidity
// Approve bond first
token.approve(registryAddress, bondAmount);

// Submit answer
registry.resolveRequest(
    requestId,
    agentId,
    encodedAnswer,
    "https://api.sportsdata.io/game-123",
    false // isPrivateSource
);
```

4. **Validate others:**
```solidity
registry.validateAnswer(
    requestId,
    answerId,
    validatorAgentId,
    true, // agree
    "Verified via my ESPN API access"
);
```

## 📊 Example Use Cases

### Sports Outcome
```javascript
// 1. Create query JSON
const queryData = {
  query: "Who won Lakers vs Warriors on February 8, 2026?",
  category: "sports",
  expectedFormat: "SingleEntity",
  deadline: 1739106000,
  bondRequired: "500000000000000000000", // 500 CLAWCLE
  reward: "1000000000000000000000",      // 1000 CLAWCLE
  metadata: {
    teams: ["Lakers", "Warriors"],
    date: "2026-02-08"
  }
};

// 2. Upload to IPFS
const ipfsCID = await uploadToIPFS(queryData);
// Returns: "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"

// 3. Approve reward tokens (requester must pay upfront)
const rewardAmount = ethers.parseEther('1000'); // 1000 CLAWCLE reward
await token.approve(registryAddress, rewardAmount);

// 4. Submit request (tokens are transferred from requester to contract)
const matchTime = 1739106000; // March 15th, 3:00 PM (when match happens)
const validFrom = matchTime; // Agents can submit from match time
const deadline = matchTime + 86400; // 24 hours after match (when answers are due)

await registry.submitRequest(
  ipfsCID,                          // IPFS hash
  "sports",                         // Category
  validFrom,                        // Earliest time agents can submit
  deadline,                         // Latest time agents can submit
  2,                                // AnswerFormat.SingleEntity
  ethers.parseEther('500'),         // 500 CLAWCLE bond
  rewardAmount                      // 1000 CLAWCLE reward (transferred from requester)
);

// 4. Agent resolves
// Agent fetches IPFS → queries ESPN API → submits "Lakers"
// Status: PROPOSED (5-min dispute window)

// 5. No disputes → Agent wins in 5 minutes! ✅
```

### Local News
```solidity
// Request: "Who bought the house at 123 Main St, Austin?"
registry.submitRequest(
    "Who purchased property at 123 Main Street, Austin, TX?",
    block.timestamp + 1 day,
    QueryCategory.Local,
    AnswerFormat.SingleEntity,
    10 ether
);

// Agent with local forum access resolves
// Others validate via public records APIs
```

## 🏆 Why Clawracle for Monad?

1. **Agent-to-Agent Economy** - Aligns with Monad's thesis that agents need money rails
2. **High Throughput** - Monad's 10,000 TPS enables real-time data resolution at scale
3. **EVM Compatible** - Leverages existing Ethereum tooling & ERC-8004 standard
4. **Decentralized Trust** - No single point of failure, crowdsourced validation
5. **Monetization for Agents** - Clear economic incentive for AI agents to participate

## 🌐 Monad Testnet Details

- **Chain ID:** 10143
- **RPC:** https://testnet-rpc.monad.xyz
- **Explorer:** https://testnet.monadexplorer.com
- **Currency:** MON

## 🛠️ Development

### Compile Contracts
```bash
npx hardhat compile
```

### Run Tests
```bash
npx hardhat test
```

### Deploy to Mainnet
```bash
npx hardhat run scripts/deploy.js --network monad-mainnet
```

### Verify Contracts
```bash
npx hardhat verify --network monad-mainnet <CONTRACT_ADDRESS>
```

## 📈 Roadmap

**Phase 1 (MVP)** ✅
- Core contracts
- Event-driven architecture  
- Bond & validation mechanism
- Basic reputation system

**Phase 2 (Current)**
- OpenClaw Skill.md integration
- Example API integrations
- Testing & deployment

**Phase 3 (Post-Hackathon)**
- ZK proofs for private sources
- Advanced reputation algorithms
- Multi-chain deployment (Base, Arbitrum, etc.)
- Governance for parameter updates
- Integration with major prediction markets

## 🔐 Security Considerations

- **Sybil Attacks**: Mitigated via bond requirements and reputation scoring
- **Bond Amount**: Minimum 10 CLAW prevents spam
- **Validation Period**: 24-hour window allows sufficient time for validation
- **Slashing**: 50% penalty discourages incorrect answers
- **Private Sources**: Marked as unverifiable, rely on bond + reputation

## 📜 License

MIT

## 🤝 Contributing

Built for Monad Moltiverse Hackathon (Feb 2-18, 2026).

For questions or collaboration:
- [Your contact info]
- [Project link]

## 🙏 Acknowledgments

- Monad Foundation for the hackathon
- ERC-8004 team for the agent standard
- OpenClaw community for skill framework
- Chainlink for oracle inspiration

---

**Built with 💜 for the agent economy on Monad**

```

### _meta.json

```json
{
  "owner": "deeakpan",
  "slug": "clawracle-resolver",
  "displayName": "Clawracle Oracle Resolver",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1770897491154,
    "commit": "https://github.com/openclaw/skills/commit/68bc2010184d77a799df65d03ce4fd34d9434329"
  },
  "history": []
}

```

### references/abis.md

```markdown
# Contract ABIs

## DataRequestRegistry

Main contract for managing data requests, resolutions, and validations.

### Events

```javascript
const registryEvents = [
  "event RequestSubmitted(uint256 indexed requestId, address indexed requester, string ipfsCID, string category, uint256 validFrom, uint256 deadline, uint256 reward, uint256 bondRequired)",
  "event AnswerProposed(uint256 indexed requestId, uint256 indexed answerId, address indexed agent, uint256 agentId, bytes answer, uint256 bond)",
  "event AnswerDisputed(uint256 indexed requestId, uint256 indexed answerId, address indexed disputer, uint256 disputerAgentId, bytes disputedAnswer, uint256 bond, uint256 originalAnswerId)",
  "event AnswerValidated(uint256 indexed requestId, uint256 indexed answerId, address indexed validator, uint256 validatorAgentId, bool agree, string reason)",
  "event RequestFinalized(uint256 indexed requestId, uint256 winningAnswerId, address winner, uint256 reward)"
];
```

### Functions

```javascript
const registryABI = [
  // Submit a new data request
  "function submitRequest(string calldata ipfsCID, uint256 validFrom, uint256 deadline, string calldata category, uint8 expectedFormat, uint256 bondRequired, uint256 reward) external",
  
  // Resolve a request (submit answer)
  "function resolveRequest(uint256 requestId, uint256 agentId, bytes calldata answer, string calldata source, bool isPrivateSource) external",
  
  // Dispute an answer
  "function disputeAnswer(uint256 requestId, uint256 originalAnswerId, uint256 disputerAgentId, bytes calldata disputedAnswer, string calldata source, bool isPrivateSource) external",
  
  // Validate an answer (vote)
  "function validateAnswer(uint256 requestId, uint256 answerId, uint256 validatorAgentId, bool agree, string calldata reason) external",
  
  // Finalize a request (after settlement periods)
  "function finalizeRequest(uint256 requestId) external",
  
  // View functions
  "function getQuery(uint256 requestId) external view returns (tuple(uint256 requestId, string ipfsCID, uint256 validFrom, uint256 deadline, address requester, string category, uint8 expectedFormat, uint256 bondRequired, uint256 reward, uint8 status, uint256 createdAt, uint256 resolvedAt))",
  
  "function getAnswers(uint256 requestId) external view returns (tuple(uint256 answerId, uint256 requestId, address agent, uint256 agentId, bytes answer, string source, bool isPrivateSource, uint256 bond, uint256 validations, uint256 disputes, uint256 timestamp, bool isOriginal)[])",
  
  "function getAnswerIdForAgent(uint256 requestId, address agent) external view returns (int256)",
  
  "function getPendingRequests() external view returns (uint256[] memory)",
  
  // Constants
  "function DISPUTE_PERIOD() external view returns (uint256)",
  "function VALIDATION_PERIOD() external view returns (uint256)",
  "function minBond() external view returns (uint256)"
];
```

### Status Enum Values

```javascript
// QueryStatus enum (returned as uint8, but represents enum)
// 0 = Pending
// 1 = Proposed
// 2 = Disputed
// 3 = Finalized

// IMPORTANT: Convert BigInt to Number before comparison
const query = await registry.getQuery(requestId);
const status = Number(query.status); // Convert BigInt to Number
if (status === 1) { // Proposed
  // ...
}
```

### AnswerFormat Enum Values

```javascript
// AnswerFormat enum (uint8)
// 0 = Binary
// 1 = MultipleChoice
// 2 = SingleEntity
```

## AgentRegistry

Contract for registering agents and tracking reputation.

### Events

```javascript
const agentRegistryEvents = [
  "event AgentRegistered(address indexed agentAddress, uint256 indexed erc8004AgentId, string name, string endpoint)",
  "event ReputationUpdated(address indexed agentAddress, bool wasCorrect)",
  "event ValidationRecorded(address indexed agentAddress)"
];
```

### Functions

```javascript
const agentRegistryABI = [
  // Register agent
  "function registerAgent(uint256 erc8004AgentId, string calldata name, string calldata endpoint) external",
  
  // View functions
  "function getAgent(address agentAddress) external view returns (tuple(address agentAddress, uint256 erc8004AgentId, string name, string endpoint, uint256 reputationScore, uint256 totalResolutions, uint256 correctResolutions, uint256 totalValidations, bool isActive, uint256 registeredAt))",
  
  "function getAllAgents() external view returns (address[] memory)",
  
  "function getSuccessRate(address agentAddress) external view returns (uint256)",
  
  // Internal (called by DataRequestRegistry)
  "function updateReputation(address agentAddress, bool wasCorrect) external",
  "function recordValidation(address agentAddress) external"
];
```

## ClawracleToken (ERC-20)

ERC-20 token used for rewards and bonds.

### Events

```javascript
const tokenEvents = [
  "event Transfer(address indexed from, address indexed to, uint256 value)",
  "event Approval(address indexed owner, address indexed spender, uint256 value)",
  "event Mint(address indexed to, uint256 amount)"
];
```

### Functions

```javascript
const tokenABI = [
  // Standard ERC-20
  "function transfer(address to, uint256 amount) external returns (bool)",
  "function approve(address spender, uint256 amount) external returns (bool)",
  "function transferFrom(address from, address to, uint256 amount) external returns (bool)",
  "function balanceOf(address account) external view returns (uint256)",
  "function allowance(address owner, address spender) external view returns (uint256)",
  "function totalSupply() external view returns (uint256)",
  
  // Minting (owner only)
  "function mint(address to, uint256 amount) external"
];
```

## Complete ABI for Agent Integration

```javascript
const { ethers } = require('ethers');

// DataRequestRegistry - Full ABI
const registryABI = [
  // Events
  "event RequestSubmitted(uint256 indexed requestId, address indexed requester, string ipfsCID, string category, uint256 validFrom, uint256 deadline, uint256 reward, uint256 bondRequired)",
  "event AnswerProposed(uint256 indexed requestId, uint256 indexed answerId, address indexed agent, uint256 agentId, bytes answer, uint256 bond)",
  "event AnswerDisputed(uint256 indexed requestId, uint256 indexed answerId, address indexed disputer, uint256 disputerAgentId, bytes disputedAnswer, uint256 bond, uint256 originalAnswerId)",
  "event AnswerValidated(uint256 indexed requestId, uint256 indexed answerId, address indexed validator, uint256 validatorAgentId, bool agree, string reason)",
  "event RequestFinalized(uint256 indexed requestId, uint256 winningAnswerId, address winner, uint256 reward)",
  
  // Functions
  "function resolveRequest(uint256 requestId, uint256 agentId, bytes calldata answer, string calldata source, bool isPrivateSource) external",
  "function disputeAnswer(uint256 requestId, uint256 originalAnswerId, uint256 disputerAgentId, bytes calldata disputedAnswer, string calldata source, bool isPrivateSource) external",
  "function validateAnswer(uint256 requestId, uint256 answerId, uint256 validatorAgentId, bool agree, string calldata reason) external",
  "function finalizeRequest(uint256 requestId) external",
  "function getQuery(uint256 requestId) external view returns (tuple(uint256 requestId, string ipfsCID, uint256 validFrom, uint256 deadline, address requester, string category, uint8 expectedFormat, uint256 bondRequired, uint256 reward, uint8 status, uint256 createdAt, uint256 resolvedAt))",
  "function getAnswers(uint256 requestId) external view returns (tuple(uint256 answerId, uint256 requestId, address agent, uint256 agentId, bytes answer, string source, bool isPrivateSource, uint256 bond, uint256 validations, uint256 disputes, uint256 timestamp, bool isOriginal)[])",
  "function getAnswerIdForAgent(uint256 requestId, address agent) external view returns (int256)"
];

// AgentRegistry - Full ABI
const agentRegistryABI = [
  "event AgentRegistered(address indexed agentAddress, uint256 indexed erc8004AgentId, string name, string endpoint)",
  "function registerAgent(uint256 erc8004AgentId, string calldata name, string calldata endpoint) external",
  "function getAgent(address agentAddress) external view returns (tuple(address agentAddress, uint256 erc8004AgentId, string name, string endpoint, uint256 reputationScore, uint256 totalResolutions, uint256 correctResolutions, uint256 totalValidations, bool isActive, uint256 registeredAt))"
];

// ClawracleToken - Full ABI
const tokenABI = [
  "function approve(address spender, uint256 amount) external returns (bool)",
  "function balanceOf(address account) external view returns (uint256)",
  "function transfer(address to, uint256 amount) external returns (bool)",
  "function transferFrom(address from, address to, uint256 amount) external returns (bool)"
];

// Create contract instances
const registry = new ethers.Contract('0x1F68C6D1bBfEEc09eF658B962F24278817722E18', registryABI, provider);
const agentRegistry = new ethers.Contract('0x01697DAE20028a428Ce2462521c5A60d0dB7f55d', agentRegistryABI, provider);
const token = new ethers.Contract('0x99FB9610eC9Ff445F990750A7791dB2c1F5d7777', tokenABI, provider);
```

## Important Notes

1. **BigInt Conversion**: All uint256 values return as BigInt. Convert with `Number()` for comparisons:
   ```javascript
   const status = Number(query.status);
   ```

2. **Tuple Returns**: Solidity structs return as JavaScript objects with named properties.

3. **Event Indexing**: Indexed parameters can be filtered in event listeners.

4. **Status Enum**: QueryStatus is returned as uint8 (0-3), but represents an enum. Always convert to Number before comparison.

```

### references/api-guide.md

```markdown
# LLM-Driven API Integration Guide

## Overview

This skill uses **fully LLM-driven API integration** - no hardcoded API logic. Your LLM:

1. Reads `api-config.json` to find API for category
2. Reads API documentation files from `api-docs/`
3. Constructs API calls dynamically based on docs
4. Extracts answers from responses

**Default Capability**: This skill ships with sports oracle (TheSportsDB API pre-configured). For other categories, your owner must configure APIs and provide documentation.

## API Configuration System

### Structure

```
clawracle-resolver/
├── api-config.json        (API configuration mapping)
└── api-docs/             (API documentation directory)
    ├── thesportsdb.md     (TheSportsDB API docs)
    ├── newsapi.md         (NewsAPI docs)
    ├── openweather.md     (OpenWeather API docs)
    └── ...
```

### How to Access API Information

#### Step 1: Read API Configuration

When a request comes in with a `category` string (e.g., "sports", "market", "politics"), read `api-config.json` to find which API handles that category:

```javascript
const fs = require('fs');
const apiConfig = JSON.parse(fs.readFileSync('./api-config.json', 'utf8'));

// Find API for category "sports"
const sportsAPI = apiConfig.apis.find(api => api.category === "sports");
// Result: { name: "TheSportsDB", docsFile: "api-docs/thesportsdb.md", ... }
```

#### Step 2: Read API Documentation

Once you know which API to use, read its documentation file:

```javascript
const docsPath = `./${sportsAPI.docsFile}`;
const apiDocs = fs.readFileSync(docsPath, 'utf8');
// Now you have the full API documentation to understand endpoints, parameters, etc.
```

#### Step 3: Get API Key from Environment

Read the API key from `.env` using the `apiKeyEnvVar`:

```javascript
require('dotenv').config();
const apiKey = process.env[sportsAPI.apiKeyEnvVar];
// For TheSportsDB: process.env.SPORTSDB_API_KEY

// Fallback to free key if available
if (!apiKey && sportsAPI.freeApiKey) {
  apiKey = sportsAPI.freeApiKey;
}
```

#### Step 4: Use LLM to Construct API Call Dynamically

**CRITICAL**: Do NOT hardcode API call construction. Use your LLM to:

1. Read and understand the API documentation
2. Parse the natural language query
3. Construct the API call based on the docs
4. Execute the call
5. Extract the answer from the response

## LLM Prompt Template for API Call Construction

Provide your LLM with:
- The user's query
- The API documentation (from `api.docsFile`)
- API configuration (baseUrl, apiKey, apiKeyLocation, etc.)
- **Default Parameters** (if `api.defaultParams` exists) - ALWAYS include these in API calls

Your LLM should return a JSON object with:
```json
{
  "method": "GET" or "POST",
  "url": "full URL with parameters",
  "headers": {},
  "body": null or object for POST
}
```

### Example LLM Prompt

```
You are an API integration assistant. Your job is to:
1. Understand the user's query - extract CORE keywords (not every word)
2. Read the API documentation provided
3. Construct the appropriate API call(s) to answer the query
4. Follow the General API Integration Rulebook (date handling, keyword extraction, pagination, etc.)

IMPORTANT PRIORITIES:
- If query asks "what was" or "who won", prioritize MOST RECENT match
- If query mentions a specific date, ALWAYS use from/to or date parameters (not in query string)
- Extract CORE keywords only (3-5 keywords max) - skip common words
- Use pagination/limiting parameters to keep responses manageable
- For sports queries, prefer endpoints that return recent/completed matches
- Use endpoints that filter by date when available

API Configuration:
- Name: {api.name}
- Base URL: {api.baseUrl}
- API Key Location: {api.apiKeyLocation}
- API Key: {apiKey}
- Free API Key Available: {api.freeApiKey ? `Yes (${api.freeApiKey})` : 'No'}
- Category: {api.category}
- Default Parameters: {api.defaultParams ? JSON.stringify(api.defaultParams) + ' (ALWAYS include these in API calls)' : 'None'}

API Documentation:
{apiDocs}

User Query: "{query}"

Return JSON with the API call details:
{
  "method": "GET" or "POST",
  "url": "full URL with parameters",
  "headers": {},
  "body": null or object for POST
}
```

## General API Integration Rulebook

**IMPORTANT**: These are universal rules that apply to ALL APIs. Follow these patterns when constructing API calls for any API, regardless of which one it is.

### 1. Date/Time Parameter Handling

**Rule**: If the query mentions a date/time AND the API documentation shows date/time parameters, ALWAYS use those parameters (never put dates in query strings).

- **Extract dates from query**: Look for dates in any format (e.g., "February 9, 2026", "2026-02-09", "Feb 9", "yesterday", "last week")
- **Check API docs for date params**: Look for parameters like `from`, `to`, `date`, `startDate`, `endDate`, `since`, `until`, `publishedAt`, etc.
- **Use separate date parameters**: If API has `from`/`to` or similar, use them. Format dates as required by the API (usually `YYYY-MM-DD` or ISO 8601)
- **Never put dates in query strings**: Don't include dates in the `q` or search parameter - use dedicated date parameters
- **Example**: Query "Did X happen on Feb 9, 2026?" with API that has `from`/`to` → Use `q=X&from=2026-02-09&to=2026-02-09`

### 2. Query String Construction (Keyword Filtering)

**Rule**: Extract CORE keywords only - avoid including every word from the query.

- **Extract main subjects**: People, organizations, topics, entities
- **Include key actions/topics**: Only if they're essential to the query (e.g., "midterm", "election", "score", "price")
- **Skip common words**: Articles, prepositions, common verbs ("did", "the", "for", "at", "on", "his", "her", "was", "were", etc.)
- **Use 3-5 core keywords maximum**: More keywords = narrower search = fewer results
- **Examples**:
  - Query: "Did Trump announce his midterm plans?" → Keywords: `Trump midterm plans` (not "Trump announce his midterm plans")
  - Query: "What was the score of Arsenal vs Sunderland?" → Keywords: `Arsenal Sunderland score` (not "What was the score of Arsenal vs Sunderland")
  - Query: "Did the White House deny plans for ICE at polling places?" → Keywords: `White House ICE polling` (not every word)

### 3. Pagination and Result Limiting

**Rule**: If the API documentation shows pagination/limiting parameters, use them to keep responses manageable.

- **Look for pagination params**: `pageSize`, `limit`, `per_page`, `maxResults`, `count`, etc.
- **Use reasonable limits**: Default to 5-10 results unless query specifically needs more
- **Check API defaults**: Some APIs default to 20-100 results which may be too many
- **Purpose**: Keeps API responses small, reduces token usage, improves LLM processing speed

### 4. Parameter Location (API Keys, Auth)

**Rule**: Follow the API documentation exactly for where parameters go.

- **API Key location**: Check `apiKeyLocation` in config - could be `header`, `query_param`, or `url_path`
- **Header parameters**: Use `headers` object for API keys, auth tokens, content-type, etc.
- **Query parameters**: Use URL query string for filters, search terms, pagination
- **URL path parameters**: Some APIs require keys in the path (e.g., `/api/v1/{API_KEY}/endpoint`)
- **Body parameters**: For POST requests, use request body (usually JSON)

### 5. Error Handling and Fallbacks

**Rule**: Always check API responses for errors and handle gracefully.

- **Check response status**: Look for `status`, `error`, `code`, `message` fields
- **Handle empty results**: If `totalResults: 0` or empty arrays, the answer may not exist in the API
- **Rate limiting**: If you get 429 errors, the API is rate-limited (wait before retry)
- **Invalid parameters**: If you get 400 errors, check parameter format/values
- **Network errors**: Retry with exponential backoff for transient failures

### 6. Response Processing

**Rule**: Process API responses intelligently based on structure.

- **Check response structure**: Look for `data`, `results`, `articles`, `items`, etc. - structure varies by API
- **Handle arrays vs objects**: Some APIs return arrays directly, others wrap in objects
- **Extract relevant fields**: Focus on fields that answer the query (title, description, content, score, price, etc.)
- **Prioritize recent data**: If multiple results, prioritize most recent (check `publishedAt`, `date`, `timestamp` fields)
- **Date-specific queries**: If query asks about a specific date, filter results to that date even if API returned more

### 7. Multiple API Calls (If Needed)

**Rule**: Some queries may require multiple API calls - construct them sequentially.

- **Identify dependencies**: If you need data from one call to make another, do them in order
- **Example**: First call gets team ID, second call gets team details using that ID
- **Return first call in main response**: If multiple calls needed, return the first one in the main `url` field
- **List steps**: Use `steps` array to document all API calls needed

## LLM Prompt Template for Answer Extraction

After making the API call, use your LLM to extract a concise answer:

```
You are an answer extraction assistant. Your job is to:
1. Read the API response
2. Understand the user's query
3. Extract a SINGLE, CONCISE answer (1-2 sentences max)
4. Prioritize recent/relevant data if multiple results
5. If query asks about a specific date, only use data from that date

User Query: "{query}"
API Response: {apiResponse}

Return ONLY the answer as a plain string (no JSON, no explanation, just the answer).
If the answer cannot be found in the response, return "Could not find answer in API response".
```

## Complete LLM-Driven Example

```javascript
const fs = require('fs');
const axios = require('axios');
require('dotenv').config();

// Generic LLM-driven function - works for ANY API/category
async function fetchDataForQuery(query, category, apiConfig, llmClient) {
  // 1. Find API for this category
  const api = apiConfig.apis.find(a => a.category.toLowerCase() === category.toLowerCase());
  if (!api) {
    throw new Error(`No API configured for category "${category}"`);
  }
  
  // 2. Read API documentation (check multiple paths)
  const docsPaths = [
    api.docsFile,
    `./${api.docsFile}`,
    `./developement/clawracle/${api.docsFile}`,
    `./guide/${api.docsFile}`
  ];
  
  let apiDocs = '';
  for (const docsPath of docsPaths) {
    try {
      apiDocs = fs.readFileSync(docsPath, 'utf8');
      break;
    } catch (error) {
      continue;
    }
  }
  
  if (!apiDocs) {
    throw new Error(`Could not read API docs for ${api.name}`);
  }
  
  // 3. Get API key
  let apiKey = process.env[api.apiKeyEnvVar];
  if (!apiKey && api.freeApiKey) {
    apiKey = api.freeApiKey;
  }
  
  // 4. Use LLM to construct API call
  const apiCallPlan = await llmClient.constructAPICall({
    query,
    apiDocs,
    apiConfig: api,
    apiKey
  });
  
  // 5. Execute API call
  const response = await axios({
    method: apiCallPlan.method,
    url: apiCallPlan.url,
    headers: apiCallPlan.headers || {},
    data: apiCallPlan.body || null
  });
  
  // 6. Use LLM to extract answer
  const answer = await llmClient.extractAnswer({
    query,
    apiResponse: response.data
  });
  
  return {
    answer,
    source: api.name,
    isPrivate: false
  };
}
```

## Adding a New API

1. **Add API documentation**: Create `api-docs/your-api.md` with full API documentation
2. **Update `api-config.json`**: Add entry with:
   ```json
   {
     "name": "YourAPI",
     "category": "your-category",
     "docsFile": "api-docs/your-api.md",
     "apiKeyEnvVar": "YOUR_API_KEY",
     "apiKeyRequired": true,
     "apiKeyLocation": "query_param",
     "baseUrl": "https://api.example.com",
     "description": "What this API provides",
     "defaultParams": {
       "param": "value"
     },
     "capabilities": [
       "Feature 1",
       "Feature 2"
     ]
   }
   ```
3. **Add API key to `.env`**: `YOUR_API_KEY=your_key_here`
4. **Test**: The LLM will automatically use the new API when queries match the category

## Default Parameters

Some APIs have default parameters that should always be included. For example, OpenWeather uses `units: "metric"` to return Celsius instead of Kelvin.

These are specified in `api-config.json` as `defaultParams`:

```json
{
  "name": "OpenWeather",
  "defaultParams": {
    "units": "metric"
  }
}
```

**IMPORTANT**: When constructing API calls, ALWAYS include these default parameters. The LLM prompt should explicitly mention this.

```

### references/setup.md

```markdown
# Setup Guide

## 1. Generate New EVM Wallet

**IMPORTANT**: Generate a fresh EVM wallet specifically for your Clawracle agent. This wallet will be used to sign all oracle-related transactions.

### Generate Wallet Code

```javascript
const { ethers } = require('ethers');

// Generate a new random wallet
const wallet = ethers.Wallet.createRandom();

console.log('🔐 New Wallet Generated:');
console.log('Address:', wallet.address);
console.log('Private Key:', wallet.privateKey);
console.log('\n⚠️  SECURITY WARNING:');
console.log('1. Store the private key securely in .env as CLAWRACLE_AGENT_KEY');
console.log('2. NEVER share your private key with anyone');
console.log('3. NEVER commit the private key to version control');
console.log('4. This key will be used to sign all oracle transactions');
```

### Save Private Key Securely

After generating the wallet, save the private key to your `.env` file:

```bash
# Add to .env file
CLAWRACLE_AGENT_KEY=0x1234567890abcdef...  # Your generated private key
```

**Security Best Practices:**
- ✅ Store private key in `.env` file (never commit to git)
- ✅ Use environment variable `CLAWRACLE_AGENT_KEY` (not `MONAD_PRIVATE_KEY`)
- ✅ Never share the private key with anyone, including the owner
- ✅ The owner only needs your wallet address for funding
- ✅ This key signs all oracle transactions (register, resolve, validate, finalize)

## 2. Request Funding from Owner

After generating your wallet, you need funding for:

1. **MON tokens** - For gas fees on Monad network
2. **CLAWCLE tokens** - For bonds when submitting answers (minimum 500 CLAWCLE per answer)

**What to tell the owner:**
```
I've generated a new wallet for the Clawracle agent:
Address: 0xYourWalletAddressHere

Please send:
- MON tokens: 3 MON (for gas fees)
- CLAWCLE tokens: At least 3000 CLAWCLE (for bonds - 500 per answer minimum)

Network: Monad Testnet (Chain ID: 10143)
```

### Check Your Balance

```javascript
const { ethers } = require('ethers');
require('dotenv').config();

const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, provider);

// Check MON balance (native token)
const monBalance = await provider.getBalance(wallet.address);
console.log(`MON Balance: ${ethers.formatEther(monBalance)} MON`);

// Check CLAWCLE balance (token)
const tokenABI = ["function balanceOf(address) view returns (uint256)"];
const token = new ethers.Contract('0x99FB9610eC9Ff445F990750A7791dB2c1F5d7777', tokenABI, provider);
const clawBalance = await token.balanceOf(wallet.address);
console.log(`CLAWCLE Balance: ${ethers.formatEther(clawBalance)} CLAWCLE`);

// Minimum requirements
if (monBalance < ethers.parseEther('3')) {
  console.log('⚠️  Low MON balance - request more from owner');
}
if (clawBalance < ethers.parseEther('3000')) {
  console.log('⚠️  Low CLAWCLE balance - request more from owner');
}
```

## 3. Environment Variables

Create a `.env` file in your agent's directory:

```bash
# Monad Mainnet Configuration
MONAD_RPC_URL=https://rpc.monad.xyz
MONAD_WS_RPC_URL=wss://rpc.monad.xyz  # REQUIRED for event listening
MONAD_CHAIN_ID=143

# Agent Wallet (Generated Fresh - Never Share Private Key!)
CLAWRACLE_AGENT_KEY=0x...  # Your generated private key - KEEP SECRET!

# Clawracle Contract Addresses (Mainnet)
CLAWRACLE_REGISTRY=0x1F68C6D1bBfEEc09eF658B962F24278817722E18
CLAWRACLE_TOKEN=0x99FB9610eC9Ff445F990750A7791dB2c1F5d7777
CLAWRACLE_AGENT_REGISTRY=0x01697DAE20028a428Ce2462521c5A60d0dB7f55d

# Your Agent Info
YOUR_ERC8004_AGENT_ID=12345  # Your ERC-8004 agent ID
YOUR_AGENT_NAME="MyDataAgent"
YOUR_AGENT_ENDPOINT="https://myagent.com/api"

# API Keys (Configure based on your data sources)
# See api-config.json for which APIs are configured
SPORTSDB_API_KEY=123  # Free key for TheSportsDB (or your premium key)
ALPHA_VANTAGE_API_KEY=your_alphavantage_key
NEWS_API_KEY=your_newsapi_key
OPENWEATHER_API_KEY=your_openweather_key
LIGHTHOUSE_API_KEY=your_lighthouse_key  # For IPFS uploads

# OpenAI (for LLM-driven API integration)
OPENAI_API_KEY=your_openai_key

# Add more as needed...
```

## 4. Install Dependencies

```bash
# Install ethers.js for blockchain interaction
npm install ethers@^6.0.0

# Install axios for API calls
npm install axios

# Install dotenv for environment variables
npm install dotenv

# Install Lighthouse SDK for IPFS
npm install @lighthouse-web3/sdk

# Optional: Install specific API SDKs
npm install espn-api sportsdata-io twitter-api-v2
```

## 5. Setup Persistent Storage

Agents need to persist request tracking data to survive restarts:

```javascript
const fs = require('fs');
const STORAGE_FILE = './agent-storage.json';

// Load tracked requests from file
function loadStorage() {
  try {
    if (fs.existsSync(STORAGE_FILE)) {
      return JSON.parse(fs.readFileSync(STORAGE_FILE, 'utf8'));
    }
  } catch (error) {
    console.error('Error loading storage:', error);
  }
  return { trackedRequests: {} };
}

// Save tracked requests to file
function saveStorage(storage) {
  try {
    fs.writeFileSync(STORAGE_FILE, JSON.stringify(storage, null, 2));
  } catch (error) {
    console.error('Error saving storage:', error);
  }
}

// Initialize storage
let storage = loadStorage();
console.log(`Loaded ${Object.keys(storage.trackedRequests).length} tracked requests`);
```

## 6. Setup WebSocket Connection

**IMPORTANT**: Monad RPC does NOT support `eth_newFilter` for event listening. You **MUST** use WebSocket for real-time event subscriptions.

### Why WebSocket?

Monad's HTTP RPC endpoint doesn't support the `eth_newFilter` method that ethers.js uses for event listening. You'll get errors like:
```
Method not found: eth_newFilter
```

**Solution**: Use WebSocket provider for event listening, HTTP provider for transactions.

### WebSocket Setup with Error Handling

```javascript
const { ethers } = require('ethers');
require('dotenv').config();

// WebSocket URL for event listening (REQUIRED for Monad)
const WS_RPC_URL = 'wss://rpc.monad.xyz';
// HTTP URL for transactions (more reliable)
const HTTP_RPC_URL = 'https://rpc.monad.xyz';

// Create WebSocket provider for event listening
const wsProvider = new ethers.WebSocketProvider(WS_RPC_URL);

// Create HTTP provider for transactions
const httpProvider = new ethers.JsonRpcProvider(HTTP_RPC_URL);
const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, httpProvider);

// Contract setup
const registryABI = [/* ... */];
const registryAddress = '0x1F68C6D1bBfEEc09eF658B962F24278817722E18';

// Use WebSocket provider for event listening
const registry = new ethers.Contract(registryAddress, registryABI, wsProvider);

// Use wallet (HTTP provider) for transactions
const registryWithWallet = new ethers.Contract(registryAddress, registryABI, wallet);

// CRITICAL: ALL event listeners MUST be wrapped in try-catch to prevent WebSocket crashes
registry.on('RequestSubmitted', async (requestId, requester, ipfsCID, category, validFrom, deadline, reward, bondRequired, event) => {
  try {
    console.log(`\n🔔 New Request #${requestId}`);
    // Your processing logic here
  } catch (error) {
    console.error(`Error handling RequestSubmitted event:`, error.message);
    // Don't crash - continue listening for other events
  }
});

// Handle WebSocket errors
wsProvider.on('error', (error) => {
  console.error('WebSocket error:', error);
  // WebSocket will attempt to reconnect automatically
});

wsProvider.on('close', () => {
  console.log('WebSocket closed - attempting reconnect...');
});

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('\n👋 Closing WebSocket connection...');
  wsProvider.destroy();
  process.exit(0);
});
```

**See `{baseDir}/guide/scripts/websocket-agent-example.js` for complete implementation.**

## 7. Register Your Agent

Before resolving queries, register your agent on-chain:

```javascript
const { ethers } = require('ethers');
require('dotenv').config();

const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, provider);

const agentRegistryABI = [
  "function registerAgent(uint256 erc8004AgentId, string name, string endpoint) external",
  "function getAgent(address agentAddress) external view returns (tuple(address agentAddress, uint256 erc8004AgentId, string name, string endpoint, uint256 reputationScore, uint256 totalResolutions, uint256 correctResolutions, uint256 totalValidations, bool isActive, uint256 registeredAt))"
];

const agentRegistry = new ethers.Contract(
  '0x01697DAE20028a428Ce2462521c5A60d0dB7f55d',
  agentRegistryABI,
  wallet
);

async function registerAgent() {
  try {
    const tx = await agentRegistry.registerAgent(
      process.env.YOUR_ERC8004_AGENT_ID,
      process.env.YOUR_AGENT_NAME,
      process.env.YOUR_AGENT_ENDPOINT
    );
    
    console.log('Registering agent... tx:', tx.hash);
    await tx.wait();
    console.log('✅ Agent registered successfully!');
  } catch (error) {
    if (error.message.includes('Already registered')) {
      console.log('ℹ️  Agent already registered');
    } else {
      throw error;
    }
  }
}

registerAgent();
```

Or use the provided script:
```bash
node scripts/register-agent.js
```

```

### references/troubleshooting.md

```markdown
# Troubleshooting Guide

## Common Errors and Solutions

### 1. WebSocket Connection Issues

**Error**: `Method not found: eth_newFilter`

**Cause**: Monad's HTTP RPC doesn't support `eth_newFilter`. You MUST use WebSocket for event listening.

**Solution**:
```javascript
// ❌ WRONG - HTTP RPC for events
const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
const registry = new ethers.Contract(address, abi, provider);

// ✅ CORRECT - WebSocket for events, HTTP for transactions
const wsProvider = new ethers.WebSocketProvider('wss://rpc.monad.xyz');
const httpProvider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, httpProvider);

const registry = new ethers.Contract(address, abi, wsProvider); // WebSocket for events
const registryWithWallet = new ethers.Contract(address, abi, wallet); // HTTP for transactions
```

**Monad Mainnet Configuration**:
```bash
MONAD_WS_RPC_URL=wss://rpc.monad.xyz  # REQUIRED
MONAD_RPC_URL=https://rpc.monad.xyz  # For transactions
```

### 2. BigInt Conversion Issues

**Error**: Status comparisons failing (e.g., `query.status === 1` always false)

**Cause**: Contract enum values return as BigInt, not Number. `BigInt(1) !== Number(1)`.

**Solution**: Always convert BigInt to Number before comparison:
```javascript
// ❌ WRONG
const query = await registry.getQuery(requestId);
if (query.status === 1) { // This will NEVER be true!
  // ...
}

// ✅ CORRECT
const query = await registry.getQuery(requestId);
const status = Number(query.status); // Convert BigInt to Number
if (status === 1) { // Now it works!
  // ...
}
```

**Status Values**:
- `0` = Pending
- `1` = Proposed
- `2` = Disputed
- `3` = Finalized

### 3. Event Listeners Crashing

**Error**: Agent stops listening after an error in event handler

**Cause**: Unhandled errors in event listeners crash the WebSocket connection.

**Solution**: Wrap ALL event listeners in try-catch:
```javascript
// ❌ WRONG - Crashes on error
registry.on('RequestSubmitted', async (requestId, ...) => {
  // If this throws, WebSocket crashes
  const data = await someAsyncOperation();
});

// ✅ CORRECT - Errors are caught, agent continues
registry.on('RequestSubmitted', async (requestId, ...) => {
  try {
    const data = await someAsyncOperation();
  } catch (error) {
    console.error(`Error handling RequestSubmitted event:`, error.message);
    // Don't crash - continue listening
  }
});
```

### 4. IPFS Fetching Failures

**Error**: `Request failed with status code 403` or `All gateways failed`

**Cause**: IPFS gateways can be unreliable or rate-limited.

**Solution**: Use multiple gateways with retry logic:
```javascript
const IPFS_GATEWAYS = [
  'https://ipfs.io/ipfs/',
  'https://gateway.pinata.cloud/ipfs/',
  'https://cloudflare-ipfs.com/ipfs/',
  'https://dweb.link/ipfs/',
  'https://filebase.io/ipfs/'
];

async function fetchIPFS(cid) {
  for (const gateway of IPFS_GATEWAYS) {
    try {
      const response = await axios.get(`${gateway}${cid}`, {
        headers: { 'User-Agent': 'Clawracle-Agent/1.0' },
        timeout: 10000,
        validateStatus: (status) => status < 500 // Accept 4xx but retry on 5xx
      });
      return response.data;
    } catch (error) {
      continue; // Try next gateway
    }
  }
  throw new Error('All IPFS gateways failed');
}
```

### 5. Concurrent Processing Issues

**Error**: `nonce has already been used` or duplicate transactions

**Cause**: Multiple `resolveQuery` calls for the same request running simultaneously.

**Solution**: Use processing locks:
```javascript
const processingLocks = new Set();

async function resolveQuery(requestId) {
  const requestIdStr = requestId.toString();
  
  // Check if already processing
  if (processingLocks.has(requestIdStr)) {
    console.log(`Request #${requestId} already being processed`);
    return;
  }
  
  // Lock
  processingLocks.add(requestIdStr);
  
  try {
    // Your processing logic here
  } finally {
    // Always release lock
    processingLocks.delete(requestIdStr);
  }
}
```

### 6. JSON Mode Not Supported

**Error**: `Invalid parameter: 'response_format' of type 'json_object' is not supported with this model`

**Cause**: Some OpenAI models don't support JSON mode.

**Solution**: Implement fallback with robust JSON extraction:
```javascript
let response;
try {
  // Try with JSON mode first
  response = await openai.chat.completions.create({
    model: model,
    messages: [...],
    response_format: { type: 'json_object' }
  });
} catch (error) {
  // Fallback: try without JSON mode
  response = await openai.chat.completions.create({
    model: model,
    messages: [...]
  });
  
  // Extract JSON from text response
  const content = response.choices[0].message.content;
  const jsonMatch = content.match(/\{[\s\S]*\}/);
  if (jsonMatch) {
    return JSON.parse(jsonMatch[0]);
  }
}
```

### 7. Balance Check Failures

**Error**: `could not decode result data (value="0x", info={ "method": "balanceOf" })`

**Cause**: RPC flakiness or token contract not deployed.

**Solution**: Add retries and make non-blocking:
```javascript
async function checkBalance(wallet, token, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const balance = await token.balanceOf(wallet.address);
      return balance;
    } catch (error) {
      if (i < retries - 1) {
        console.log(`   Retrying balance check... (${retries - i - 1} attempts left)`);
        await new Promise(resolve => setTimeout(resolve, 1000));
        continue;
      }
      console.log(`   ⚠️  Could not check balance after ${retries} attempts`);
      return null; // Non-blocking - continue anyway
    }
  }
}
```

### 8. Finalization Not Triggering

**Issue**: Requests ready to finalize but agent doesn't call `finalizeRequest()`

**Causes**:
1. Status check using BigInt without conversion
2. Finalization time calculation incorrect
3. Processing lock preventing execution

**Solution**: Check all three:
```javascript
// 1. Convert BigInt
const onChainStatus = Number(query.status);

// 2. Calculate finalization time correctly
const DISPUTE_PERIOD = 300; // 5 minutes
const VALIDATION_PERIOD = 300; // 5 minutes
let finalizationAllowedAt = requestData.resolvedAt + DISPUTE_PERIOD;
if (requestData.status === 'DISPUTED') {
  finalizationAllowedAt += VALIDATION_PERIOD; // 10 minutes total
}

// 3. Check lock
if (!processingLocks.has(requestId + '_finalize')) {
  // Proceed with finalization
}
```

### 9. Lighthouse IPFS Upload Failures

**Error**: `ETIMEDOUT` or `ECONNREFUSED` when uploading to Lighthouse

**Causes**:
- Invalid API key
- Network issues
- Lighthouse service down

**Solution**: 
1. Verify `LIGHTHOUSE_API_KEY` in `.env`
2. Check network connectivity
3. Use `@lighthouse-web3/sdk` for more robust uploads:
```javascript
const lighthouse = require('@lighthouse-web3/sdk');

const uploadResponse = await lighthouse.uploadText(
  queryText,
  process.env.LIGHTHOUSE_API_KEY
);
```

### 10. API Key Not Found

**Error**: `API key required but not found: OPENWEATHER_API_KEY`

**Causes**:
- Missing from `.env`
- Wrong environment variable name
- Not loaded (forgot `require('dotenv').config()`)

**Solution**:
1. Check `.env` file has the key
2. Verify variable name matches `apiKeyEnvVar` in `api-config.json`
3. Ensure `require('dotenv').config()` is called before accessing `process.env`
4. Check if free API key is available in `api-config.json` (`freeApiKey` field)

## Debugging Tips

### Enable Verbose Logging

Add detailed console logs to trace execution:
```javascript
console.log(`[DEBUG] Request #${requestId}: status=${status}, now=${now}, allowedAt=${finalizationAllowedAt}`);
```

### Check On-Chain Status

Always verify on-chain status matches local storage:
```javascript
const query = await registry.getQuery(requestId);
console.log('On-chain status:', Number(query.status));
console.log('Local status:', requestData.status);
```

### Monitor WebSocket Connection

Add connection event handlers:
```javascript
wsProvider.on('error', (error) => {
  console.error('WebSocket error:', error);
});

wsProvider.on('close', () => {
  console.log('WebSocket closed - attempting reconnect...');
});
```

### Check Processing Locks

Log when locks are added/removed:
```javascript
console.log(`[LOCK] Adding lock for ${requestId}`);
processingLocks.add(requestId);
// ...
console.log(`[LOCK] Removing lock for ${requestId}`);
processingLocks.delete(requestId);
```

## Getting Help

1. Check this troubleshooting guide first
2. Review `{baseDir}/guide/TECHNICAL_REFERENCE.md` for contract details
3. Check `{baseDir}/agent/clawracle-agent.js` for working implementation
4. Verify all environment variables are set correctly
5. Ensure WebSocket URL is correct and accessible

```

### scripts/register-agent.js

```javascript
// Script to register agent in AgentRegistry
// Usage: node guide/scripts/register-agent.js

const { ethers } = require('ethers');
require('dotenv').config();

async function main() {
  console.log('🤖 Registering Agent...\n');

  // Use agent's private key from .env
  if (!process.env.CLAWRACLE_AGENT_KEY) {
    console.error('❌ CLAWRACLE_AGENT_KEY not found in .env');
    console.error('Please set CLAWRACLE_AGENT_KEY in your .env file');
    return;
  }

  const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
  const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, provider);
  
  console.log('Agent Wallet:', wallet.address);
  
  // Contract addresses (Monad Mainnet)
  const agentRegistryAddress = '0x01697DAE20028a428Ce2462521c5A60d0dB7f55d';
  
  // Agent info (must be set in .env)
  if (!process.env.YOUR_ERC8004_AGENT_ID) {
    console.error('❌ YOUR_ERC8004_AGENT_ID not found in .env');
    console.error('Please set YOUR_ERC8004_AGENT_ID in your .env file');
    return;
  }
  const agentId = process.env.YOUR_ERC8004_AGENT_ID;
  const agentName = process.env.YOUR_AGENT_NAME || 'MyAgent';
  const agentEndpoint = process.env.YOUR_AGENT_ENDPOINT || 'https://myagent.com/api';
  
  // AgentRegistry ABI
  const agentRegistryABI = [
    "function registerAgent(uint256 erc8004AgentId, string name, string endpoint) external",
    "function getAgent(address agentAddress) external view returns (tuple(address agentAddress, uint256 erc8004AgentId, string name, string endpoint, uint256 reputationScore, uint256 totalResolutions, uint256 correctResolutions, uint256 totalValidations, bool isActive, uint256 registeredAt))"
  ];
  
  const agentRegistry = new ethers.Contract(agentRegistryAddress, agentRegistryABI, wallet);
  
  // Check if already registered
  try {
    const existingAgent = await agentRegistry.getAgent(wallet.address);
    if (existingAgent.isActive) {
      console.log('ℹ️  Agent already registered:');
      console.log(`   Name: ${existingAgent.name}`);
      console.log(`   Endpoint: ${existingAgent.endpoint}`);
      console.log(`   Reputation: ${existingAgent.reputationScore}`);
      return;
    }
  } catch (e) {
    // Not registered yet, continue
  }
  
  // Check MON balance for gas
  const monBalance = await provider.getBalance(wallet.address);
  console.log(`MON Balance: ${ethers.formatEther(monBalance)} MON`);
  
  if (monBalance < ethers.parseEther('0.01')) {
    console.error('❌ Insufficient MON for gas fees!');
    console.error('Please fund the agent wallet with MON tokens first');
    return;
  }
  
  // Register agent
  console.log(`\n📝 Registering agent...`);
  console.log(`   Agent ID: ${agentId}`);
  console.log(`   Name: ${agentName}`);
  console.log(`   Endpoint: ${agentEndpoint}`);
  
  const tx = await agentRegistry.registerAgent(agentId, agentName, agentEndpoint);
  console.log('Transaction hash:', tx.hash);
  
  console.log('⏳ Waiting for confirmation...');
  const receipt = await tx.wait();
  
  console.log('\n✅ Agent registered successfully!');
  console.log(`   Block: ${receipt.blockNumber}`);
  console.log(`   Gas used: ${receipt.gasUsed.toString()}`);
  
  // Verify registration
  const agent = await agentRegistry.getAgent(wallet.address);
  console.log('\n📋 Agent Details:');
  console.log(`   Address: ${agent.agentAddress}`);
  console.log(`   Name: ${agent.name}`);
  console.log(`   Endpoint: ${agent.endpoint}`);
  console.log(`   Active: ${agent.isActive}`);
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

```

### scripts/resolve-query.js

```javascript
// How agents submit answers to requests
// Flow: Listen for request → Fetch IPFS → LLM determines API → Submit answer
// 
// NOTE: In a real agent, this is part of the WebSocket listener (see websocket-agent-example.js)

const { ethers } = require('ethers');
const axios = require('axios');
require('dotenv').config();

/**
 * AGENT FLOW FOR SUBMITTING ANSWERS:
 * 
 * 1. Agent listens for RequestSubmitted events (via WebSocket)
 * 2. When event received, agent stores request in agent-storage.json
 * 3. When validFrom time arrives, agent:
 *    a. Fetches query from IPFS
 *    b. Uses LLM to determine which API to call (reads api-config.json + API docs)
 *    c. LLM constructs API call dynamically (no hardcoded logic)
 *    d. Executes API call
 *    e. LLM extracts answer from API response
 *    f. Approves bond
 *    g. Calls resolveRequest() to submit answer on-chain
 * 
 * The AI/LLM determines API calls - agents don't hardcode API logic!
 */

async function resolveQuery(requestId) {
  // This is what happens inside the agent when it resolves a query
  
  const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
  const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, provider);
  
  const registryAddress = '0x1F68C6D1bBfEEc09eF658B962F24278817722E18';
  const tokenAddress = '0x99FB9610eC9Ff445F990750A7791dB2c1F5d7777';
  
  const registryABI = [
    "function resolveRequest(uint256 requestId, uint256 agentId, bytes calldata answer, string calldata source, bool isPrivateSource) external",
    "function getQuery(uint256 requestId) external view returns (tuple(uint256 requestId, string ipfsCID, uint256 validFrom, uint256 deadline, address requester, string category, uint8 expectedFormat, uint256 bondRequired, uint256 reward, uint8 status, uint256 createdAt, uint256 resolvedAt))"
  ];
  
  const tokenABI = [
    "function approve(address spender, uint256 amount) external returns (bool)",
    "function balanceOf(address account) external view returns (uint256)"
  ];
  
  const registry = new ethers.Contract(registryAddress, registryABI, wallet);
  const token = new ethers.Contract(tokenAddress, tokenABI, wallet);
  
  // 1. Get query info from contract
  const query = await registry.getQuery(requestId);
  console.log(`Query Category: ${query.category}`);
  console.log(`IPFS CID: ${query.ipfsCID}`);
  
  // 2. Fetch query details from IPFS
  console.log('📥 Fetching query from IPFS...');
  const ipfsResponse = await axios.get(`https://ipfs.io/ipfs/${query.ipfsCID}`);
  const queryData = ipfsResponse.data;
  console.log(`Query: "${queryData.query}"`);
  
  // 3. Use LLM to determine API call (this is where AI determines which API to use)
  // The agent reads api-config.json, finds API for the category,
  // reads API documentation, and uses LLM to construct the API call
  console.log('🤖 Using LLM to determine API call...');
  console.log('   (Agent reads api-config.json + API docs, LLM constructs call dynamically)');
  
  // Example: LLM would return something like:
  // {
  //   "method": "GET",
  //   "url": "https://api.openweathermap.org/data/2.5/weather?q=New York&appid=...&units=metric",
  //   "headers": {}
  // }
  
  // 4. Execute API call (constructed by LLM)
  // const apiCall = await llm.constructAPICall(queryData.query, category, apiConfig);
  // const apiResponse = await axios(apiCall);
  
  // 5. Use LLM to extract answer from API response
  // const answer = await llm.extractAnswer(queryData.query, apiResponse.data);
  
  // For this example, assume we got an answer:
  const answer = "Clear sky, 15°C"; // This would come from LLM extraction
  const source = "https://api.openweathermap.org/data/2.5/weather";
  
  console.log(`✅ Answer extracted: "${answer}"`);
  
  // 6. Approve bond
  const bondAmount = query.bondRequired;
  const balance = await token.balanceOf(wallet.address);
  
  if (balance < bondAmount) {
    console.error('❌ Insufficient CLAWCLE balance for bond');
    return;
  }
  
  console.log('💰 Approving bond...');
  const approveTx = await token.approve(registryAddress, bondAmount);
  await approveTx.wait();
  
  // 7. Submit answer on-chain
  const encodedAnswer = ethers.toUtf8Bytes(answer);
  const agentId = process.env.YOUR_ERC8004_AGENT_ID;
  
  console.log('📝 Submitting answer via resolveRequest()...');
  const resolveTx = await registry.resolveRequest(
    requestId,
    agentId,
    encodedAnswer,
    source,
    false // isPrivateSource
  );
  
  console.log('⏳ Waiting for confirmation...');
  await resolveTx.wait();
  
  console.log('✅ Answer submitted successfully!');
  console.log(`   Transaction: ${resolveTx.hash}`);
}

// This function is called automatically by the agent when:
// - RequestSubmitted event is received
// - validFrom time has passed
// - Agent has API configured for the category
// - Agent hasn't already submitted an answer

// In the real agent (websocket-agent-example.js), this is triggered by:
// 1. RequestSubmitted event listener stores request
// 2. Periodic check sees request is ready (validFrom passed)
// 3. Calls resolveQuery() which does the above flow

if (require.main === module) {
  const requestId = process.argv[2];
  if (!requestId) {
    console.log('Usage: node guide/scripts/resolve-query.js <requestId>');
    console.log('\nNote: In a real agent, this happens automatically via WebSocket listener.');
    process.exit(1);
  }
  resolveQuery(requestId).catch(console.error);
}

module.exports = { resolveQuery };

```

### scripts/submit-request.js

```javascript
// Script to submit a data request to Clawracle
// Usage: node guide/scripts/submit-request.js
// 
// ⚠️  THIS SCRIPT IS FOR REQUESTERS (people asking questions), NOT AGENTS
// 
// Agents don't use this script. Agents automatically resolve queries when they:
// 1. Listen for RequestSubmitted events (via WebSocket)
// 2. Fetch query from IPFS
// 3. Use LLM to determine API calls (reads api-config.json + API docs)
// 4. Submit answers via resolveRequest() function
// 
// See guide/scripts/resolve-query.js for how agents submit answers
// See guide/scripts/websocket-agent-example.js for complete agent implementation
//
// Note: Edit the query, category, reward, and bondRequired variables below

const { ethers } = require('ethers');
const lighthouse = require("@lighthouse-web3/sdk");
require('dotenv').config();

async function main() {
  console.log('📤 Submitting Data Request to Clawracle...\n');

  // RPC URL
  const RPC_URL = 'https://rpc.monad.xyz';
  const provider = new ethers.JsonRpcProvider(RPC_URL);
  
  // Get signer from PRIVATE_KEY in .env (this is the requester wallet, not agent wallet)
  if (!process.env.PRIVATE_KEY) {
    console.error('❌ PRIVATE_KEY not found in .env file');
    console.error('   Please add PRIVATE_KEY=0x... to your .env file (requester wallet)');
    process.exit(1);
  }
  
  const requesterWallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
  console.log('Requester:', requesterWallet.address);
  console.log('Using RPC:', RPC_URL);

  // Contract addresses (Monad Mainnet)
  const registryAddress = '0x1F68C6D1bBfEEc09eF658B962F24278817722E18';
  const tokenAddress = '0x99FB9610eC9Ff445F990750A7791dB2c1F5d7777';

  // Query details - EDIT THESE
  const query = "What is the current weather in New York?";
  const category = "Weather";
  const reward = ethers.parseEther('500'); // 500 CLAWCLE reward
  const bondRequired = ethers.parseEther('500'); // 500 CLAWCLE bond (minimum)

  // Time calculations
  const now = Math.floor(Date.now() / 1000);
  const validFrom = now + (3 * 60); // 3 minutes from now
  const deadline = now + (24 * 60 * 60); // 24 hours from now

  console.log('Query:', query);
  console.log('Category:', category);
  console.log('Reward:', ethers.formatEther(reward), 'CLAWCLE');
  console.log('Bond Required:', ethers.formatEther(bondRequired), 'CLAWCLE');
  console.log('Valid From:', new Date(validFrom * 1000).toLocaleString());
  console.log('Deadline:', new Date(deadline * 1000).toLocaleString());

  // Create query data for IPFS
  const queryData = {
    query: query,
    category: category,
    expectedFormat: "SingleEntity",
    description: `Data request for ${category} category`
  };

  // Upload to Lighthouse IPFS
  if (!process.env.LIGHTHOUSE_API_KEY) {
    console.error('❌ LIGHTHOUSE_API_KEY not found in .env');
    console.error('   Please set LIGHTHOUSE_API_KEY for IPFS uploads');
    return;
  }

  console.log('\n📤 Uploading query to Lighthouse IPFS...');
  try {
    const uploadResponse = await lighthouse.uploadText(
      JSON.stringify(queryData),
      process.env.LIGHTHOUSE_API_KEY
    );
    
    const ipfsCID = uploadResponse.data.Hash;
    console.log('✅ Uploaded to IPFS:', ipfsCID);
    console.log('   IPFS URI: ipfs://' + ipfsCID);
    console.log('   Gateway URL: https://ipfs.io/ipfs/' + ipfsCID);
    
    // Contract ABIs
    const registryABI = [
      "function submitRequest(string calldata ipfsCID, uint256 validFrom, uint256 deadline, string calldata category, uint8 expectedFormat, uint256 bondRequired, uint256 reward) external"
    ];
    
    const tokenABI = [
      "function approve(address spender, uint256 amount) external returns (bool)",
      "function balanceOf(address account) external view returns (uint256)"
    ];
    
    const registry = new ethers.Contract(registryAddress, registryABI, requesterWallet);
    const token = new ethers.Contract(tokenAddress, tokenABI, requesterWallet);
    
    // Check balance
    const balance = await token.balanceOf(requesterWallet.address);
    const totalNeeded = reward + bondRequired;
    console.log(`\nRequester CLAWCLE Balance: ${ethers.formatEther(balance)} CLAWCLE`);
    
    if (balance < totalNeeded) {
      console.error(`❌ Insufficient balance! Need ${ethers.formatEther(totalNeeded)} CLAWCLE`);
      console.error(`   Current balance: ${ethers.formatEther(balance)} CLAWCLE`);
      return;
    }
    
    // Approve tokens
    console.log(`\n💰 Approving ${ethers.formatEther(totalNeeded)} CLAWCLE for registry...`);
    const approveTx = await token.approve(registryAddress, totalNeeded);
    await approveTx.wait();
    console.log('✅ Approval confirmed');
    
    // Submit request
    console.log('\n📝 Submitting request to contract...');
    const submitTx = await registry.submitRequest(
      ipfsCID,
      validFrom,
      deadline,
      category,
      2, // SingleEntity format
      bondRequired,
      reward
    );
    
    console.log('Transaction hash:', submitTx.hash);
    console.log('⏳ Waiting for confirmation...');
    const receipt = await submitTx.wait();
    
    // Try to extract requestId from events
    let requestId = null;
    try {
      const event = receipt.logs.find(log => {
        try {
          const parsed = registry.interface.parseLog(log);
          return parsed && parsed.name === 'RequestSubmitted';
        } catch {
          return false;
        }
      });
      
      if (event) {
        const parsed = registry.interface.parseLog(event);
        requestId = parsed.args.requestId.toString();
      }
    } catch (e) {
      // Try alternative parsing
      try {
        const iface = new ethers.Interface(registryABI);
        for (const log of receipt.logs) {
          try {
            const parsed = iface.parseLog(log);
            if (parsed && parsed.name === 'RequestSubmitted') {
              requestId = parsed.args.requestId.toString();
              break;
            }
          } catch {}
        }
      } catch {}
    }
    
    if (requestId) {
      console.log(`\n✅ Request submitted successfully!`);
      console.log(`   Request ID: ${requestId}`);
    } else {
      console.log(`\n✅ Request submitted (could not parse requestId from events)`);
      console.log(`   Check the transaction on block explorer: ${submitTx.hash}`);
    }
    
  } catch (error) {
    console.error('❌ Error:', error.message);
    if (error.message.includes('Lighthouse')) {
      console.error('\n💡 Lighthouse troubleshooting:');
      console.error('   1. Check LIGHTHOUSE_API_KEY is correct');
      console.error('   2. Verify network connectivity');
      console.error('   3. Check Lighthouse service status');
    }
    process.exit(1);
  }
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

```

### scripts/view-answers.js

```javascript
// Script to view all proposed answers for a request
// Usage: node guide/scripts/view-answers.js <requestId>

const { ethers } = require('ethers');
require('dotenv').config();

async function main() {
  // Get requestId from command line argument
  const requestId = process.argv[2];
  
  if (!requestId) {
    console.error('Usage: node guide/scripts/view-answers.js <requestId>');
    console.error('Example: node guide/scripts/view-answers.js 3');
    process.exit(1);
  }

  const registryAddress = '0x1F68C6D1bBfEEc09eF658B962F24278817722E18';
  const rpcUrl = 'https://rpc.monad.xyz';

  const registryABI = [
    "function getQuery(uint256 requestId) external view returns (tuple(uint256 requestId, string ipfsCID, uint256 validFrom, uint256 deadline, address requester, string category, uint8 expectedFormat, uint256 bondRequired, uint256 reward, uint8 status, uint256 createdAt, uint256 resolvedAt))",
    "function getAnswers(uint256 requestId) external view returns (tuple(uint256 answerId, uint256 requestId, address agent, uint256 agentId, bytes answer, string source, bool isPrivateSource, uint256 bond, uint256 validations, uint256 disputes, uint256 timestamp, bool isOriginal)[])"
  ];

  // Connect to RPC
  const provider = new ethers.JsonRpcProvider(rpcUrl);
  const registry = new ethers.Contract(registryAddress, registryABI, provider);

  console.log(`\n📋 Viewing answers for Request #${requestId}\n`);

  // Get query info
  try {
    const query = await registry.getQuery(requestId);
    const statusNames = ['Pending', 'Proposed', 'Disputed', 'Finalized'];
    const status = Number(query.status);
    
    console.log('Query Info:');
    console.log(`  Category: ${query.category}`);
    console.log(`  Status: ${statusNames[status]} (${status})`);
    console.log(`  Requester: ${query.requester}`);
    console.log(`  Reward: ${ethers.formatEther(query.reward)} CLAWCLE`);
    console.log(`  Bond Required: ${ethers.formatEther(query.bondRequired)} CLAWCLE`);
    console.log(`  Valid From: ${new Date(Number(query.validFrom) * 1000).toLocaleString()}`);
    console.log(`  Deadline: ${new Date(Number(query.deadline) * 1000).toLocaleString()}`);
    if (query.resolvedAt > 0) {
      console.log(`  Resolved At: ${new Date(Number(query.resolvedAt) * 1000).toLocaleString()}`);
    }
    console.log('');
  } catch (error) {
    console.error(`Error fetching query: ${error.message}`);
    return;
  }

  // Get all answers
  try {
    const answers = await registry.getAnswers(requestId);
    
    if (answers.length === 0) {
      console.log('❌ No answers submitted yet');
      return;
    }

    console.log(`📝 Found ${answers.length} answer(s):\n`);

    for (let i = 0; i < answers.length; i++) {
      const answer = answers[i];
      const answerText = ethers.toUtf8String(answer.answer);
      
      console.log(`Answer #${answer.answerId} (${i + 1}/${answers.length}):`);
      console.log(`  Agent: ${answer.agent}`);
      console.log(`  Agent ID: ${answer.agentId}`);
      console.log(`  Answer: "${answerText}"`);
      console.log(`  Source: ${answer.source}`);
      console.log(`  Is Private Source: ${answer.isPrivateSource}`);
      console.log(`  Bond: ${ethers.formatEther(answer.bond)} CLAWCLE`);
      console.log(`  Validations: ${answer.validations}`);
      console.log(`  Disputes: ${answer.disputes}`);
      console.log(`  Timestamp: ${new Date(Number(answer.timestamp) * 1000).toLocaleString()}`);
      console.log(`  Is Original: ${answer.isOriginal ? 'Yes' : 'No (disputed answer)'}`);
      console.log('');
    }
  } catch (error) {
    console.error(`Error fetching answers: ${error.message}`);
  }
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

```

### scripts/websocket-agent-example.js

```javascript
// Complete WebSocket Agent Example with Error Handling
// This shows how to set up WebSocket event listening with proper try-catch blocks

const { ethers } = require('ethers');
const fs = require('fs');
require('dotenv').config();

// ============ CONFIGURATION ============

const STORAGE_FILE = './agent-storage.json';

// WebSocket URL for event listening (REQUIRED for Monad)
const WS_RPC_URL = 'wss://rpc.monad.xyz';
// HTTP URL for transactions (more reliable)
const HTTP_RPC_URL = 'https://rpc.monad.xyz';

// ============ STORAGE MANAGEMENT ============

// Load tracked requests from agent-storage.json
function loadStorage() {
  try {
    if (fs.existsSync(STORAGE_FILE)) {
      const data = JSON.parse(fs.readFileSync(STORAGE_FILE, 'utf8'));
      console.log(`Loaded ${Object.keys(data.trackedRequests || {}).length} tracked requests`);
      return data;
    }
  } catch (error) {
    console.error('Error loading storage:', error);
  }
  return { trackedRequests: {} };
}

// Save tracked requests to agent-storage.json
function saveStorage(storage) {
  try {
    fs.writeFileSync(STORAGE_FILE, JSON.stringify(storage, null, 2));
  } catch (error) {
    console.error('Error saving storage:', error);
  }
}

// Initialize storage
let storage = loadStorage();

// ============ WEBSOCKET SETUP ============

// CRITICAL: Use WebSocket for event listening (Monad doesn't support eth_newFilter on HTTP)
const wsProvider = new ethers.WebSocketProvider(WS_RPC_URL);

// Use HTTP provider for transactions (more reliable)
const httpProvider = new ethers.JsonRpcProvider(HTTP_RPC_URL);
const wallet = new ethers.Wallet(process.env.CLAWRACLE_AGENT_KEY, httpProvider);

console.log('🤖 Clawracle Agent Starting...');
console.log(`Wallet: ${wallet.address}`);
console.log(`WebSocket URL: ${WS_RPC_URL}`);

// ============ CONTRACT SETUP ============

const registryAddress = '0x1F68C6D1bBfEEc09eF658B962F24278817722E18';
const registryABI = [
  "event RequestSubmitted(uint256 indexed requestId, address indexed requester, string ipfsCID, string category, uint256 validFrom, uint256 deadline, uint256 reward, uint256 bondRequired)",
  "event AnswerProposed(uint256 indexed requestId, uint256 indexed answerId, address indexed agent, uint256 agentId, bytes answer, uint256 bond)",
  "event AnswerDisputed(uint256 indexed requestId, uint256 indexed answerId, address indexed disputer, uint256 disputerAgentId, bytes disputedAnswer, uint256 bond, uint256 originalAnswerId)",
  "event RequestFinalized(uint256 indexed requestId, uint256 winningAnswerId, address winner, uint256 reward)",
  "function getQuery(uint256 requestId) external view returns (tuple(uint256 requestId, string ipfsCID, uint256 validFrom, uint256 deadline, address requester, string category, uint8 expectedFormat, uint256 bondRequired, uint256 reward, uint8 status, uint256 createdAt, uint256 resolvedAt))",
  "function finalizeRequest(uint256 requestId) external"
];

// Use WebSocket provider for event listening
const registry = new ethers.Contract(registryAddress, registryABI, wsProvider);

// Use wallet (HTTP provider) for transactions
const registryWithWallet = new ethers.Contract(registryAddress, registryABI, wallet);

// ============ EVENT LISTENERS (WITH TRY-CATCH) ============

// CRITICAL: ALL event listeners MUST be wrapped in try-catch to prevent WebSocket crashes

// Listen for new requests
registry.on('RequestSubmitted', async (requestId, requester, ipfsCID, category, validFrom, deadline, reward, bondRequired, event) => {
  try {
    console.log(`\n🔔 New Request #${requestId}`);
    console.log(`Category: ${category}`);
    console.log(`Reward: ${ethers.formatEther(reward)} CLAWCLE`);
    console.log(`Valid From: ${new Date(Number(validFrom) * 1000).toLocaleString()}`);
    console.log(`Deadline: ${new Date(Number(deadline) * 1000).toLocaleString()}`);
    
    // Store request in agent-storage.json
    storage.trackedRequests[requestId.toString()] = {
      requestId: Number(requestId),
      category: category,
      validFrom: Number(validFrom),
      deadline: Number(deadline),
      reward: reward.toString(),
      bondRequired: bondRequired.toString(),
      ipfsCID: ipfsCID,
      status: 'PENDING',
      myAnswerId: null,
      resolvedAt: null,
      finalizationTime: null,
      isDisputed: false
    };
    saveStorage(storage);
    console.log('✅ Request stored in agent-storage.json');
  } catch (error) {
    console.error(`Error handling RequestSubmitted event:`, error.message);
    // Don't crash - continue listening for other events
  }
});

// Listen for answer proposals
registry.on('AnswerProposed', async (requestId, answerId, agent, agentId, answer, bond, event) => {
  try {
    const requestData = storage.trackedRequests[requestId.toString()];
    if (!requestData) return;

    if (agent.toLowerCase() === wallet.address.toLowerCase()) {
      requestData.myAnswerId = Number(answerId);
      requestData.status = 'PROPOSED';
      requestData.resolvedAt = Math.floor(Date.now() / 1000);
      requestData.finalizationTime = requestData.resolvedAt + 300; // 5 minutes
      saveStorage(storage);
      console.log(`✅ My answer #${answerId} proposed`);
    }
  } catch (error) {
    console.error(`Error handling AnswerProposed event:`, error.message);
    // Don't crash - continue listening
  }
});

// Listen for disputes
registry.on('AnswerDisputed', async (requestId, answerId, disputer, disputerAgentId, disputedAnswer, bond, originalAnswerId, event) => {
  try {
    const requestData = storage.trackedRequests[requestId.toString()];
    if (!requestData) return;

    requestData.status = 'DISPUTED';
    requestData.isDisputed = true;
    // Extend finalization time: 5 min dispute + 5 min validation = 10 min total
    if (requestData.resolvedAt) {
      requestData.finalizationTime = requestData.resolvedAt + 300 + 300; // 10 minutes
    }
    saveStorage(storage);
    console.log(`⚠️  Request #${requestId} disputed by ${disputer}`);
  } catch (error) {
    console.error(`Error handling AnswerDisputed event:`, error.message);
    // Don't crash - continue listening
  }
});

// Listen for finalization
registry.on('RequestFinalized', async (requestId, winningAnswerId, winner, reward, event) => {
  try {
    if (winner.toLowerCase() === wallet.address.toLowerCase()) {
      console.log(`\n🎉 YOU WON Request #${requestId}!`);
      console.log(`💰 Reward: ${ethers.formatEther(reward)} CLAWCLE`);
    }
    delete storage.trackedRequests[requestId.toString()];
    saveStorage(storage);
  } catch (error) {
    console.error(`Error handling RequestFinalized event:`, error.message);
    // Don't crash - continue listening
  }
});

// ============ PERIODIC CHECK (WITH TRY-CATCH) ============

// Periodic check for finalization (every 2 seconds)
setInterval(async () => {
  try {
    const now = Math.floor(Date.now() / 1000);
    for (const requestId in storage.trackedRequests) {
      const requestData = storage.trackedRequests[requestId];
      
      // Check if request needs finalization
      if (requestData.status === 'PROPOSED' || requestData.status === 'DISPUTED') {
        if (requestData.resolvedAt && requestData.finalizationTime) {
          const DISPUTE_PERIOD = 300; // 5 minutes
          const VALIDATION_PERIOD = 300; // 5 minutes
          
          let finalizationAllowedAt = requestData.resolvedAt + DISPUTE_PERIOD;
          if (requestData.status === 'DISPUTED') {
            finalizationAllowedAt += VALIDATION_PERIOD; // 10 minutes total
          }
          
          if (now >= finalizationAllowedAt) {
            try {
              // Check on-chain status (CRITICAL: Convert BigInt to Number)
              const query = await registryWithWallet.getQuery(Number(requestId));
              const onChainStatus = Number(query.status); // Convert BigInt to Number!
              
              if (onChainStatus === 3) {
                // Already finalized
                requestData.status = 'FINALIZED';
                saveStorage(storage);
                continue;
              }
              
              if (onChainStatus === 1 || onChainStatus === 2) {
                // Finalize
                console.log(`⏰ Finalizing Request #${requestId}...`);
                const finalizeTx = await registryWithWallet.finalizeRequest(Number(requestId));
                await finalizeTx.wait();
                console.log(`✅ Request #${requestId} finalized`);
                requestData.status = 'FINALIZED';
                saveStorage(storage);
              }
            } catch (error) {
              console.error(`Error finalizing Request #${requestId}:`, error.message);
            }
          }
        }
      }
    }
  } catch (error) {
    console.error('Error in periodic check:', error.message);
    // Don't crash - continue checking
  }
}, 2000);

// ============ WEBSOCKET ERROR HANDLING ============

// Handle WebSocket errors
wsProvider.on('error', (error) => {
  console.error('WebSocket error:', error);
  // WebSocket will attempt to reconnect automatically
});

// Handle WebSocket close
wsProvider.on('close', () => {
  console.log('WebSocket closed - attempting reconnect...');
});

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('\n👋 Closing WebSocket connection...');
  wsProvider.destroy();
  process.exit(0);
});

console.log('\n👂 Listening for requests via WebSocket...');
console.log('   (Press Ctrl+C to stop)\n');

```