Universal Crypto MCP

# Agenti - Universal Crypto MCP Server (Full Documentation)

> The most comprehensive Model Context Protocol (MCP) server for blockchain and DeFi.
> https://github.com/nirholas/agenti

## Table of Contents

1. [Overview](#overview)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Tool Categories](#tool-categories)
5. [Complete Tool Reference](#complete-tool-reference)
6. [Networks Reference](#networks-reference)
7. [x402 Payment Protocol](#x402-payment-protocol)
8. [Security Considerations](#security-considerations)
9. [Integration Guide](#integration-guide)
10. [Troubleshooting](#troubleshooting)

---

## Overview

Agenti is a Universal Model Context Protocol (MCP) server enabling AI agents to interact with any blockchain through natural language. It provides 380+ tools across 20+ networks with built-in security, DeFi integration, and the revolutionary x402 payment protocol for autonomous agent payments.

### Why Agenti?

| Feature | Agenti | Other MCP Servers |
|---------|--------|-------------------|
| Tools | 380+ | 10-50 |
| Chains | 20+ (EVM + Solana) | 1-3 |
| DEX Support | Multi-aggregator | Single/None |
| Security | GoPlus, honeypot, rug detection | Basic/None |
| DeFi | Aave, Compound, Lido, Uniswap | Limited |
| Market Data | CoinGecko, DefiLlama, LunarCrush | Basic |
| Bridges | LayerZero, Stargate, Wormhole | None |
| MEV Protection | Flashbots | None |
| Transport | stdio, HTTP, SSE | Usually stdio only |
| ChatGPT Support | ✅ Native HTTP mode | ❌ Most don't |

---

## Installation

### NPX (Recommended)
```bash
npx @nirholas/agenti
```

### Global Install
```bash
npm install -g @nirholas/agenti
agenti
```

### From Source
```bash
git clone https://github.com/nirholas/agenti.git
cd agenti
npm install
npm run build
npm start
```

---

## Configuration

### Environment Variables

```bash
# === REQUIRED FOR WRITE OPERATIONS ===
PRIVATE_KEY=0x...           # Wallet private key for signing

# === x402 PAYMENT CONFIGURATION ===
X402_PRIVATE_KEY=0x...      # Separate key for payments (recommended)
X402_NETWORK=base           # Default: base (lowest fees)

# === API KEYS (OPTIONAL, ENHANCES DATA) ===
COINGECKO_API_KEY=...       # Higher rate limits
DEFILLAMA_API_KEY=...       # Premium endpoints
LUNARCRUSH_API_KEY=...      # Social sentiment
GOPLUS_API_KEY=...          # Security scanning

# === RPC ENDPOINTS (OPTIONAL) ===
ETHEREUM_RPC=https://...    # Custom RPC
POLYGON_RPC=https://...
ARBITRUM_RPC=https://...
```

### Transport Modes

```bash
# stdio (Default) - For Claude Desktop, Cursor, etc.
npx @nirholas/agenti

# HTTP - For ChatGPT, web integrations
npx @nirholas/agenti --http --port 3000

# SSE - Server-Sent Events for streaming
npx @nirholas/agenti --sse --port 3000
```

---

## Tool Categories

### 1. Network & Chain Operations (12 tools)
- `get_chain_info` - Chain details (chainId, blockNumber, RPC)
- `get_supported_networks` - List all supported networks
- `get_block_number` - Current block number
- `get_block` - Block by number/hash
- `get_gas_price` - Current gas prices
- `estimate_gas` - Estimate transaction gas
- `get_fee_data` - EIP-1559 fee data
- `get_network_status` - Network health status
- `get_finality` - Block finality info
- `switch_network` - Change active network
- `get_rpc_url` - Get network RPC URL
- `validate_address` - Validate address format

### 2. Wallet Operations (15 tools)
- `get_balance` - Native + token balances
- `get_token_balance` - Specific token balance
- `get_wallet_portfolio` - Full portfolio view
- `get_wallet_history` - Transaction history
- `get_nonce` - Current nonce
- `sign_message` - Sign arbitrary message
- `sign_typed_data` - EIP-712 signing
- `verify_signature` - Verify message signature
- `create_wallet` - Generate new wallet
- `import_wallet` - Import from private key
- `export_wallet` - Export wallet data
- `get_address` - Get current address
- `switch_wallet` - Change active wallet
- `get_wallet_tokens` - List held tokens
- `get_wallet_nfts` - List held NFTs

### 3. Transaction Operations (10 tools)
- `send_transaction` - Send with confirmation
- `get_transaction` - Transaction details
- `get_transaction_receipt` - Receipt with logs
- `estimate_transaction` - Cost estimation
- `simulate_transaction` - Dry run simulation
- `cancel_transaction` - Cancel pending tx
- `speed_up_transaction` - Replace with higher gas
- `get_pending_transactions` - List pending txs
- `decode_transaction` - Decode tx data
- `build_transaction` - Build unsigned tx

### 4. Token Operations (12 tools)
- `transfer_token` - ERC20 transfer
- `approve_token` - Approve spending
- `check_allowance` - Check approval amount
- `revoke_approval` - Revoke token approval
- `get_token_info` - Token metadata
- `get_token_holders` - Top holders
- `get_token_supply` - Total/circulating supply
- `get_token_transfers` - Transfer history
- `wrap_token` - Wrap native token
- `unwrap_token` - Unwrap to native
- `permit_token` - EIP-2612 permit
- `batch_transfer` - Multiple transfers

### 5. DEX & Swap Operations (15 tools)
- `get_quote` - Best swap quote (aggregated)
- `swap_tokens` - Execute swap
- `get_liquidity_pools` - Available pools
- `add_liquidity` - Add LP position
- `remove_liquidity` - Remove LP position
- `get_pool_info` - Pool details/TVL
- `get_pool_price` - Pool spot price
- `get_slippage` - Estimated slippage
- `get_price_impact` - Price impact calculation
- `limit_order` - Place limit order
- `cancel_order` - Cancel limit order
- `get_orders` - List open orders
- `get_route` - Optimal swap route
- `multi_hop_swap` - Complex routing
- `arbitrage_check` - Find arbitrage opportunities

### 6. Lending & Borrowing (12 tools)
- `supply_lending` - Supply to protocol
- `withdraw_lending` - Withdraw supply
- `borrow_lending` - Borrow assets
- `repay_lending` - Repay loan
- `get_lending_position` - Current position
- `get_health_factor` - Collateral health
- `get_lending_rates` - Supply/borrow rates
- `get_available_borrow` - Borrowing capacity
- `get_liquidation_threshold` - Liquidation price
- `enable_collateral` - Enable as collateral
- `disable_collateral` - Disable collateral
- `flash_loan` - Flash loan execution

### 7. Staking Operations (10 tools)
- `stake_eth` - Liquid staking (Lido/Rocket)
- `unstake_eth` - Unstake ETH
- `get_staking_position` - Current stake
- `get_staking_rewards` - Pending rewards
- `claim_rewards` - Claim staking rewards
- `get_staking_apy` - Current APY
- `stake_token` - Stake protocol tokens
- `unstake_token` - Unstake tokens
- `get_validator_info` - Validator details
- `compound_rewards` - Auto-compound

### 8. Bridge & Cross-Chain (8 tools)
- `bridge_tokens` - Cross-chain transfer
- `get_bridge_quote` - Bridge cost/time
- `get_bridge_status` - Track bridge tx
- `get_supported_bridges` - Available bridges
- `get_bridge_limits` - Min/max amounts
- `claim_bridge` - Claim on destination
- `estimate_bridge_time` - Time estimate
- `get_bridge_history` - Past bridges

### 9. Security Analysis (15 tools)
- `check_token_security` - Full security scan
- `detect_honeypot` - Honeypot detection
- `check_contract_verified` - Verification status
- `get_contract_source` - Source code
- `analyze_contract` - Static analysis
- `check_rug_pull_risk` - Rug indicators
- `get_token_audit` - Audit reports
- `check_approvals` - Approval audit
- `simulate_revoke` - Safe revoke simulation
- `get_phishing_sites` - Known phishing
- `validate_contract` - Contract validation
- `get_scam_database` - Known scams
- `check_ownership` - Owner analysis
- `get_holder_distribution` - Holder concentration
- `detect_wash_trading` - Wash trade detection

### 10. Market Data (20 tools)
- `get_price` - Real-time price
- `get_price_history` - Historical OHLCV
- `get_market_cap` - Market capitalization
- `get_volume` - 24h volume
- `get_trending` - Trending tokens
- `get_gainers_losers` - Top movers
- `get_fear_greed` - Fear & Greed Index
- `get_global_stats` - Global market stats
- `get_dominance` - BTC/ETH dominance
- `search_coins` - Search tokens
- `get_coin_info` - Detailed token info
- `get_exchanges` - Exchange list
- `get_exchange_volume` - Exchange volumes
- `compare_prices` - Cross-exchange prices
- `get_price_alerts` - Set price alerts
- `get_all_time_high` - ATH data
- `get_price_change` - % changes
- `get_correlation` - Price correlation
- `get_volatility` - Volatility metrics
- `get_market_sentiment` - Sentiment analysis

### 11. DeFi Analytics (18 tools)
- `get_defi_tvl` - Protocol TVL
- `get_chain_tvl` - Chain TVL
- `get_tvl_history` - TVL over time
- `get_protocol_info` - Protocol details
- `get_yields` - Yield opportunities
- `get_yield_history` - Yield trends
- `get_protocol_fees` - Fee revenue
- `get_protocol_revenue` - Revenue metrics
- `get_stablecoin_stats` - Stablecoin data
- `get_dex_volume` - DEX volumes
- `get_lending_stats` - Lending metrics
- `get_derivatives_stats` - Derivatives data
- `get_insurance_stats` - Insurance TVL
- `compare_protocols` - Protocol comparison
- `get_protocol_chains` - Multi-chain presence
- `get_protocol_treasury` - Treasury holdings
- `get_unlock_schedule` - Token unlocks
- `get_airdrop_info` - Airdrop tracking

### 12. NFT Operations (14 tools)
- `get_nft_metadata` - NFT details
- `get_nft_owner` - Current owner
- `transfer_nft` - Transfer NFT
- `approve_nft` - Approve transfer
- `get_collection_info` - Collection data
- `get_collection_stats` - Floor, volume
- `get_nft_history` - Transfer history
- `list_nft` - List for sale
- `buy_nft` - Purchase NFT
- `make_offer` - Make bid
- `cancel_listing` - Cancel sale
- `get_nft_valuations` - Price estimates
- `mint_nft` - Mint new NFT
- `batch_transfer_nft` - Multiple transfers

### 13. Governance (10 tools)
- `get_proposals` - Active proposals
- `get_proposal` - Proposal details
- `cast_vote` - Vote on proposal
- `delegate_votes` - Delegate voting power
- `get_voting_power` - Check voting power
- `get_delegates` - Current delegates
- `create_proposal` - Create new proposal
- `queue_proposal` - Queue for execution
- `execute_proposal` - Execute passed
- `get_governance_info` - DAO info

### 14. x402 Payment Tools (14 tools)
- `x402_pay_request` - HTTP request + auto-pay
- `x402_send` - Direct payment
- `x402_batch_send` - Multiple payments
- `x402_gasless_send` - Gasless via EIP-3009
- `x402_balance` - Check balance
- `x402_address` - Get wallet address
- `x402_estimate` - Cost estimation
- `x402_networks` - Supported networks
- `x402_config` - View configuration
- `x402_tx_status` - Transaction status
- `x402_yield` - USDs yield info
- `x402_apy` - Current APY (~5%)
- `x402_yield_estimate` - Project yield
- `x402_approve` - Approve spending

---

## Networks Reference

### EVM Networks (Full Support)

| Network | Chain ID | Native Token | Explorer |
|---------|----------|--------------|----------|
| Ethereum | 1 | ETH | etherscan.io |
| Polygon | 137 | MATIC | polygonscan.com |
| Arbitrum | 42161 | ETH | arbiscan.io |
| Optimism | 10 | ETH | optimistic.etherscan.io |
| Base | 8453 | ETH | basescan.org |
| BSC | 56 | BNB | bscscan.com |
| Avalanche | 43114 | AVAX | snowtrace.io |
| Fantom | 250 | FTM | ftmscan.com |
| Gnosis | 100 | xDAI | gnosisscan.io |
| Celo | 42220 | CELO | celoscan.io |
| Moonbeam | 1284 | GLMR | moonscan.io |
| Aurora | 1313161554 | ETH | explorer.aurora.dev |
| Metis | 1088 | METIS | andromeda-explorer.metis.io |
| Linea | 59144 | ETH | lineascan.build |
| Scroll | 534352 | ETH | scrollscan.com |
| zkSync | 324 | ETH | explorer.zksync.io |
| Mantle | 5000 | MNT | explorer.mantle.xyz |
| Blast | 81457 | ETH | blastscan.io |
| Mode | 34443 | ETH | explorer.mode.network |
| Sei | 1329 | SEI | seitrace.com |

### Non-EVM (Adapter Support)
- Solana (via @agenti/solana adapter)

---

## x402 Payment Protocol

### What is x402?

x402 implements HTTP 402 "Payment Required" for AI agents. Agents can autonomously pay for API access, premium data, and services.

### How It Works

1. Agent makes request to x402-enabled API
2. API returns 402 with payment requirements
3. Agent's x402 wallet pays automatically
4. API returns data after payment confirmation

### Supported Stablecoins

| Token | Networks | Notes |
|-------|----------|-------|
| USDC | All EVM | Primary payment token |
| USDs | Base, Arbitrum | Auto-yield (~5% APY) |

### Configuration

```bash
export X402_PRIVATE_KEY=0x...
export X402_NETWORK=base        # Recommended for lowest fees
export X402_MAX_PAYMENT=1.00    # Max payment per request
```

### Usage Examples

```
# Pay for premium API
x402_pay_request({ url: "https://api.example.com/premium", maxPayment: "0.10" })

# Check balance
x402_balance()
# Output: { usdc: "45.23", native: "0.005" }

# Send direct payment
x402_send({ to: "0x...", amount: "1.00", token: "usdc" })
```

---

## Security Considerations

### Private Key Safety

1. **Never share private keys** in prompts or logs
2. **Use separate keys** for x402 payments
3. **Set spending limits** with X402_MAX_PAYMENT
4. **Test on testnets** before mainnet

### Transaction Safety

1. **Always simulate** before executing
2. **Review transaction data** before signing
3. **Use MEV protection** for swaps
4. **Check token security** before interacting

### Approval Management

1. **Audit approvals** regularly with `check_approvals`
2. **Revoke unused approvals** with `revoke_approval`
3. **Use permit** instead of approve when possible
4. **Set minimal approval amounts**

---

## Integration Guide

### Claude Desktop

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "agenti": {
      "command": "npx",
      "args": ["@nirholas/agenti"],
      "env": {
        "PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

### Cursor

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "agenti": {
      "command": "npx",
      "args": ["@nirholas/agenti"]
    }
  }
}
```

### ChatGPT (HTTP Mode)

```bash
# Start HTTP server
npx @nirholas/agenti --http --port 3000

# Configure in ChatGPT Actions with OpenAPI spec
```

### Windsurf / Continue

```json
// .continue/config.json or windsurf config
{
  "mcpServers": [
    {
      "name": "agenti",
      "command": "npx @nirholas/agenti"
    }
  ]
}
```

---

## Troubleshooting

### Common Issues

**"No private key configured"**
- Set PRIVATE_KEY environment variable for write operations

**"Insufficient funds"**
- Check native token balance for gas
- Check token balance for transfers

**"Transaction underpriced"**
- Network congestion - increase gas price
- Use `get_gas_price` to check current prices

**"Nonce too low"**
- Pending transaction - wait or cancel
- Use `get_pending_transactions` to check

**"Contract execution reverted"**
- Use `simulate_transaction` to debug
- Check contract requirements

### Debug Mode

```bash
DEBUG=agenti:* npx @nirholas/agenti
```

### Support

- GitHub Issues: https://github.com/nirholas/agenti/issues
- Discord: [Coming soon]
- Twitter: https://x.com/nichxbt

---

## License

Apache-2.0 - Free for commercial and personal use.

---

## Links

- GitHub: https://github.com/nirholas/agenti
- NPM: https://www.npmjs.com/package/@nirholas/agenti
- Documentation: https://nirholas.github.io/agenti/
- Twitter: https://x.com/nichxbt