README.md
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.v
Tools 8
wallet_balanceGet native KXCO balancewallet_transactionsList transactionstoken_transfersList token transferswallet_summaryFull wallet overviewtransaction_infoTx status by hashcontract_abiContract ABI + sourcetoken_infoToken metadataevent_logsContract event logsTry it
→What is the current KXCO balance for wallet 0xABC...?
→Summarize the recent activity for wallet 0xABC...
→Check the status of transaction 0x...
→Get the token metadata for contract address 0x...
→List the last 10 transactions for wallet 0x...