Kxcoscan AI Tools

A production-ready AI tool server that wraps the Kxcoscan 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

API Reference

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

GET /api/balance

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

GET /api/transactions

GET /api/token-transfers

GET /api/tx

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

GET /api/contract

Returns abi, sourceCode, contractName, isVerified.

GET /api/logs

GET /api/token-info

Returns name, symbol, decimals, totalSupply, totalSupplyFormatted.

GET /api/wallet-summary ⭐ AI-optimised

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

MCP Server

The /api/mcp endpoint implements Model Context Protocol over stateless HTTP.

Available tools

Claude Desktop configuration

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

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

Manual JSON-RPC call

# 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)

# 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

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

Build check

npm run build
npm run type-check

How AI agents call these tools

Option 1 — Direct HTTP (any agent framework)

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)

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 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

License

MIT