# Kxcoscan AI Tools

A production-ready AI tool server that wraps the [Kxcoscan](https://kxcoscan.com) blockchain explorer API into clean, structured endpoints that any AI agent (Claude, GPT-4, etc.) can call directly.

Built with **Next.js 14**, deployed on **Vercel**, and includes an **MCP (Model Context Protocol)** server.

---

## Architecture

```
kxcoscan-ai-tools/
├── app/
│   ├── api/
│   │   ├── balance/          GET  /api/balance
│   │   ├── transactions/     GET  /api/transactions
│   │   ├── token-transfers/  GET  /api/token-transfers
│   │   ├── tx/               GET  /api/tx
│   │   ├── contract/         GET  /api/contract
│   │   ├── logs/             GET  /api/logs
│   │   ├── token-info/       GET  /api/token-info
│   │   ├── wallet-summary/   GET  /api/wallet-summary
│   │   └── mcp/              POST /api/mcp  (MCP JSON-RPC)
│   ├── page.tsx              Interactive frontend dashboard
│   └── layout.tsx
├── components/
│   ├── ApiTester.tsx         Interactive tool tester (client)
│   └── JsonDisplay.tsx       Syntax-highlighted JSON viewer
├── lib/
│   ├── kxcoscan.ts           Core API wrapper + utilities
│   └── cache.ts              Edge cache response helpers
├── mcp/
│   └── server.ts             MCP tool definitions
├── config/
│   └── modules.json          Supported modules & AI tool manifest
├── types/
│   └── explorer.ts           Full TypeScript types
└── vercel.json
```

### Key design decisions

| Concern | Solution |
|---|---|
| No API key needed | Open requests with a descriptive `User-Agent` |
| Parallel fetches | `Promise.allSettled` — one failed upstream call won't break the response |
| AI-friendly output | Wei → KXCO conversion, ISO timestamps, human-readable status strings |
| Caching | Vercel edge `Cache-Control: s-maxage` headers (10s–1hr by tier) |
| MCP | Stateless JSON-RPC 2.0 handler — no persistent process needed on Vercel |
| CORS | `*` on all `/api/*` routes so any AI agent can call from any origin |

---

## API Reference

All endpoints return JSON. All require a `GET` request with query parameters.

### `GET /api/balance`
| Param | Required | Description |
|---|---|---|
| `address` | ✅ | Wallet address `0x...` |

```json
{
  "wallet": "0xABC...",
  "balance": "102.345678",
  "symbol": "KXCO",
  "balanceRaw": "102345678000000000000"
}
```

---

### `GET /api/transactions`
| Param | Required | Default | Description |
|---|---|---|---|
| `address` | ✅ | — | Wallet address |
| `page` | | 1 | Page number |
| `offset` | | 10 | Results per page (max 100) |
| `sort` | | desc | `asc` or `desc` |
| `startblock` | | — | Filter from block |
| `endblock` | | — | Filter to block |

---

### `GET /api/token-transfers`
| Param | Required | Description |
|---|---|---|
| `address` | ✅ | Wallet address |
| `contractaddress` | | Filter to a specific token |
| `page` | | Page number |
| `offset` | | Results per page |

---

### `GET /api/tx`
| Param | Required | Description |
|---|---|---|
| `txhash` | ✅ | Transaction hash `0x...` (64 hex chars) |

Returns `status: "success" | "failed" | "pending"`.

---

### `GET /api/contract`
| Param | Required | Description |
|---|---|---|
| `address` | ✅ | Contract address |

Returns `abi`, `sourceCode`, `contractName`, `isVerified`.

---

### `GET /api/logs`
| Param | Required | Description |
|---|---|---|
| `address` | ✅ | Contract address |
| `fromBlock` | | Start block (default: 0) |
| `toBlock` | | End block (default: latest) |
| `topic0` | | Event signature hash filter |

---

### `GET /api/token-info`
| Param | Required | Description |
|---|---|---|
| `contractaddress` | ✅ | Token contract address |

Returns `name`, `symbol`, `decimals`, `totalSupply`, `totalSupplyFormatted`.

---

### `GET /api/wallet-summary` ⭐ AI-optimised
| Param | Required | Description |
|---|---|---|
| `address` | ✅ | Wallet address |

Returns balance + last 5 transactions + last 5 token transfers + a natural-language `summary` string.

---

## MCP Server

The `/api/mcp` endpoint implements [Model Context Protocol](https://spec.modelcontextprotocol.io/) over stateless HTTP.

### Available tools

| Tool | Description |
|---|---|
| `wallet_balance` | Get native KXCO balance |
| `wallet_transactions` | List transactions |
| `token_transfers` | List token transfers |
| `wallet_summary` | Full wallet overview |
| `transaction_info` | Tx status by hash |
| `contract_abi` | Contract ABI + source |
| `token_info` | Token metadata |
| `event_logs` | Contract event logs |

### Claude Desktop configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kxcoscan": {
      "url": "https://your-app.vercel.app/api/mcp",
      "transport": "http"
    }
  }
}
```

### Manual JSON-RPC call

```bash
# List tools
curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 1,
    "params": {
      "name": "wallet_summary",
      "arguments": { "address": "0xYOUR_ADDRESS" }
    }
  }'
```

---

## Deployment

### Deploy to Vercel (recommended)

```bash
# 1. Install Vercel CLI
npm i -g vercel

# 2. Clone and install
git clone <this-repo>
cd kxcoscan-ai-tools
npm install

# 3. Deploy
vercel

# Follow prompts — no environment variables required.
# The API is open (no key needed).
```

### Local development

```bash
npm install
npm run dev
# → http://localhost:3000
```

### Build check

```bash
npm run build
npm run type-check
```

---

## How AI agents call these tools

### Option 1 — Direct HTTP (any agent framework)

```python
import httpx

BASE = "https://your-app.vercel.app"

# Get wallet summary
r = httpx.get(f"{BASE}/api/wallet-summary", params={"address": "0xABC..."})
data = r.json()
print(data["summary"])  # Natural language overview
```

### Option 2 — Claude tool use (Anthropic SDK)

```python
import anthropic, httpx

client = anthropic.Anthropic()

def wallet_summary(address: str) -> dict:
    return httpx.get(
        "https://your-app.vercel.app/api/wallet-summary",
        params={"address": address}
    ).json()

tools = [{
    "name": "wallet_summary",
    "description": "Get a comprehensive overview of a KXCO wallet",
    "input_schema": {
        "type": "object",
        "properties": {
            "address": {"type": "string", "description": "Wallet address 0x..."}
        },
        "required": ["address"]
    }
}]

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{
        "role": "user",
        "content": "Analyse wallet 0xABC..."
    }]
)

# Handle tool_use blocks
for block in response.content:
    if block.type == "tool_use" and block.name == "wallet_summary":
        result = wallet_summary(block.input["address"])
        # Continue conversation with result...
```

### Option 3 — MCP (Claude Desktop / Claude Code)

See [MCP Server](#mcp-server) section above.

---

## Adding new tools

1. Add the new module/action to `config/modules.json`
2. Create `app/api/<tool-name>/route.ts` following the existing pattern
3. Add the tool definition to `mcp/server.ts`
4. Add the tool card to `components/ApiTester.tsx`

The `config/modules.json` file serves as the canonical manifest — you can also parse it programmatically to auto-discover available tools.

---

## Caching tiers

| Tier | `s-maxage` | `stale-while-revalidate` | Used for |
|---|---|---|---|
| `realtime` | 10s | 30s | Live data |
| `short` | 60s | 120s | Balances, transactions |
| `medium` | 5min | 10min | Token metadata |
| `long` | 1hr | 2hr | Contract ABIs (immutable) |

---

## License

MIT