bsv-mcp 0.0.7 → 0.0.9

package/Dockerfile

@@ -0,0 +1,20 @@
+# Use the official Bun image
+FROM oven/bun:1
+
+# Set working directory
+WORKDIR /app
+
+# Copy all application code first
+COPY . .
+
+# Install dependencies
+RUN bun install --frozen-lockfile
+
+# Set user for security
+USER bun
+
+# Expose port (if needed)
+EXPOSE 3000
+
+# Run the application
+CMD ["bun", "run", "index.ts"] 

package/README.md

@@ -1,5 +1,7 @@
 # Bitcoin SV MCP Server
 
+[![smithery badge](https://smithery.ai/badge/@b-open-io/bsv-mcp)](https://smithery.ai/server/@b-open-io/bsv-mcp)
+
 > **⚠️ NOTICE: Experimental Work in Progress**  
 > This project is in an early experimental stage. Features may change, and the API is not yet stable.
 > Contributions, feedback, and bug reports are welcome! Feel free to open issues or submit pull requests.
@@ -136,46 +138,46 @@ The toolkit is organized into several categories:
 
 Wallet tools provide core BSV wallet functionality:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `wallet_getPublicKey` | Retrieves a public key for a specified protocol and key ID |
-| `wallet_createSignature` | Creates a cryptographic signature for the provided data |
-| `wallet_verifySignature` | Verifies a cryptographic signature against the provided data |
-| `wallet_encrypt` | Encrypts data using a specified protocol and key |
-| `wallet_decrypt` | Decrypts data using a specified protocol and key |
-| `wallet_getAddress` | Returns a BSV address for the current wallet or a derived path |
-| `wallet_sendToAddress` | Sends BSV to a specified address (supports BSV or USD amounts) |
-| `wallet_purchaseListing` | Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings |
-| `wallet_createOrdinals` | Creates and inscribes ordinals on the BSV blockchain |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `wallet_getPublicKey` | Retrieves a public key for a specified protocol and key ID | `{"publicKey":"032d0c73eb9270e9e009fd1f9dd77e19cf764fbad5f799560c4e8fd414e40d6fc2"}` |
+| `wallet_createSignature` | Creates a cryptographic signature for the provided data | `{"signature":[144,124,85,193,226,45,140,249,9,177,11,167,33,215,209,38,...]}` |
+| `wallet_verifySignature` | Verifies a cryptographic signature against the provided data | `{"isValid":true}` |
+| `wallet_encryption` | Combined tool for encrypting and decrypting data using the wallet's cryptographic keys (replaces separate encrypt/decrypt tools) | Encrypt: `{"ciphertext":[89,32,155,38,125,22,49,226,26,...]}` <br> Decrypt: `{"plaintext":[104,101,108,108,111,32,119,111,114,108,100]}` |
+| `wallet_getAddress` | Returns a BSV address for the current wallet or a derived path | `{"address":"1ExampleBsvAddressXXXXXXXXXXXXXXXXX","status":"ok"}` |
+| `wallet_sendToAddress` | Sends BSV to a specified address (supports BSV or USD amounts) | `{"status":"success","txid":"a1b2c3d4e5f6...","satoshis":1000000}` |
+| `wallet_purchaseListing` | Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings | `{"status":"success","txid":"a1b2c3d4e5f6...","type":"nft","origin":"abcdef123456..."}` |
+| `wallet_createOrdinals` | Creates and inscribes ordinals on the BSV blockchain | `{"txid":"a1b2c3d4e5f6...","inscriptionAddress":"1ExampleAddress...","contentType":"image/png"}` |
 
 ### BSV Tools
 
 Tools for interacting with the BSV blockchain and network:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `bsv_getPrice` | Gets the current BSV price from an exchange API |
-| `bsv_decodeTransaction` | Decodes a BSV transaction and returns detailed information |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `bsv_getPrice` | Gets the current BSV price from an exchange API | `Current BSV price: $38.75 USD` |
+| `bsv_decodeTransaction` | Decodes a BSV transaction and returns detailed information | `{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,"inputs":[...],"outputs":[...]}` |
+| `bsv_explore` | Comprehensive blockchain explorer tool accessing WhatsOnChain API endpoints | `{"chain_info":{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}}` |
 
 ### Ordinals Tools
 
 Tools for working with ordinals (NFTs) on BSV:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `ordinals_getInscription` | Retrieves detailed information about a specific inscription |
-| `ordinals_searchInscriptions` | Searches for inscriptions based on various criteria |
-| `ordinals_marketListings` | Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface |
-| `ordinals_marketSales` | Gets information about BSV-20 and BSV-21 token market sales |
-| `ordinals_getBsv20ById` | Retrieves details about a specific BSV20 token by ID |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `ordinals_getInscription` | Retrieves detailed information about a specific inscription | `{"id":"a1b2c3d4e5f6...","origin":"a1b2c3d4e5f6...","contentType":"image/png","content":"iVBORw0KGgoAAA..."}` |
+| `ordinals_searchInscriptions` | Searches for inscriptions based on various criteria | `{"results":[{"id":"a1b2c3...","contentType":"image/png","owner":"1Example..."},...]}` |
+| `ordinals_marketListings` | Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface | `{"results":[{"txid":"a1b2c3...","price":9990000,"tick":"PEPE","listing":true},...]}` |
+| `ordinals_marketSales` | Gets information about BSV-20 and BSV-21 token market sales | `{"results":[{"txid":"a1b2c3...","price":34710050,"tick":"$BTC","sale":true},...]}` |
+| `ordinals_getTokenByIdOrTicker` | Retrieves details about a specific BSV20 token by ID | `{"tick":"PEPE","max":"21000000","lim":"1000","dec":"2"}` |
 
 ### Utility Tools
 
 General-purpose utility functions:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `utils_convertData` | Converts data between different encodings (utf8, hex, base64, binary) |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `utils_convertData` | Converts data between different encodings (utf8, hex, base64, binary) | `68656c6c6f20776f726c64` (UTF-8 "hello world" converted to hex) |
 
 ## Using the Tools with MCP
 
@@ -185,6 +187,8 @@ Once connected, you can use natural language to interact with Bitcoin SV through
 - "Get my Bitcoin SV address"
 - "Send 0.01 BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
 - "Send $5 USD worth of BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
+- "Encrypt this message using my wallet's keys"
+- "Decrypt this data that was previously encrypted for me"
 - "Purchase this NFT listing: txid_vout"
 - "Purchase this BSV-20 token listing: txid_vout"
 
@@ -198,6 +202,11 @@ Once connected, you can use natural language to interact with Bitcoin SV through
 ### Blockchain Operations
 - "What is the current BSV price?"
 - "Decode this BSV transaction: (transaction hex or ID)"
+- "Get the latest Bitcoin SV chain information"
+- "Show me block details for height 800000"
+- "Explore transaction history for address 1ExampleBsvAddressXXXX"
+- "Check unspent outputs (UTXOs) for my wallet address"
+- "Get details for transaction with hash a1b2c3d4e5f6..."
 
 ### Data Conversion
 - "Convert 'Hello World' from UTF-8 to hex format"
@@ -230,14 +239,81 @@ For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Conte
 
 ## Recent Updates
 
-### Enhanced Marketplace Tools
-- **Unified Market Listings**: The `ordinals_marketListings` tool now supports NFTs, BSV-20, and BSV-21 tokens through a single interface with appropriate filtering.
-- **Improved Market Sales**: The `ordinals_marketSales` tool (renamed from `ordinals_bsv20MarketSales`) now supports both BSV-20 and BSV-21 token sales.
-- **Token Purchases**: The `wallet_purchaseListing` tool has been enhanced to support purchasing both NFTs and BSV-20/BSV-21 tokens.
+- **Blockchain Explorer**: Added `bsv_explore` tool for WhatsOnChain API access with mainnet/testnet support
+- **Unified Tools**: Merged `wallet_encrypt`/`wallet_decrypt` into single `wallet_encryption` tool
+- **Enhanced Marketplace**: Support for NFTs, BSV-20/21 tokens in listings, sales and purchases
+- **Performance**: Added price caching and optimized API endpoint structure
+- **Improved Validation**: Better error handling for private keys and parameters
+
+## Bitcoin SV Blockchain Explorer
+
+The `bsv_explore` tool provides comprehensive access to the Bitcoin SV blockchain through the WhatsOnChain API. This powerful explorer tool allows you to query various aspects of the blockchain, including chain data, blocks, transactions, and address information.
+
+### Available Endpoints
+
+The tool supports the following endpoint categories and specific endpoints:
+
+#### Chain Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `chain_info` | Network statistics, difficulty, and chain work | None | `{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"000000000000..."}` |
+| `chain_tips` | Current chain tips including heights and states | None | `[{"height":826458,"hash":"000000000000...","branchlen":0,"status":"active"}]` |
+| `circulating_supply` | Current BSV circulating supply | None | `{"bsv":21000000}` |
+| `peer_info` | Connected peer statistics | None | `[{"addr":"1.2.3.4:8333","services":"000000000000...","lastsend":1621234567}]` |
+
+#### Block Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `block_by_hash` | Complete block data via hash | `blockHash` | `{"hash":"000000000000...","confirmations":1000,"size":1000000,...}` |
+| `block_by_height` | Complete block data via height | `blockHeight` | `{"hash":"000000000000...","confirmations":1000,"size":1000000,...}` |
+
+#### Transaction Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `tx_by_hash` | Detailed transaction data | `txHash` | `{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,...}` |
+| `tx_raw` | Raw transaction hex data | `txHash` | `"01000000012345abcdef..."` |
+| `tx_receipt` | Transaction receipt | `txHash` | `{"blockHash":"000000000000...","blockHeight":800000,"confirmations":26458}` |
+
+#### Address Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `address_history` | Transaction history for address | `address`, optional: `limit` | `[{"tx_hash":"a1b2c3d4e5f6...","height":800000},...]` |
+| `address_utxos` | Unspent outputs for address | `address` | `[{"tx_hash":"a1b2c3d4e5f6...","tx_pos":0,"value":100000},...]` |
+
+#### Network
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `health` | API health check | None | `{"status":"synced"}` |
+
+### Usage Examples
+
+The `bsv_explore` tool can be used with natural language prompts like:
+
+```
+"Get the current Bitcoin SV blockchain information"
+"Show me block #800000 details"
+"Fetch transaction history for address 1ExampleBsvAddressXXXXXXXX"
+"Get unspent outputs for my wallet address"
+"Check transaction details for txid a1b2c3d4e5f6..."
+"What is the current BSV circulating supply?"
+```
+
+Under the hood, the tool accepts parameters to specify which data to retrieve:
+
+- `endpoint`: The specific WhatsOnChain endpoint to query (e.g., `chain_info`, `tx_by_hash`)
+- `network`: The BSV network to use (`main` or `test`)
+- Additional parameters as required by the specific endpoint:
+  - `blockHash`: For block_by_hash endpoint
+  - `blockHeight`: For block_by_height endpoint
+  - `txHash`: For transaction-related endpoints
+  - `address`: For address-related endpoints
+  - `limit`: Optional pagination limit for address_history
+
+### Network Options
 
-### API Refinements
-- Standardized endpoint structure for interactions with the GorillaPool API.
-- Improved parameter handling for different token types and marketplace actions.
+The tool supports both mainnet and testnet:
+- `main`: Bitcoin SV mainnet (default)
+- `test`: Bitcoin SV testnet
 
 ## Development
 
@@ -255,4 +331,4 @@ bun test
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/index.ts

@@ -6,16 +6,43 @@ import { registerAllTools } from "./tools";
 import { registerWalletTools } from "./tools/wallet/tools";
 import { Wallet } from "./tools/wallet/wallet";
 
+/**
+ * Validate the private key from environment variables
+ * Exits the process with an error message if validation fails
+ */
+function validatePrivateKey(): PrivateKey {
+	const privateKeyWif = process.env.PRIVATE_KEY_WIF;
+	
+	// Check if private key is set
+	if (!privateKeyWif) {
+		console.error("\x1b[31mError: PRIVATE_KEY_WIF environment variable is not set\x1b[0m");
+		console.error("Please set this variable with a valid Bitcoin SV private key in WIF format");
+		console.error("Example: PRIVATE_KEY_WIF=your_private_key_wif bun run index.ts");
+		process.exit(1);
+	}
+	
+	// Validate the private key format
+	try {
+		return PrivateKey.fromWif(privateKeyWif);
+	} catch (error) {
+		console.error("\x1b[31mError: Invalid private key format\x1b[0m");
+		console.error("The PRIVATE_KEY_WIF provided is not a valid Bitcoin SV private key in WIF format");
+		console.error("Please check your key and try again");
+		process.exit(1);
+	}
+}
+
+// Validate private key early before starting the server
+const privKey = validatePrivateKey();
+console.log("\x1b[32mPrivate key validated successfully\x1b[0m");
+
 const server = new McpServer({
 	name: "Bitcoin SV MCP",
 	version: "0.0.1",
 });
 
-// Singleton wallet instance (for demo, could be replaced with real key management)
-// If PRIVATE_KEY_WIF is set in the environment, use it to instantiate the Wallet
-const privateKeyWif = process.env.PRIVATE_KEY_WIF;
-const privKey = privateKeyWif ? PrivateKey.fromWif(privateKeyWif) : undefined;
-const wallet = privKey ? new Wallet(privKey) : new Wallet();
+// Initialize wallet with the validated private key
+const wallet = new Wallet(privKey);
 
 // Register wallet tools separately (needs wallet instance)
 registerWalletTools(server, wallet);
@@ -25,7 +52,7 @@ registerAllTools(server);
 
 // Debug: Log all registered tools
 console.log("Registered tools:", Object.keys(server));
-console.log("MCP Server:", server);
+console.log("MCP Server ready 🚀");
 
 // Connect to the transport
 const transport = new StdioServerTransport();

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"bin": {
 		"bsv-mcp": "./index.ts"
 	},

package/smithery.yaml

@@ -1,3 +1,6 @@
+build:
+  dockerBuildPath: ./ 
+  
 startCommand:
   type: stdio
   configSchema:
@@ -7,15 +10,12 @@ startCommand:
     properties:
       privateKeyWif:
         type: string
-        description: "Your private key WIF (Wallet Import Format) for Bitcoin SV transactions. This key is used to sign transactions and is required for wallet operations."
+        description: "The private key WIF (Wallet Import Format) for Bitcoin SV transactions. This key is used to sign transactions and is required for wallet operations."
   commandFunction: |
-    (config) => ({
-      "command": "bun",
-      "args": [
-        "run",
-        "index.ts"
-      ],
-      "env": {
-        "PRIVATE_KEY_WIF": config.privateKeyWif
-      }
+    (config) => ({ 
+      command: 'bun', 
+      args: ['run', 'index.ts'], 
+      env: { 
+        PRIVATE_KEY_WIF: config.privateKeyWif 
+      } 
     })

package/tools/bsv/explore.ts

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Base URL for WhatsOnChain API
+const WOC_API_BASE_URL = "https://api.whatsonchain.com/v1/bsv";
+
+/**
+ * WhatsOnChain API endpoints available for exploration
+ */
+enum ExploreEndpoint {
+  // Chain endpoints
+  CHAIN_INFO = "chain_info",
+  CHAIN_TIPS = "chain_tips",
+  CIRCULATING_SUPPLY = "circulating_supply",
+  PEER_INFO = "peer_info",
+  
+  // Block endpoints
+  BLOCK_BY_HASH = "block_by_hash",
+  BLOCK_BY_HEIGHT = "block_by_height",
+  
+  // Transaction endpoints
+  TX_BY_HASH = "tx_by_hash",
+  TX_RAW = "tx_raw",
+  TX_RECEIPT = "tx_receipt",
+  ADDRESS_HISTORY = "address_history",
+  ADDRESS_UTXOS = "address_utxos",
+  
+  // Health endpoint
+  HEALTH = "health",
+}
+
+enum Network {
+  MAIN = "main",
+  TEST = "test",
+}
+
+// Schema for the bsv_explore tool arguments
+const exploreArgsSchema = z.object({
+  endpoint: z.nativeEnum(ExploreEndpoint).describe("WhatsOnChain API endpoint to call"),
+  network: z.nativeEnum(Network).default(Network.MAIN).describe("Network to use (main or test)"),
+  
+  // Parameters for specific endpoints
+  blockHash: z.string().optional().describe("Block hash (required for block_by_hash endpoint)"),
+  blockHeight: z.number().optional().describe("Block height (required for block_by_height endpoint)"),
+  txHash: z.string().optional().describe("Transaction hash (required for tx_by_hash, tx_raw, and tx_receipt endpoints)"),
+  address: z.string().optional().describe("Bitcoin address (required for address_history and address_utxos endpoints)"),
+  limit: z.number().optional().describe("Limit for paginated results (optional for address_history)"),
+});
+
+// Type for the tool arguments
+type ExploreArgs = z.infer<typeof exploreArgsSchema>;
+
+/**
+ * Register the bsv_explore tool with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerExploreTool(server: McpServer): void {
+  server.tool(
+    "bsv_explore",
+    "Explore Bitcoin SV blockchain data using the WhatsOnChain API. Access multiple data types:\n\n" +
+    "CHAIN DATA:\n" +
+    "- chain_info: Network stats, difficulty, and chain work\n" +
+    "- chain_tips: Current chain tips including heights and states\n" +
+    "- circulating_supply: Current BSV circulating supply\n" +
+    "- peer_info: Connected peer statistics\n\n" +
+    "BLOCK DATA:\n" +
+    "- block_by_hash: Complete block data via hash (requires blockHash parameter)\n" +
+    "- block_by_height: Complete block data via height (requires blockHeight parameter)\n\n" +
+    "TRANSACTION DATA:\n" +
+    "- tx_by_hash: Detailed transaction data (requires txHash parameter)\n" +
+    "- tx_raw: Raw transaction hex data (requires txHash parameter)\n" +
+    "- tx_receipt: Transaction receipt (requires txHash parameter)\n\n" +
+    "ADDRESS DATA:\n" +
+    "- address_history: Transaction history for address (requires address parameter, optional limit)\n" +
+    "- address_utxos: Unspent outputs for address (requires address parameter)\n\n" +
+    "NETWORK:\n" +
+    "- health: API health check\n\n" +
+    "Use the appropriate parameters for each endpoint type and specify 'main' or 'test' network.",
+    { args: exploreArgsSchema },
+    async ({ args }) => {
+      try {
+        const params = exploreArgsSchema.parse(args);
+        
+        // Validate required parameters for specific endpoints
+        if (params.endpoint === ExploreEndpoint.BLOCK_BY_HASH && !params.blockHash) {
+          throw new Error("blockHash is required for block_by_hash endpoint");
+        }
+        
+        if (params.endpoint === ExploreEndpoint.BLOCK_BY_HEIGHT && params.blockHeight === undefined) {
+          throw new Error("blockHeight is required for block_by_height endpoint");
+        }
+
+        if ([ExploreEndpoint.TX_BY_HASH, ExploreEndpoint.TX_RAW, ExploreEndpoint.TX_RECEIPT].includes(params.endpoint) && !params.txHash) {
+          throw new Error("txHash is required for transaction endpoints");
+        }
+
+        if ([ExploreEndpoint.ADDRESS_HISTORY, ExploreEndpoint.ADDRESS_UTXOS].includes(params.endpoint) && !params.address) {
+          throw new Error("address is required for address endpoints");
+        }
+        
+        // Build API URL based on the selected endpoint
+        let apiUrl = `${WOC_API_BASE_URL}/${params.network}`;
+        
+        switch (params.endpoint) {
+          case ExploreEndpoint.CHAIN_INFO:
+            apiUrl += "/chain/info";
+            break;
+          case ExploreEndpoint.CHAIN_TIPS:
+            apiUrl += "/chain/tips";
+            break;
+          case ExploreEndpoint.CIRCULATING_SUPPLY:
+            apiUrl += "/circulatingsupply";
+            break;
+          case ExploreEndpoint.PEER_INFO:
+            apiUrl += "/peer/info";
+            break;
+          case ExploreEndpoint.BLOCK_BY_HASH:
+            apiUrl += `/block/hash/${params.blockHash}`;
+            break;
+          case ExploreEndpoint.BLOCK_BY_HEIGHT:
+            apiUrl += `/block/height/${params.blockHeight}`;
+            break;
+          case ExploreEndpoint.TX_BY_HASH:
+            apiUrl += `/tx/hash/${params.txHash}`;
+            break;
+          case ExploreEndpoint.TX_RAW:
+            apiUrl += `/tx/${params.txHash}/hex`;
+            break;
+          case ExploreEndpoint.TX_RECEIPT:
+            apiUrl += `/tx/${params.txHash}/receipt`;
+            break;
+          case ExploreEndpoint.ADDRESS_HISTORY:
+            apiUrl += `/address/${params.address}/history`;
+            if (params.limit !== undefined) {
+              apiUrl += `?limit=${params.limit}`;
+            }
+            break;
+          case ExploreEndpoint.ADDRESS_UTXOS:
+            apiUrl += `/address/${params.address}/unspent`;
+            break;
+          case ExploreEndpoint.HEALTH:
+            apiUrl += "/woc";
+            break;
+          default:
+            throw new Error(`Unsupported endpoint: ${params.endpoint}`);
+        }
+        
+        // Make the API request
+        const response = await fetch(apiUrl);
+        if (!response.ok) {
+          throw new Error(`API error: ${response.status} ${response.statusText}`);
+        }
+        
+        const result = await response.json();
+        
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text", 
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`
+            }
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+} 

package/tools/bsv/getPrice.ts

@@ -1,6 +1,48 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
+// Define cache duration (5 minutes in milliseconds)
+const PRICE_CACHE_DURATION = 5 * 60 * 1000;
+
+// Cache object to store price data
+let cachedPrice: { value: number; timestamp: number } | null = null;
+
+/**
+ * Get the BSV price with caching mechanism
+ * @returns The current BSV price in USD
+ */
+async function getBsvPriceWithCache(): Promise<number> {
+	// Return cached price if it's still valid
+	if (cachedPrice && (Date.now() - cachedPrice.timestamp) < PRICE_CACHE_DURATION) {
+		console.log("Using cached BSV price");
+		return cachedPrice.value;
+	}
+
+	console.log("Fetching fresh BSV price");
+	// If no valid cache, fetch new price
+	const res = await fetch(
+		"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
+	);
+	if (!res.ok) throw new Error("Failed to fetch price");
+	
+	const data = (await res.json()) as {
+		currency: string;
+		rate: string;
+		time: number;
+	};
+	
+	const price = Number(data.rate);
+	if (Number.isNaN(price) || price <= 0) throw new Error("Invalid price received");
+	
+	// Update cache
+	cachedPrice = { 
+		value: price, 
+		timestamp: Date.now() 
+	};
+	
+	return price;
+}
+
 /**
  * Register the BSV price lookup tool
  * @param server The MCP server instance
@@ -14,23 +56,12 @@ export function registerGetPriceTool(server: McpServer): void {
 		},
 		async () => {
 			try {
-				const res = await fetch(
-					"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
-				);
-				if (!res.ok) throw new Error("Failed to fetch price");
-				const data = (await res.json()) as {
-					currency: string;
-					rate: string;
-					time: number;
-				};
-				const price = data.rate;
-				if (typeof price !== "string" && typeof price !== "number")
-					throw new Error("Price not found");
+				const price = await getBsvPriceWithCache();
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Current BSV price: $${Number(price).toFixed(2)} USD`,
+							text: `Current BSV price: $${price.toFixed(2)} USD`,
 						},
 					],
 				};
@@ -43,3 +74,6 @@ export function registerGetPriceTool(server: McpServer): void {
 		},
 	);
 }
+
+// Export the cached price getter for use in other modules
+export { getBsvPriceWithCache };

package/tools/bsv/index.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerDecodeTransactionTool } from "./decodeTransaction";
 import { registerGetPriceTool } from "./getPrice";
+import { registerExploreTool } from "./explore";
 
 /**
  * Register all BSV tools with the MCP server
@@ -10,4 +11,5 @@ export function registerBsvTools(server: McpServer): void {
 	// Register BSV-related tools
 	registerGetPriceTool(server);
 	registerDecodeTransactionTool(server);
+	registerExploreTool(server);
 }

package/tools/wallet/schemas.ts

@@ -72,6 +72,19 @@ export const walletDecryptArgsSchema = z.object({
 	privileged: z.boolean().optional(),
 });
 
+// Combined wallet encryption/decryption args
+export const walletEncryptionArgsSchema = z.object({
+	mode: z.enum(["encrypt", "decrypt"]).describe("Operation mode: 'encrypt' to encrypt data or 'decrypt' to decrypt data"),
+	data: z.array(z.number()).describe("Data to process: plaintext for encryption or ciphertext for decryption"),
+	protocolID: walletProtocolSchema,
+	keyID: z.string(),
+	privilegedReason: z.string().optional(),
+	counterparty: z
+		.union([z.string(), z.literal("self"), z.literal("anyone")])
+		.optional(),
+	privileged: z.boolean().optional(),
+}).describe("Combined schema for encryption and decryption operations, with a mode parameter to switch between functions");
+
 // Create HMAC arguments
 export const createHmacArgsSchema = z.object({
 	message: z.string(),
@@ -296,3 +309,4 @@ export const purchaseListingArgsSchema = z.object({
 // Export types
 export type SendToAddressArgs = z.infer<typeof sendToAddressArgsSchema>;
 export type PurchaseListingArgs = z.infer<typeof purchaseListingArgsSchema>;
+export type WalletEncryptionArgs = z.infer<typeof walletEncryptionArgsSchema>;

package/tools/wallet/sendToAddress.ts

@@ -5,33 +5,7 @@ import { toSatoshi } from "satoshi-token";
 import type { z } from "zod";
 import { sendToAddressArgsSchema } from "./schemas";
 import type { Wallet } from "./wallet";
-
-/**
- * Fetch the current BSV price from whatsonchain API
- * @returns The BSV price in USD
- */
-async function getBsvPrice(): Promise<number> {
-	try {
-		const res = await fetch(
-			"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
-		);
-		if (!res.ok) throw new Error("Failed to fetch BSV price");
-
-		// Parse the response with proper type casting
-		const data = (await res.json()) as {
-			rate: string;
-			currency: string;
-			time: number;
-		};
-		const price = Number(data.rate);
-
-		if (Number.isNaN(price) || price <= 0) throw new Error("Invalid BSV price");
-		return price;
-	} catch (error) {
-		console.error("BSV price fetch error:", error);
-		throw error;
-	}
-}
+import { getBsvPriceWithCache } from "../bsv/getPrice";
 
 // Use the schema imported from schemas.ts
 export type SendToAddressArgs = z.infer<typeof sendToAddressArgsSchema>;
@@ -62,7 +36,7 @@ export function registerSendToAddressTool(server: McpServer, wallet: Wallet) {
 				let satoshis: number;
 				if (currency === "USD") {
 					// Get current BSV price
-					const bsvPriceUsd = await getBsvPrice();
+					const bsvPriceUsd = await getBsvPriceWithCache();
 
 					// Convert USD to BSV
 					const bsvAmount = amount / bsvPriceUsd;

package/tools/wallet/tools.test.ts

@@ -11,15 +11,13 @@ type WalletToolName =
 	| "wallet_getPublicKey"
 	| "wallet_createSignature"
 	| "wallet_verifySignature"
-	| "wallet_encrypt"
-	| "wallet_decrypt";
+	| "wallet_encryption";	
 
 const toolNames: WalletToolName[] = [
 	"wallet_getPublicKey",
 	"wallet_createSignature",
 	"wallet_verifySignature",
-	"wallet_encrypt",
-	"wallet_decrypt",
+	"wallet_encryption",
 ];
 
 // Helper function to get dummy arguments for each tool
@@ -36,10 +34,12 @@ function getDummyArgs(tool: WalletToolName): Record<string, unknown> {
 				signature: "sig",
 				publicKey: "pubkey",
 			};
-		case "wallet_encrypt":
-			return { data: "test", publicKey: "pubkey" };
-		case "wallet_decrypt":
-			return { encryptedData: "data" };
+			// TODO we merged encrypt and decrypt into encryption we need to update the test file
+		// case "wallet_encryption":
+		// 	if 
+		// 	return { data: "test", publicKey: "pubkey" };
+		// case "wallet_decryption":
+		// 	return { encryptedData: "data" };
 		default:
 			return {};
 	}

package/tools/wallet/tools.ts

@@ -31,8 +31,7 @@ import {
 	type purchaseListingArgsSchema,
 	type sendToAddressArgsSchema,
 	verifySignatureArgsSchema,
-	walletDecryptArgsSchema,
-	walletEncryptArgsSchema,
+	walletEncryptionArgsSchema,
 } from "./schemas";
 
 import { registerCreateOrdinalsTool } from "./createOrdinals";
@@ -46,8 +45,7 @@ type ToolArgSchemas = {
 	wallet_getPublicKey: typeof getPublicKeyArgsSchema;
 	wallet_createSignature: typeof createSignatureArgsSchema;
 	wallet_verifySignature: typeof verifySignatureArgsSchema;
-	wallet_encrypt: typeof walletEncryptArgsSchema;
-	wallet_decrypt: typeof walletDecryptArgsSchema;
+	wallet_encryption: typeof walletEncryptionArgsSchema;
 	wallet_listActions: typeof listActionsArgsSchema;
 	wallet_listOutputs: typeof listOutputsArgsSchema;
 	wallet_getNetwork: typeof emptyArgsSchema;
@@ -94,11 +92,12 @@ export function registerWalletTools(
 	// Handle tools registration with properly typed parameters
 	function registerTool<T extends z.ZodType>(
 		name: keyof ToolArgSchemas,
+		description: string,
 		schema: { args: T },
 		handler: ToolCallback<{ args: T }>,
 	): void {
 		// Register all tools normally
-		server.tool(name, schema, handler);
+		server.tool(name, description, schema, handler);
 		handlers[name] = handler as ToolHandler;
 	}
 
@@ -117,6 +116,7 @@ export function registerWalletTools(
 	// Register wallet_getPublicKey
 	registerTool(
 		"wallet_getPublicKey",
+		"Retrieves the current wallet's public key. This public key can be used for cryptographic operations like signature verification or encryption.",
 		{ args: getPublicKeyArgsSchema },
 		async (
 			{ args }: { args: z.infer<typeof getPublicKeyArgsSchema> },
@@ -135,6 +135,7 @@ export function registerWalletTools(
 	// Register wallet_createSignature
 	registerTool(
 		"wallet_createSignature",
+		"Creates a cryptographic signature using the wallet's private key. This tool enables secure message signing and transaction authorization, supporting various signature protocols.",
 		{ args: createSignatureArgsSchema },
 		async (
 			{ args }: { args: z.infer<typeof createSignatureArgsSchema> },
@@ -153,6 +154,7 @@ export function registerWalletTools(
 	// Register wallet_verifySignature
 	registerTool(
 		"wallet_verifySignature",
+		"Verifies a cryptographic signature against a message or data. This tool supports various verification protocols and can validate signatures from both the wallet's own keys and external public keys.",
 		{ args: verifySignatureArgsSchema },
 		async (
 			{ args }: { args: z.infer<typeof verifySignatureArgsSchema> },
@@ -168,16 +170,38 @@ export function registerWalletTools(
 		},
 	);
 
-	// Register wallet_encrypt
+	// Register combined wallet_encryption tool
 	registerTool(
-		"wallet_encrypt",
-		{ args: walletEncryptArgsSchema },
+		"wallet_encryption",
+		"Combined tool for encrypting and decrypting data using the wallet's cryptographic keys. Supports both encryption of plaintext data and decryption of previously encrypted content. Use the 'mode' parameter to switch between operations.",
+		{ args: walletEncryptionArgsSchema },
 		async (
-			{ args }: { args: z.infer<typeof walletEncryptArgsSchema> },
+			{ args }: { args: z.infer<typeof walletEncryptionArgsSchema> },
 			extra: RequestHandlerExtra,
 		) => {
 			try {
-				const result = await wallet.encrypt(args);
+				let result: { ciphertext?: number[]; plaintext?: number[] };
+				if (args.mode === "encrypt") {
+					// For encryption, the data is treated as plaintext
+					result = await wallet.encrypt({
+						plaintext: args.data,
+						protocolID: args.protocolID,
+						keyID: args.keyID,
+						privilegedReason: args.privilegedReason,
+						counterparty: args.counterparty,
+						privileged: args.privileged,
+					});
+				} else {
+					// For decryption, the data is treated as ciphertext
+					result = await wallet.decrypt({
+						ciphertext: args.data,
+						protocolID: args.protocolID,
+						keyID: args.keyID,
+						privilegedReason: args.privilegedReason,
+						counterparty: args.counterparty,
+						privileged: args.privileged,
+					});
+				}
 				return { content: [{ type: "text", text: JSON.stringify(result) }] };
 			} catch (err: unknown) {
 				const msg = err instanceof Error ? err.message : String(err);
@@ -186,27 +210,8 @@ export function registerWalletTools(
 		},
 	);
 
-	// Register wallet_decrypt
-	registerTool(
-		"wallet_decrypt",
-		{ args: walletDecryptArgsSchema },
-		async (
-			{ args }: { args: z.infer<typeof walletDecryptArgsSchema> },
-			extra: RequestHandlerExtra,
-		) => {
-			try {
-				const result = await wallet.decrypt(args);
-				return { content: [{ type: "text", text: JSON.stringify(result) }] };
-			} catch (err: unknown) {
-				const msg = err instanceof Error ? err.message : String(err);
-				return { content: [{ type: "text", text: msg }], isError: true };
-			}
-		},
-	);
-
-	// Register ordinals extension tools
-	// Register the wallet_createOrdinals tool
+	// Register createOrdinals tool
 	registerCreateOrdinalsTool(server, wallet);
-
+	
 	return handlers;
 }

package/tools/wallet/wallet.ts

@@ -38,6 +38,7 @@ import type {
 	ListOutputsResult,
 	ProveCertificateArgs,
 	ProveCertificateResult,
+	PubKeyHex,
 	RelinquishCertificateArgs,
 	RelinquishCertificateResult,
 	RelinquishOutputArgs,
@@ -127,7 +128,15 @@ export class Wallet extends ProtoWallet implements WalletInterface {
 	}
 
 	async getPublicKey(args: GetPublicKeyArgs): Promise<GetPublicKeyResult> {
-		return Promise.reject(new Error("Not implemented"));
+		const privateKey = this.getPrivateKey();
+		if (!privateKey) {
+			throw new Error("No private key available");
+		}
+		
+		const publicKey = privateKey.toPublicKey();
+		return {
+			publicKey: publicKey.toDER("hex") as PubKeyHex,
+		};
 	}
 	async revealCounterpartyKeyLinkage(
 		args: RevealCounterpartyKeyLinkageArgs,