docs: add Arc MCP Server example for Claude Code integration

docs/deploying-smart-contracts-with-foundry.md

@@ -0,0 +1,41 @@
+# Deploying Smart Contracts on Arc Testnet with Foundry
+
+This guide walks through writing, testing, and deploying Solidity smart contracts on Arc Testnet using Foundry.
+
+## Network Configuration
+
+| Parameter | Value |
+|-----------|-------|
+| RPC URL | https://rpc.testnet.arc.network |
+| Chain ID | 5042002 |
+| Gas Token | USDC |
+| Explorer | https://testnet.arcscan.app |
+
+## Installing Foundry
+
+```bash
+curl -L https://foundry.paradigm.xyz | bash
+source ~/.bashrc
+foundryup
+```
+
+## Creating a Project
+
+```bash
+forge init my-arc-project && cd my-arc-project
+```
+
+## Deploying to Arc Testnet
+
+```bash
+forge create src/HelloArc.sol:HelloArc \
+  --rpc-url https://rpc.testnet.arc.network \
+  --private-key YOUR_PRIVATE_KEY \
+  --broadcast
+```
+
+## Resources
+
+- [Arc Docs](https://docs.arc.network)
+- [Foundry Book](https://book.getfoundry.sh)
+- [Explorer](https://testnet.arcscan.app)

docs/examples/arc-intelligence-dashboard.md

@@ -0,0 +1,56 @@
+# Arc Intelligence Dashboard
+
+A real-time Next.js dashboard for Arc Testnet that visualizes X402 payments, ERC-8004 agent identity, ERC-8183 jobs, and deployed contracts.
+
+## Live Demo
+
+https://arc-intelligence-dashboard.vercel.app
+
+## Features
+
+- Real-time USDC balance (refreshed every 10 seconds)
+- Live Arc Testnet block number
+- Transaction count for main agent address
+- Agentic Stack status (X402, ERC-8004, ERC-8183)
+- 15 deployed Solidity contracts with explorer links
+- circlefin/arc-node contribution history
+
+## Tech Stack
+
+- Next.js 16 with TypeScript
+- Tailwind CSS
+- viem for Arc Testnet RPC
+- Deployed on Vercel
+
+## Quick Start
+
+npm install
+npm run dev
+
+## Arc Testnet Configuration
+
+const arcTestnet = {
+  id: 5042002,
+  name: "Arc Testnet",
+  rpcUrls: { default: { http: ["https://rpc.testnet.arc.network"] } },
+  blockExplorers: { default: { name: "Arcscan", url: "https://testnet.arcscan.app" } },
+};
+
+## Data Fetching
+
+The dashboard uses viem createPublicClient to fetch:
+- ERC-20 USDC balance via balanceOf()
+- Latest block number via getBlockNumber()
+- Transaction count via getTransactionCount()
+
+All three queries run concurrently with Promise.all and refresh every 10 seconds.
+
+## GitHub Repository
+
+https://github.com/consumeobeydie/arc-intelligence-dashboard
+
+## Resources
+
+- Arc Docs: https://docs.arc.network
+- Arc Testnet Explorer: https://testnet.arcscan.app
+- viem: https://viem.sh

docs/examples/arc-mcp-server.md

@@ -0,0 +1,62 @@
+# Arc MCP Server
+
+A Model Context Protocol (MCP) server that gives AI tools like Claude Code direct access to Arc Testnet blockchain data.
+
+## What is MCP?
+
+Model Context Protocol (MCP) is an open standard that lets AI tools discover and use external tools and data sources. With this Arc MCP server, Claude Code can query Arc Testnet directly during conversations.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| get_balance | Get USDC balance for any address |
+| get_transaction | Get transaction details by hash |
+| get_block | Get latest block information |
+| get_tx_count | Get transaction count for an address |
+| get_agent_info | Get ERC-8004 agent information |
+| get_job_status | Get ERC-8183 job status |
+| get_network_info | Get network info and contract addresses |
+
+## Installation
+
+git clone https://github.com/consumeobeydie/arc-mcp-server.git
+cd arc-mcp-server
+npm install
+
+## Add to Claude Code
+
+claude mcp add --transport stdio arc-testnet node /path/to/arc-mcp-server/src/index.js
+
+## Example Usage
+
+Once added, ask Claude Code:
+- "Get the USDC balance of 0x54b4B44749a95070560509B6Ec0be501665CcF63"
+- "Get Arc Testnet network info"
+- "Get ERC-8004 agent info"
+- "Get status of job 110935"
+
+## Example Output
+
+Claude Code returns structured data like:
+
+Network: Arc Testnet
+Chain ID: 5042002
+Gas Token: USDC
+Finality: Sub-second deterministic
+Latest Block: 46,336,076
+
+Contracts:
+- USDC: 0x3600000000000000000000000000000000000000
+- IdentityRegistry: 0x8004A818BFB912233c491871b3d84c89A494BD9e
+- AgenticCommerce: 0x0747EEf0706327138c69792bF28Cd525089e4583
+
+## GitHub Repository
+
+https://github.com/consumeobeydie/arc-mcp-server
+
+## Resources
+
+- Arc MCP Docs: https://docs.arc.io/ai/mcp
+- Model Context Protocol: https://modelcontextprotocol.io
+- Arc Testnet Explorer: https://testnet.arcscan.app

docs/examples/erc8004-agent-registration.md

@@ -0,0 +1,180 @@
+# ERC-8004 AI Agent Registration on Arc Testnet
+
+This example shows how to register an AI agent with onchain identity, build reputation, and verify credentials using the ERC-8004 standard on Arc Testnet with Circle Developer-Controlled Wallets.
+
+## Overview
+
+ERC-8004 provides onchain identity and reputation for AI agents. Combined with x402 payments, it enables fully autonomous agents that can prove their identity, build trust, and transact on Arc Testnet.
+
+## ERC-8004 Contracts on Arc Testnet
+
+| Contract | Address |
+|----------|---------|
+| IdentityRegistry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
+| ReputationRegistry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
+| ValidationRegistry | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` |
+
+## Prerequisites
+
+- Node.js v22+
+- Circle Developer Console account with API key
+- Entity Secret registered in Circle Console
+
+## Installation
+
+```bash
+mkdir arc-erc8004-agent && cd arc-erc8004-agent
+npm init -y
+npm install @circle-fin/developer-controlled-wallets viem dotenv
+```
+
+## Environment Setup
+
+```bash
+# .env
+CIRCLE_API_KEY=your_circle_api_key
+CIRCLE_ENTITY_SECRET=your_entity_secret
+```
+
+## Complete Implementation
+
+```javascript
+const { initiateDeveloperControlledWalletsClient } = require("@circle-fin/developer-controlled-wallets");
+const { createPublicClient, http, parseAbiItem, keccak256, toHex } = require("viem");
+require("dotenv").config();
+
+const arcTestnet = {
+  id: 5042002,
+  name: "Arc Testnet",
+  nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 18 },
+  rpcUrls: { default: { http: ["https://rpc.testnet.arc.network"] } },
+  blockExplorers: { default: { name: "Arcscan", url: "https://testnet.arcscan.app" } },
+  testnet: true,
+};
+
+const IDENTITY_REGISTRY = "0x8004A818BFB912233c491871b3d84c89A494BD9e";
+const REPUTATION_REGISTRY = "0x8004B663056A597Dffe9eCcC1965A193B7388713";
+const VALIDATION_REGISTRY = "0x8004Cb1BF31DAf7788923b405b754f57acEB4272";
+const METADATA_URI = "ipfs://bafkreibdi6623n3xpf7ymk62ckb4bo75o3qemwkpfvp5i25j66itxvsoei";
+
+const circleClient = initiateDeveloperControlledWalletsClient({
+  apiKey: process.env.CIRCLE_API_KEY,
+  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
+});
+
+const publicClient = createPublicClient({
+  chain: arcTestnet,
+  transport: http(),
+});
+
+async function waitForTransaction(txId, label) {
+  for (let i = 0; i < 30; i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const { data } = await circleClient.getTransaction({ id: txId });
+    if (data?.transaction?.state === "COMPLETE") return data.transaction.txHash;
+    if (data?.transaction?.state === "FAILED") throw new Error(label + " failed");
+  }
+  throw new Error(label + " timed out");
+}
+
+async function main() {
+  // Step 1: Create two wallets (owner + validator)
+  const walletSet = await circleClient.createWalletSet({ name: "ERC8004 Agent Wallets" });
+  const walletsResponse = await circleClient.createWallets({
+    blockchains: ["ARC-TESTNET"],
+    count: 2,
+    walletSetId: walletSet.data?.walletSet?.id,
+    accountType: "SCA",
+  });
+
+  const ownerWallet = walletsResponse.data?.wallets?.[0];
+  const validatorWallet = walletsResponse.data?.wallets?.[1];
+  console.log("Owner:    ", ownerWallet.address);
+  console.log("Validator:", validatorWallet.address);
+
+  // Step 2: Register agent identity
+  const registerTx = await circleClient.createContractExecutionTransaction({
+    walletAddress: ownerWallet.address,
+    blockchain: "ARC-TESTNET",
+    contractAddress: IDENTITY_REGISTRY,
+    abiFunctionSignature: "register(string)",
+    abiParameters: [METADATA_URI],
+    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
+  });
+  const registerHash = await waitForTransaction(registerTx.data?.id, "registration");
+  console.log("Registered:", "https://testnet.arcscan.app/tx/" + registerHash);
+
+  // Step 3: Get agent ID from Transfer event
+  const latestBlock = await publicClient.getBlockNumber();
+  const fromBlock = latestBlock > 10000n ? latestBlock - 10000n : 0n;
+  const transferLogs = await publicClient.getLogs({
+    address: IDENTITY_REGISTRY,
+    event: parseAbiItem("event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)"),
+    args: { to: ownerWallet.address },
+    fromBlock,
+    toBlock: latestBlock,
+  });
+  const agentId = transferLogs[transferLogs.length - 1].args.tokenId.toString();
+  console.log("Agent ID:", agentId);
+
+  // Step 4: Record reputation (validator wallet)
+  const tag = "x402_payment_successful";
+  const feedbackHash = keccak256(toHex(tag));
+  const reputationTx = await circleClient.createContractExecutionTransaction({
+    walletAddress: validatorWallet.address,
+    blockchain: "ARC-TESTNET",
+    contractAddress: REPUTATION_REGISTRY,
+    abiFunctionSignature: "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)",
+    abiParameters: [agentId, "95", "0", tag, "", "", "", feedbackHash],
+    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
+  });
+  await waitForTransaction(reputationTx.data?.id, "reputation");
+
+  // Step 5: Request + respond to validation
+  const requestHash = keccak256(toHex("validation_request_" + agentId));
+  const validationReqTx = await circleClient.createContractExecutionTransaction({
+    walletAddress: ownerWallet.address,
+    blockchain: "ARC-TESTNET",
+    contractAddress: VALIDATION_REGISTRY,
+    abiFunctionSignature: "validationRequest(address,uint256,string,bytes32)",
+    abiParameters: [validatorWallet.address, agentId, "ipfs://bafkreiexample", requestHash],
+    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
+  });
+  await waitForTransaction(validationReqTx.data?.id, "validation request");
+
+  const validationResTx = await circleClient.createContractExecutionTransaction({
+    walletAddress: validatorWallet.address,
+    blockchain: "ARC-TESTNET",
+    contractAddress: VALIDATION_REGISTRY,
+    abiFunctionSignature: "validationResponse(bytes32,uint8,string,bytes32,string)",
+    abiParameters: [requestHash, "100", "", "0x" + "0".repeat(64), "agent_verified"],
+    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
+  });
+  await waitForTransaction(validationResTx.data?.id, "validation response");
+
+  console.log("Agent registration complete!");
+  console.log("Explorer:", "https://testnet.arcscan.app/address/" + ownerWallet.address);
+}
+
+main().catch(console.error);
+```
+
+## Expected Output
+## How It Works
+
+1. **Two wallets** — owner registers the agent, validator records reputation (per ERC-8004, owners cannot self-attest)
+2. **Identity registration** — mints an ERC-721 NFT on IdentityRegistry, giving the agent a unique onchain ID
+3. **Reputation** — validator records feedback with a score and tag on ReputationRegistry
+4. **Validation** — two-step request/response flow on ValidationRegistry proves the agent meets criteria
+
+## Integration with X402
+
+This ERC-8004 identity can be combined with x402 payments for a complete agentic flow:
+See the full working example: [github.com/consumeobeydie/arc-agent-api](https://github.com/consumeobeydie/arc-agent-api)
+
+## Resources
+
+- [Arc ERC-8004 Docs](https://docs.arc.network/arc/tutorials/register-your-first-ai-agent)
+- [Arc Testnet Explorer](https://testnet.arcscan.app)
+- [Circle Developer Console](https://console.circle.com)
+- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004)

docs/examples/erc8183-job-lifecycle.md

@@ -0,0 +1,5 @@
+# ERC-8183 Job Lifecycle on Arc Testnet
+
+Job ID: 110860 - Status: Completed - Budget: 5 USDC
+
+Full example: https://github.com/consumeobeydie/arc-agent-api