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

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

{
  "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 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:

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

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