> For the complete documentation index, see [llms.txt](https://brolab.gitbook.io/hyperion-mcp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://brolab.gitbook.io/hyperion-mcp/hyperion-mcp-server-sdk-guide.md).

# Hyperion MCP Server SDK Guide

**Complete SDK guide for integrating with the Hyperion MCP Server via Smithery**

## 📋 Table of Contents

* [Quick Start](#-quick-start)
* [Installation](#-installation)
* [Authentication](#-authentication)
* [Available Tools](#-available-tools)
* [Usage Examples](#-usage-examples)
* [Error Handling](#-error-handling)
* [Best Practices](#-best-practices)

## 🚀 Quick Start

### Basic Setup

```javascript
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { Client } from "@modelcontextprotocol/sdk/client/index.js"

// Construct server URL with authentication
const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
url.searchParams.set("api_key", "36e96d01-a9dd-4e4c-a705-bbe239a712ea")
url.searchParams.set("profile", "notable-sparrow-IsrW6Y")
const serverUrl = url.toString()

const transport = new StreamableHTTPClientTransport(serverUrl)

// Create MCP client
const client = new Client({
  name: "My Hyperion App",
  version: "1.0.0"
})

await client.connect(transport)

// List available tools
const tools = await client.listTools()
console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`)
```

## 📦 Installation

### Prerequisites

* Node.js 18+
* npm or yarn package manager

### Install MCP SDK

```bash
npm install @modelcontextprotocol/sdk
```

### TypeScript Support (Optional)

```bash
npm install -D typescript @types/node
```

## 🔐 Authentication

The Hyperion MCP Server is hosted on Smithery and requires authentication:

```javascript
// Your Smithery credentials
const API_KEY = "36e96d01-a9dd-4e4c-a705-bbe239a712ea"
const PROFILE = "notable-sparrow-IsrW6Y"

// Construct authenticated URL
const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
url.searchParams.set("api_key", API_KEY)
url.searchParams.set("profile", PROFILE)
```

## 🛠️ Available Tools

The Hyperion MCP Server provides **18 comprehensive tools** for blockchain interactions:

### 💼 Wallet Management

#### `create_wallet`

Create a new Hyperion wallet with generated mnemonic phrase.

**Parameters:**

* `name` (optional): Wallet name

**Example:**

```javascript
const result = await client.callTool('create_wallet', {
  name: 'MyWallet'
})
```

#### `import_wallet`

Import existing wallet using private key or mnemonic phrase.

**Parameters:**

* `privateKey` (optional): Private key to import
* `mnemonic` (optional): Mnemonic phrase to import
* `name` (optional): Wallet name

**Example:**

```javascript
const result = await client.callTool('import_wallet', {
  mnemonic: 'your twelve word mnemonic phrase here...',
  name: 'ImportedWallet'
})
```

#### `list_wallets`

List all available wallets.

**Parameters:** None

**Example:**

```javascript
const result = await client.callTool('list_wallets', {})
```

#### `set_current_wallet`

Set the current active wallet for transactions.

**Parameters:**

* `address` (required): Wallet address to set as current

**Example:**

```javascript
const result = await client.callTool('set_current_wallet', {
  address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4'
})
```

#### `get_current_wallet`

Get current active wallet information.

**Parameters:** None

**Example:**

```javascript
const result = await client.callTool('get_current_wallet', {})
```

### 💰 Balance & Transactions

#### `get_balance`

Get balance of wallet address (native tMETIS or ERC20 tokens).

**Parameters:**

* `address` (required): Wallet address to check
* `tokenAddress` (optional): ERC20 token contract address

**Examples:**

```javascript
// Get native tMETIS balance
const nativeBalance = await client.callTool('get_balance', {
  address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4'
})

// Get ERC20 token balance
const tokenBalance = await client.callTool('get_balance', {
  address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  tokenAddress: '0x1234567890123456789012345678901234567890'
})
```

#### `send_transaction`

Send native tokens or ERC20 tokens to another address.

**Parameters:**

* `to` (required): Recipient address
* `amount` (required): Amount to send (in token units, not wei)
* `tokenAddress` (optional): ERC20 token contract address
* `gasLimit` (optional): Gas limit
* `gasPrice` (optional): Gas price

**Examples:**

```javascript
// Send native tMETIS
const nativeTx = await client.callTool('send_transaction', {
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  amount: '1.5'
})

// Send ERC20 tokens
const tokenTx = await client.callTool('send_transaction', {
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  amount: '100',
  tokenAddress: '0x1234567890123456789012345678901234567890'
})
```

#### `get_transaction`

Get transaction details by hash.

**Parameters:**

* `hash` (required): Transaction hash

**Example:**

```javascript
const result = await client.callTool('get_transaction', {
  hash: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
})
```

#### `estimate_gas`

Estimate gas cost for a transaction.

**Parameters:**

* `to` (required): Recipient address
* `value` (optional): Value to send (in ether)
* `data` (optional): Transaction data

**Example:**

```javascript
const result = await client.callTool('estimate_gas', {
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  value: '1.0'
})
```

### 🔗 Blockchain Queries

#### `get_block`

Get block information by number or hash.

**Parameters:**

* `blockNumber` (optional): Block number
* `blockHash` (optional): Block hash

**Examples:**

```javascript
// Get block by number
const blockByNumber = await client.callTool('get_block', {
  blockNumber: 12345
})

// Get block by hash
const blockByHash = await client.callTool('get_block', {
  blockHash: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
})
```

#### `get_network_info`

Get current network information and status.

**Parameters:** None

**Example:**

```javascript
const result = await client.callTool('get_network_info', {})
```

### 📄 Smart Contract Interactions

#### `call_contract`

Call a smart contract method (read-only).

**Parameters:**

* `contractAddress` (required): Smart contract address
* `methodName` (required): Method name to call
* `parameters` (optional): Method parameters array
* `abi` (optional): Contract ABI array

**Example:**

```javascript
const result = await client.callTool('call_contract', {
  contractAddress: '0x1234567890123456789012345678901234567890',
  methodName: 'balanceOf',
  parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4']
})
```

#### `send_contract_transaction`

Send a transaction to a smart contract method.

**Parameters:**

* `contractAddress` (required): Smart contract address
* `methodName` (required): Method name to call
* `parameters` (optional): Method parameters array
* `abi` (optional): Contract ABI array
* `value` (optional): Ether value to send
* `gasLimit` (optional): Gas limit
* `gasPrice` (optional): Gas price

**Example:**

```javascript
const result = await client.callTool('send_contract_transaction', {
  contractAddress: '0x1234567890123456789012345678901234567890',
  methodName: 'transfer',
  parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4', '1000000000000000000']
})
```

### 🪙 ERC20 Token Tools

#### `deploy_erc20_token`

Deploy a new ERC20 token contract.

**Parameters:**

* `name` (required): Token name (e.g., "My Token")
* `symbol` (required): Token symbol (e.g., "MTK")
* `initialSupply` (required): Initial token supply
* `decimals` (optional): Token decimals (default: 18)
* `mintable` (optional): Whether token should be mintable (default: false)
* `gasLimit` (optional): Gas limit
* `gasPrice` (optional): Gas price

**Example:**

```javascript
const result = await client.callTool('deploy_erc20_token', {
  name: 'My Token',
  symbol: 'MTK',
  decimals: 18,
  initialSupply: '1000000',
  mintable: true
})
```

#### `get_token_info`

Get information about an ERC20 token.

**Parameters:**

* `tokenAddress` (required): ERC20 token contract address

**Example:**

```javascript
const result = await client.callTool('get_token_info', {
  tokenAddress: '0x1234567890123456789012345678901234567890'
})
```

#### `mint_tokens`

Mint tokens (only for mintable tokens).

**Parameters:**

* `tokenAddress` (required): ERC20 token contract address
* `to` (required): Address to mint tokens to
* `amount` (required): Amount of tokens to mint
* `gasLimit` (optional): Gas limit
* `gasPrice` (optional): Gas price

**Example:**

```javascript
const result = await client.callTool('mint_tokens', {
  tokenAddress: '0x1234567890123456789012345678901234567890',
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  amount: '1000'
})
```

### 🎨 ERC721 NFT Tools

#### `deploy_erc721_token`

Deploy a new ERC721 token contract (NFT).

**Parameters:**

* `name` (required): Token name (e.g., "My NFT")
* `symbol` (required): Token symbol (e.g., "NFT")
* `bytecode` (required): Compiled contract bytecode (0x...)
* `gasLimit` (optional): Gas limit for deployment
* `gasPrice` (optional): Gas price for deployment

**Example:**

```javascript
const result = await client.callTool('deploy_erc721_token', {
  name: 'My NFT Collection',
  symbol: 'MYNFT',
  bytecode: '0x608060405234801561001057600080fd5b50...' // Your compiled contract bytecode
})
```

**Note**: You need to provide the compiled bytecode for the ERC721 contract. The server includes a reference implementation (`HyperionERC721`) that extends OpenZeppelin's `ERC721URIStorage` with minting capabilities.

## 📝 Usage Examples

### Complete Wallet Setup and Transaction Flow

```javascript
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { Client } from "@modelcontextprotocol/sdk/client/index.js"

async function hyperionExample() {
  // Setup client
  const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
  url.searchParams.set("api_key", "36e96d01-a9dd-4e4c-a705-bbe239a712ea")
  url.searchParams.set("profile", "notable-sparrow-IsrW6Y")

  const transport = new StreamableHTTPClientTransport(url.toString())
  const client = new Client({
    name: "Hyperion Demo App",
    version: "1.0.0"
  })

  await client.connect(transport)

  try {
    // 1. Create a new wallet
    console.log("Creating wallet...")
    const wallet = await client.callTool('create_wallet', {
      name: 'Demo Wallet'
    })
    console.log(wallet.content[0].text)

    // 2. Get network info
    console.log("Getting network info...")
    const networkInfo = await client.callTool('get_network_info', {})
    console.log(networkInfo.content[0].text)

    // 3. Check balance (will be 0 for new wallet)
    console.log("Checking balance...")
    const balance = await client.callTool('get_balance', {
      address: 'YOUR_WALLET_ADDRESS_HERE'
    })
    console.log(balance.content[0].text)

    // 4. Deploy an ERC20 token
    console.log("Deploying ERC20 token...")
    const tokenDeploy = await client.callTool('deploy_erc20_token', {
      name: 'Demo Token',
      symbol: 'DEMO',
      decimals: 18,
      initialSupply: '1000000',
      mintable: true
    })
    console.log(tokenDeploy.content[0].text)

  } catch (error) {
    console.error('Error:', error)
  }
}

hyperionExample()
```

### ERC20 Token Management

```javascript
async function tokenManagement() {
  // ... setup client as above ...

  try {
    // Deploy a mintable token
    const deployment = await client.callTool('deploy_erc20_token', {
      name: 'Utility Token',
      symbol: 'UTIL',
      decimals: 18,
      initialSupply: '1000000',
      mintable: true
    })

    // Extract contract address from deployment result
    const contractAddress = 'DEPLOYED_CONTRACT_ADDRESS'

    // Get token information
    const tokenInfo = await client.callTool('get_token_info', {
      tokenAddress: contractAddress
    })
    console.log('Token Info:', tokenInfo.content[0].text)

    // Mint additional tokens
    const mintResult = await client.callTool('mint_tokens', {
      tokenAddress: contractAddress,
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
      amount: '50000'
    })
    console.log('Mint Result:', mintResult.content[0].text)

    // Transfer tokens
    const transferResult = await client.callTool('send_transaction', {
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
      amount: '1000',
      tokenAddress: contractAddress
    })
    console.log('Transfer Result:', transferResult.content[0].text)

  } catch (error) {
    console.error('Token management error:', error)
  }
}
```

### ERC721 NFT Management

```javascript
async function nftManagement() {
  // ... setup client as above ...

  try {
    // Deploy an ERC721 contract
    // Note: You need to compile the contract first and get the bytecode
    const deployment = await client.callTool('deploy_erc721_token', {
      name: 'My Art Collection',
      symbol: 'ART',
      bytecode: '0x608060405234801561001057600080fd5b50...' // Your compiled bytecode
    })
    console.log('NFT Contract Deployed:', deployment.content[0].text)

    // Extract contract address from deployment result
    const contractAddress = 'DEPLOYED_NFT_CONTRACT_ADDRESS'

    // Mint an NFT using contract interaction
    const mintResult = await client.callTool('send_contract_transaction', {
      contractAddress: contractAddress,
      methodName: 'mint',
      parameters: [
        '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4', // recipient
        'https://ipfs.io/ipfs/QmYourMetadataHash' // tokenURI
      ]
    })
    console.log('NFT Minted:', mintResult.content[0].text)

    // Check NFT ownership
    const owner = await client.callTool('call_contract', {
      contractAddress: contractAddress,
      methodName: 'ownerOf',
      parameters: ['0'] // tokenId
    })
    console.log('NFT Owner:', owner.content[0].text)

    // Get token URI
    const tokenURI = await client.callTool('call_contract', {
      contractAddress: contractAddress,
      methodName: 'tokenURI',
      parameters: ['0'] // tokenId
    })
    console.log('Token URI:', tokenURI.content[0].text)

  } catch (error) {
    console.error('NFT management error:', error)
  }
}
```

### Smart Contract Interaction

```javascript
async function contractInteraction() {
  // ... setup client as above ...

  const contractAddress = '0x1234567890123456789012345678901234567890'

  try {
    // Read-only contract call
    const balance = await client.callTool('call_contract', {
      contractAddress: contractAddress,
      methodName: 'balanceOf',
      parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4']
    })
    console.log('Contract Balance:', balance.content[0].text)

    // Write contract transaction
    const transaction = await client.callTool('send_contract_transaction', {
      contractAddress: contractAddress,
      methodName: 'approve',
      parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4', '1000000000000000000']
    })
    console.log('Transaction Result:', transaction.content[0].text)

  } catch (error) {
    console.error('Contract interaction error:', error)
  }
}
```

## ⚠️ Error Handling

### Common Error Types

```javascript
async function handleErrors() {
  try {
    const result = await client.callTool('send_transaction', {
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
      amount: '1000'
    })
  } catch (error) {
    if (error.message.includes('insufficient funds')) {
      console.error('Not enough balance for transaction')
    } else if (error.message.includes('invalid address')) {
      console.error('Invalid recipient address')
    } else if (error.message.includes('gas')) {
      console.error('Gas estimation failed or gas limit too low')
    } else {
      console.error('Unknown error:', error.message)
    }
  }
}
```

### Retry Logic

```javascript
async function withRetry(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation()
    } catch (error) {
      if (i === maxRetries - 1) throw error
      console.log(`Attempt ${i + 1} failed, retrying...`)
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
    }
  }
}

// Usage
const result = await withRetry(() =>
  client.callTool('get_balance', {
    address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4'
  })
)
```

## 🎯 Best Practices

### 1. Connection Management

```javascript
class HyperionClient {
  constructor(apiKey, profile) {
    this.apiKey = apiKey
    this.profile = profile
    this.client = null
  }

  async connect() {
    if (this.client) return this.client

    const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
    url.searchParams.set("api_key", this.apiKey)
    url.searchParams.set("profile", this.profile)

    const transport = new StreamableHTTPClientTransport(url.toString())
    this.client = new Client({
      name: "Hyperion App",
      version: "1.0.0"
    })

    await this.client.connect(transport)
    return this.client
  }

  async disconnect() {
    if (this.client) {
      await this.client.close()
      this.client = null
    }
  }
}
```

### 2. Environment Configuration

```javascript
// config.js
export const config = {
  smithery: {
    apiKey: process.env.SMITHERY_API_KEY || "36e96d01-a9dd-4e4c-a705-bbe239a712ea",
    profile: process.env.SMITHERY_PROFILE || "notable-sparrow-IsrW6Y"
  },
  hyperion: {
    testnet: {
      rpcUrl: "https://hyperion-testnet.metisdevops.link",
      chainId: 133717,
      explorerUrl: "https://hyperion-testnet-explorer.metisdevops.link"
    }
  }
}
```

### 3. Type Safety (TypeScript)

```typescript
interface WalletInfo {
  address: string
  mnemonic?: string
  name?: string
}

interface TransactionResult {
  hash: string
  status: 'pending' | 'confirmed' | 'failed'
  explorerUrl?: string
}

interface TokenInfo {
  name: string
  symbol: string
  decimals: number
  totalSupply: string
  address: string
}

class TypedHyperionClient {
  async createWallet(name?: string): Promise<WalletInfo> {
    const result = await this.client.callTool('create_wallet', { name })
    // Parse and return typed result
    return this.parseWalletResult(result)
  }

  async sendTransaction(
    to: string,
    amount: string,
    tokenAddress?: string
  ): Promise<TransactionResult> {
    const result = await this.client.callTool('send_transaction', {
      to,
      amount,
      tokenAddress
    })
    return this.parseTransactionResult(result)
  }
}
```

### 4. Gas Optimization

```javascript
async function optimizeGas() {
  // Always estimate gas before sending transactions
  const gasEstimate = await client.callTool('estimate_gas', {
    to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
    value: '1.0'
  })

  // Add 20% buffer to gas estimate
  const gasLimit = Math.floor(parseInt(gasEstimate.gasUsed) * 1.2).toString()

  // Send transaction with optimized gas
  const result = await client.callTool('send_transaction', {
    to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
    amount: '1.0',
    gasLimit: gasLimit
  })
}
```

### 5. Batch Operations

```javascript
async function batchOperations() {
  const addresses = [
    '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
    '0x123d35Cc6634C0532925a3b8D4C9db96C4b4d123',
    '0x456d35Cc6634C0532925a3b8D4C9db96C4b4d456'
  ]

  // Check multiple balances concurrently
  const balancePromises = addresses.map(address =>
    client.callTool('get_balance', { address })
  )

  const balances = await Promise.all(balancePromises)
  balances.forEach((balance, index) => {
    console.log(`Address ${addresses[index]}: ${balance.content[0].text}`)
  })
}
```

## 🔒 Security Considerations

### 1. API Key Management

```javascript
// ❌ DON'T: Hardcode API keys
const apiKey = "36e96d01-a9dd-4e4c-a705-bbe239a712ea"

// ✅ DO: Use environment variables
const apiKey = process.env.SMITHERY_API_KEY

// ✅ DO: Use secure key management
import { getSecret } from './secure-config.js'
const apiKey = await getSecret('SMITHERY_API_KEY')
```

### 2. Input Validation

```javascript
function validateAddress(address) {
  if (!address || typeof address !== 'string') {
    throw new Error('Address is required and must be a string')
  }
  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
    throw new Error('Invalid Ethereum address format')
  }
  return address.toLowerCase()
}

function validateAmount(amount) {
  if (!amount || isNaN(parseFloat(amount))) {
    throw new Error('Amount must be a valid number')
  }
  if (parseFloat(amount) <= 0) {
    throw new Error('Amount must be greater than 0')
  }
  return amount
}
```

### 3. Rate Limiting

```javascript
class RateLimiter {
  constructor(maxRequests = 10, windowMs = 60000) {
    this.maxRequests = maxRequests
    this.windowMs = windowMs
    this.requests = []
  }

  async checkLimit() {
    const now = Date.now()
    this.requests = this.requests.filter(time => now - time < this.windowMs)

    if (this.requests.length >= this.maxRequests) {
      const oldestRequest = Math.min(...this.requests)
      const waitTime = this.windowMs - (now - oldestRequest)
      await new Promise(resolve => setTimeout(resolve, waitTime))
    }

    this.requests.push(now)
  }
}

const rateLimiter = new RateLimiter()

async function rateLimitedCall(toolName, params) {
  await rateLimiter.checkLimit()
  return await client.callTool(toolName, params)
}
```

## 📚 Additional Resources

### Network Information

* **Hyperion Testnet RPC**: `https://hyperion-testnet.metisdevops.link`
* **Chain ID**: `133717`
* **Currency**: `tMETIS` (Test METIS)
* **Explorer**: `https://hyperion-testnet-explorer.metisdevops.link`

### Useful Links

* [Smithery Platform](https://smithery.ai/)
* [MCP SDK Documentation](https://modelcontextprotocol.io/)
* [Hyperion MCP Server Repository](https://github.com/cuongpo/hyperion-mcp-server)
* [Hyperion Testnet Faucet](https://hyperion-testnet-explorer.metisdevops.link/faucet)

### Tool Summary

| Category                   | Tools                                                                                        | Count  |
| -------------------------- | -------------------------------------------------------------------------------------------- | ------ |
| **Wallet Management**      | `create_wallet`, `import_wallet`, `list_wallets`, `set_current_wallet`, `get_current_wallet` | 5      |
| **Balance & Transactions** | `get_balance`, `send_transaction`, `get_transaction`, `estimate_gas`                         | 4      |
| **Blockchain Queries**     | `get_block`, `get_network_info`                                                              | 2      |
| **Smart Contracts**        | `call_contract`, `send_contract_transaction`                                                 | 2      |
| **ERC20 Tokens**           | `deploy_erc20_token`, `get_token_info`, `mint_tokens`                                        | 3      |
| **ERC721 NFTs**            | `deploy_erc721_token`                                                                        | 1      |
| **Total**                  |                                                                                              | **18** |

### Example Applications

1. **DeFi Dashboard**: Track balances, transactions, and token holdings
2. **Token Launchpad**: Deploy and manage ERC20 tokens
3. **NFT Marketplace**: Deploy ERC721 contracts and mint NFTs
4. **Wallet Manager**: Create and manage multiple wallets
5. **Smart Contract Interface**: Interact with deployed contracts
6. **Transaction Monitor**: Track and analyze blockchain transactions
7. **Digital Art Platform**: Create and manage NFT collections

## 🤝 Support

For issues, questions, or contributions:

* **GitHub Issues**: [Report bugs or request features](https://github.com/cuongpo/hyperion-mcp-server/issues)
* **Documentation**: [Complete API reference](https://github.com/cuongpo/hyperion-mcp-server/blob/main/README.md)
* **Smithery Support**: [Platform documentation](https://smithery.ai/docs)

***

**Happy building with Hyperion MCP Server! 🚀**

```
```

```
```