@nirholas/bnbchain-mcp 1.0.0

package/docs/content/api/tools/tokens-tools.md

@@ -0,0 +1,350 @@
+# Token Tools
+
+Tools for ERC-20 token operations including transfers, approvals, and token information.
+
+---
+
+## Overview
+
+Token tools enable interaction with ERC-20 tokens across supported EVM networks.
+
+| Tool | Description |
+|------|-------------|
+| `tokens_get_token_info` | Get token metadata (name, symbol, decimals) |
+| `tokens_get_token_balance` | Get token balance for an address |
+| `tokens_get_token_allowance` | Check spending allowance |
+| `tokens_approve` | Approve token spending |
+| `tokens_transfer` | Transfer tokens to address |
+| `tokens_get_top_holders` | Get top token holders |
+| `tokens_get_token_price` | Get token price in USD |
+
+---
+
+## tokens_get_token_info
+
+Get metadata for an ERC-20 token.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "name": "USD Coin",
+  "symbol": "USDC",
+  "decimals": 6,
+  "totalSupply": "26000000000000000",
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Get info for USDC token on Ethereum
+```
+
+---
+
+## tokens_get_token_balance
+
+Get token balance for a specific address.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `walletAddress` | string | Yes | Wallet address to check |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "token": {
+    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    "symbol": "USDC",
+    "decimals": 6
+  },
+  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "balance": "5000.00",
+  "balanceRaw": "5000000000",
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Check USDC balance for 0x742d35... on Arbitrum
+```
+
+---
+
+## tokens_get_token_allowance
+
+Check how much of a token a spender is allowed to use.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `ownerAddress` | string | Yes | Token owner address |
+| `spenderAddress` | string | Yes | Spender address (e.g., DEX router) |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "spender": "0x1111111254EEB25477B68fb85Ed929f73A960582",
+  "allowance": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
+  "allowanceFormatted": "unlimited",
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Check my USDC allowance for 1inch router
+```
+
+---
+
+## tokens_approve
+
+Approve a spender to use tokens on your behalf.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `spenderAddress` | string | Yes | Address to approve |
+| `amount` | string | Yes | Amount to approve (or "unlimited") |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "success": true,
+  "transactionHash": "0xabc123...",
+  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "spender": "0x1111111254EEB25477B68fb85Ed929f73A960582",
+  "amount": "1000000000",
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Approve 1000 USDC for the 1inch router on Arbitrum
+```
+
+### Security Note
+
+⚠️ Requires wallet configuration with private key. Use `"unlimited"` only for trusted protocols.
+
+---
+
+## tokens_transfer
+
+Transfer tokens to another address.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `toAddress` | string | Yes | Recipient address |
+| `amount` | string | Yes | Amount to transfer |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "success": true,
+  "transactionHash": "0xdef456...",
+  "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "to": "0x1234567890123456789012345678901234567890",
+  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "amount": "100.00",
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Send 100 USDC to 0x1234... on Polygon
+```
+
+### Security Note
+
+⚠️ Requires wallet configuration with private key. Double-check recipient address before confirming.
+
+---
+
+## tokens_get_top_holders
+
+Get the largest holders of a token.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `network` | string | No | Network name (default: ethereum) |
+| `limit` | number | No | Number of holders to return (default: 10) |
+
+### Response
+
+```json
+{
+  "token": {
+    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    "symbol": "USDC"
+  },
+  "holders": [
+    {
+      "rank": 1,
+      "address": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503",
+      "balance": "3500000000.00",
+      "percentage": 13.46
+    },
+    {
+      "rank": 2,
+      "address": "0x0A59649758aa4d66E25f08Dd01271e891fe52199",
+      "balance": "2100000000.00",
+      "percentage": 8.08
+    }
+  ],
+  "totalHolders": 1543289,
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Show top 10 USDC holders on Ethereum
+```
+
+---
+
+## tokens_get_token_price
+
+Get the current USD price of a token.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tokenAddress` | string | Yes | Token contract address |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "token": {
+    "address": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
+    "symbol": "WBTC",
+    "name": "Wrapped BTC"
+  },
+  "price": 43500.50,
+  "priceChange24h": 2.35,
+  "volume24h": 125000000,
+  "marketCap": 6525075000,
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+What's the price of WBTC?
+```
+
+---
+
+## Common Token Addresses
+
+### Ethereum Mainnet
+
+| Token | Address |
+|-------|---------|
+| USDC | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
+| USDT | `0xdAC17F958D2ee523a2206206994597C13D831ec7` |
+| WETH | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` |
+| WBTC | `0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599` |
+| DAI | `0x6B175474E89094C44Da98b954EeszdKAD3eF4cDD` |
+
+### BNB Smart Chain
+
+| Token | Address |
+|-------|---------|
+| USDC | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
+| USDT | `0x55d398326f99059fF775485246999027B3197955` |
+| WBNB | `0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c` |
+| BUSD | `0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56` |
+
+### Arbitrum
+
+| Token | Address |
+|-------|---------|
+| USDC | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` |
+| USDT | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9` |
+| WETH | `0x82aF49447D8a07e3bd95BD0d56f35241523fBab1` |
+| ARB | `0x912CE59144191C1204E64559FE8253a0e49E6548` |
+
+---
+
+## Batch Operations
+
+### Check Multiple Token Balances
+
+```
+Show my balances for USDC, USDT, and DAI on Ethereum
+```
+
+### Compare Token Prices
+
+```
+Compare prices of USDC, USDT, and DAI
+```
+
+---
+
+## Error Handling
+
+| Error Code | Description |
+|------------|-------------|
+| `INVALID_ADDRESS` | Token or wallet address is invalid |
+| `TOKEN_NOT_FOUND` | Token contract doesn't exist at address |
+| `INSUFFICIENT_BALANCE` | Not enough tokens for transfer |
+| `INSUFFICIENT_ALLOWANCE` | Spender not approved for amount |
+| `TRANSACTION_FAILED` | Transfer or approval transaction failed |
+
+---
+
+## Related Tools
+
+- [Wallet Tools](wallet-tools.md) - Wallet management
+- [Swap Tools](swap-tools.md) - Token swaps
+- [Security Tools](security-tools.md) - Token security checks
+- [Market Data Tools](market-data-tools.md) - Price data

package/docs/content/api/tools/wallet-tools.md

@@ -0,0 +1,328 @@
+# Wallet Tools
+
+Tools for wallet management, balance queries, and account operations across EVM networks.
+
+---
+
+## Overview
+
+Wallet tools provide functionality for creating and managing wallets, checking balances, and performing account-related operations.
+
+| Tool | Description |
+|------|-------------|
+| `wallet_create_wallet` | Create a new wallet with mnemonic |
+| `wallet_import_from_mnemonic` | Import wallet from mnemonic phrase |
+| `wallet_import_from_private_key` | Import wallet from private key |
+| `wallet_get_address` | Get wallet address |
+| `wallet_get_balance` | Get native token balance |
+| `wallet_get_token_balances` | Get all ERC-20 token balances |
+| `wallet_sign_message` | Sign a message with wallet |
+| `wallet_verify_signature` | Verify a signed message |
+
+---
+
+## wallet_create_wallet
+
+Create a new wallet with a randomly generated mnemonic phrase.
+
+### Parameters
+
+None required.
+
+### Response
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "mnemonic": "abandon ability able about above absent absorb abstract absurd abuse access accident",
+  "privateKey": "0x..."
+}
+```
+
+### Example
+
+```
+Create a new wallet for me
+```
+
+### Security Warning
+
+⚠️ **CRITICAL**: Store the mnemonic phrase securely. Anyone with the mnemonic has full control of the wallet.
+
+---
+
+## wallet_import_from_mnemonic
+
+Import a wallet from an existing mnemonic phrase.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mnemonic` | string | Yes | 12 or 24-word mnemonic phrase |
+| `index` | number | No | Derivation path index (default: 0) |
+
+### Response
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "path": "m/44'/60'/0'/0/0"
+}
+```
+
+### Example
+
+```
+Import wallet from mnemonic: abandon ability able about above absent absorb abstract absurd abuse access accident
+```
+
+---
+
+## wallet_import_from_private_key
+
+Import a wallet from a private key.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `privateKey` | string | Yes | Private key (with or without 0x prefix) |
+
+### Response
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3"
+}
+```
+
+### Example
+
+```
+Import wallet from private key 0xabc123...
+```
+
+---
+
+## wallet_get_address
+
+Get the address of the configured wallet.
+
+### Parameters
+
+None required.
+
+### Response
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3"
+}
+```
+
+### Example
+
+```
+What's my wallet address?
+```
+
+---
+
+## wallet_get_balance
+
+Get the native token balance (ETH, BNB, MATIC, etc.) for an address.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `address` | string | Yes | Wallet address to check |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "balance": "1.5",
+  "balanceWei": "1500000000000000000",
+  "symbol": "ETH",
+  "network": "ethereum"
+}
+```
+
+### Example
+
+```
+Check the ETH balance for 0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3
+```
+
+```
+What's my BNB balance on BSC?
+```
+
+---
+
+## wallet_get_token_balances
+
+Get all ERC-20 token balances for an address.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `address` | string | Yes | Wallet address to check |
+| `network` | string | No | Network name (default: ethereum) |
+
+### Response
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "network": "ethereum",
+  "tokens": [
+    {
+      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      "symbol": "USDC",
+      "name": "USD Coin",
+      "balance": "5000.00",
+      "decimals": 6,
+      "valueUsd": 5000.00
+    },
+    {
+      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+      "symbol": "USDT",
+      "name": "Tether USD",
+      "balance": "2500.00",
+      "decimals": 6,
+      "valueUsd": 2500.00
+    }
+  ],
+  "totalValueUsd": 7500.00
+}
+```
+
+### Example
+
+```
+Show all my tokens on Arbitrum
+```
+
+```
+What tokens does 0x742d35... hold on BSC?
+```
+
+---
+
+## wallet_sign_message
+
+Sign a message with the configured wallet's private key.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `message` | string | Yes | Message to sign |
+
+### Response
+
+```json
+{
+  "message": "Hello, World!",
+  "signature": "0x1234...abcd",
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3"
+}
+```
+
+### Example
+
+```
+Sign this message: "I authorize this transaction at timestamp 1234567890"
+```
+
+---
+
+## wallet_verify_signature
+
+Verify that a message was signed by a specific address.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `message` | string | Yes | Original message |
+| `signature` | string | Yes | Signature to verify |
+| `address` | string | Yes | Expected signer address |
+
+### Response
+
+```json
+{
+  "valid": true,
+  "recoveredAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "expectedAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3"
+}
+```
+
+### Example
+
+```
+Verify this signature 0x1234...abcd for message "Hello" from address 0x742d35...
+```
+
+---
+
+## Multi-Chain Balance Check
+
+Check balances across multiple networks efficiently:
+
+```
+Check my balances on Ethereum, Arbitrum, and Polygon
+```
+
+The response will aggregate results from all networks:
+
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fEb3",
+  "balances": {
+    "ethereum": {
+      "native": "1.5 ETH",
+      "valueUsd": 3750.00
+    },
+    "arbitrum": {
+      "native": "0.8 ETH",
+      "valueUsd": 2000.00
+    },
+    "polygon": {
+      "native": "500 MATIC",
+      "valueUsd": 450.00
+    }
+  },
+  "totalValueUsd": 6200.00
+}
+```
+
+---
+
+## Supported Networks
+
+| Network | Native Token | Chain ID |
+|---------|--------------|----------|
+| ethereum | ETH | 1 |
+| bsc | BNB | 56 |
+| polygon | MATIC | 137 |
+| arbitrum | ETH | 42161 |
+| optimism | ETH | 10 |
+| base | ETH | 8453 |
+| opbnb | BNB | 204 |
+
+---
+
+## Related Tools
+
+- [Token Tools](tokens-tools.md) - ERC-20 token operations
+- [Transaction Tools](transactions-tools.md) - Send transactions
+- [Portfolio Tools](portfolio-tools.md) - Portfolio tracking
+- [Security Tools](security-tools.md) - Address security checks

package/docs/content/assets/logo.svg

@@ -0,0 +1 @@
+<svg fill="none" height="40" viewBox="0 0 183 39" width="187.6" xmlns="http://www.w3.org/2000/svg"><title>Sperax</title><path clip-rule="evenodd" d="M25.483 22.447c-6.876 0-12.449-5.57-12.449-12.437 0-3.595-2.9-6.51-6.517-6.51C2.933 3.5 0 6.415 0 10.01s2.9 6.51 6.517 6.51h.033c6.843 0 12.383 5.571 12.415 12.438v.032c0 3.595 2.9 6.51 6.518 6.51A6.503 6.503 0 0 0 32 28.99c-.033-3.628-2.933-6.543-6.517-6.543" fill="#fff" fill-rule="evenodd"/><path clip-rule="evenodd" d="M6.55 22.448c-3.585 0-6.517 2.915-6.517 6.51s2.9 6.51 6.517 6.51a6.503 6.503 0 0 0 6.517-6.51c-.032-3.595-2.933-6.51-6.517-6.51M25.483 3.5c3.6 0 6.517 2.915 6.517 6.51a6.514 6.514 0 0 1-6.517 6.51 6.514 6.514 0 0 1-6.517-6.51 6.514 6.514 0 0 1 6.517-6.51" fill="#fff" fill-rule="evenodd"/><path d="M52.464 30.32c-6.176 0-8.864-2.848-8.864-6.976V22.8h3.392v.352c0 2.656 1.12 4 5.6 4 3.168 0 4.32-.864 4.32-2.848 0-1.952-.64-2.656-3.936-3.328l-3.648-.736c-3.68-.704-5.664-2.496-5.664-5.888 0-3.168 2.464-6.112 8-6.112 5.92 0 8.288 3.328 8.288 7.136v.384H56.56v-.352c0-2.624-1.152-4-4.992-4-3.168 0-4.448.896-4.448 2.784 0 1.952.864 2.496 3.808 3.136l3.648.768c4.032.832 5.792 2.848 5.792 6.08 0 3.36-2.432 6.144-7.904 6.144m13.84 5.216H62.88v-21.44h3.136v2.624h.16c.736-1.856 2.56-2.944 5.313-2.944 4.48 0 6.944 3.232 6.944 8.288 0 5.024-2.4 8.256-6.72 8.256-2.848 0-4.608-1.312-5.312-2.784h-.096zm0-12.064c0 2.656 1.537 3.904 4.352 3.904 3.04 0 4.32-1.408 4.32-5.312 0-3.936-1.248-5.344-4.32-5.344-2.815 0-4.352 1.248-4.352 3.904zm22.089 6.848c-5.248 0-7.712-3.328-7.712-8.288 0-4.928 2.944-8.256 7.68-8.256 4.288 0 7.296 2.56 7.296 6.912 0 .832-.096 1.696-.192 2.176H83.913c.128 2.912 1.184 4.384 4.512 4.384 2.656 0 3.68-.896 3.68-2.336v-.256h3.424v.288c0 3.264-2.848 5.376-7.136 5.376m-.096-13.632c-3.008 0-4.16 1.408-4.352 3.872h8.416c.128-2.72-1.344-3.872-4.064-3.872M101.871 30h-3.456V14h3.168v2.528h.16c.64-1.472 2.112-2.752 4.448-2.752 3.328 0 4.608 2.432 4.608 5.408v1.056h-3.456v-.64c0-2.112-.608-2.88-2.624-2.88-2.08 0-2.848.8-2.848 2.912zm15.115.32c-2.848 0-5.056-1.472-5.056-4.256 0-2.624 1.92-4 5.312-4.48l5.568-.832v-.864c0-2.368-1.088-3.072-3.584-3.072-2.528 0-3.52.8-3.52 2.912v.48h-3.328v-.32c0-3.552 2.783-6.112 7.04-6.112 4.448 0 6.688 2.688 6.688 6.56V30h-3.2v-2.496h-.16c-.928 1.504-2.752 2.816-5.76 2.816m-1.696-4.512c0 1.248.8 1.76 2.816 1.76 2.239 0 4.704-.896 4.704-4.096v-.288l-5.056.768c-1.824.256-2.464.672-2.464 1.856M131.284 30h-3.904l5.696-8v-.224l-5.696-7.68h4.031l4.289 5.888h.224l4.256-5.888h3.903l-5.695 7.808v.256l5.695 7.84h-4.031l-4.288-6.08h-.224zm17.797.384v-2.848h-2.88V12.592h2.88V9.744h9.28v2.848h2.912v14.944h-2.912v2.848zm.64-3.584h8V13.36h-8zm18.298 3.584v-2.848h-2.88V23.92h3.52v2.88h8v-4.96h-8.64v-2.848h-2.88v-6.4h2.88V9.744h9.28v2.848h2.912v3.584h-3.552V13.36h-8v4.928h8.64v2.784h2.912v6.464h-2.912v2.848z" fill="#fff"/></svg>