Blockscope API

Comprehensive blockchain data querying for Bitcoin, Ethereum, and Tron

API Documentation

Find Transaction

Retrieves transaction details by providing a transaction hash or a list of transaction hashes.

Endpoint

GET /tx/{hashes}

Example Requests

curl -X GET "https://blockscope.pro/api/tx/0x0e2dc0cc3b85613860234b17473d0ce3f049a6f5ebcdbada74d16e4de6fd6103"

Response Structure

The response is an array of transaction objects. Each transaction object contains the following fields:

  • chain: The blockchain identifier (e.g., 1 for Ethereum).
  • fee: The transaction fee details.
  • balanceChanges: An array of balance changes resulting from the transaction.
  • hash: The transaction hash.
  • time: The timestamp of the transaction in seconds.
  • block_height: The block height in which the transaction was included.

Find Block

Retrieves block details by providing the blockchain identifier and block height(s).

Endpoint

GET /block/{chain}/{heights}

Parameters

  • {chain}: The blockchain identifier (btc, eth, or trx).
  • {heights}: A single block height or a comma-separated list of block heights.

Optional Query Parameters

  • full: true or false. If true, the transactions field will include full transaction details. Default is false.
  • fill_tx_hashes: true or false. If true, the transactionHashes field will be populated. Default is false.
  • limit: Limits the number of transactions returned. Default is 10,000.
  • offset: Pagination offset. Default is 0.

Example Requests

curl -X GET "https://blockscope.pro/api/block/btc/1?full=true&fill_tx_hashes=true&limit=100&offset=0"

Response Structure

The response is an array of block objects. Each block object contains the following fields:

  • block_confirmations: The number of confirmations for the block.
  • block_height: The block height.
  • block_time: The block timestamp in seconds.
  • block_size: The size of the block in bytes.
  • txCount: The number of transactions in the block.
  • transactions: An array of transaction objects (only populated if full=true).
  • transactionHashes: An array of transaction hashes (only populated if fill_tx_hashes=true).
  • block_specific: Blockchain-specific details.

Find Address

Retrieves the balance and transaction history for a given address.

Endpoint

GET /address/{address}

Parameters

{address}: The blockchain address to query.

Optional Query Parameters

  • only_tokens: true or false. If true, only token transactions (ERC20, TRC20, etc.) are returned. Default is false.
  • beforeTs: Timestamp in seconds. Returns transactions before this timestamp.
  • afterTs: Timestamp in seconds. Returns transactions after this timestamp.
  • offset: Pagination offset.
  • limit: Pagination limit.

Example Requests

curl -X GET "https://blockscope.pro/api/address/0x0854d862Eec294996DfF9d12da1Fe6DDdf46b549?only_tokens=true&beforeTs=1625097600&afterTs=1609459200&offset=0&limit=50"

Response Structure

The response contains the following fields:

  • find_tx_by_address: An object containing:
    • txs: An array of transaction objects (same structure as in Find Transaction by Hash).
    • total: The total number of transactions.
    • balances: An array of balance objects.

MCP Server

MCP Server for Blockscope Protocol

The Model Context Protocol (MCP) is a protocol that allows Language Models (LLMs) like Claude to interact with external tools and services. By exposing tools via MCP, LLMs can perform complex operations, such as querying blockchain data, computing checksums, or interacting with APIs, and return the results seamlessly to the user.

This document describes how to deploy an MCP server that exposes the Blockscope Protocol, enabling LLMs to query blockchain data (e.g., Bitcoin, Ethereum, Tron) for transactions, blocks, and address balances.

Blockscope MCP Server

The Blockscope MCP server exposes the following tools to LLMs:

  1. Find Transaction by Hash: Retrieves transaction details by hash.
  2. Find Block by Height and Chain: Retrieves block details by height and blockchain.
  3. Find Address Balance and Transactions: Retrieves balance and transaction history for a given address.
package main

import (
	"errors"
	"fmt"
	"net/http"
	"encoding/json"

	"github.com/acrmp/mcp"
	"golang.org/x/time/rate"
)

func main() {
	serverInfo := mcp.Implementation{
		Name:    "BlockscopeServer",
		Version: "1.0.0",
	}

	// Define tools
	tools := []mcp.ToolDefinition{
		{
			Metadata: mcp.Tool{
				Name:        "find_transaction_by_hash",
				Description: strPtr("Retrieve transaction details by hash"),
				InputSchema: mcp.ToolInputSchema{
					Type: "object",
					Properties: mcp.ToolInputSchemaProperties{
						"hash": map[string]any{
							"type":        "string",
							"description": "Transaction hash",
						},
					},
					Required: []string{"hash"},
				},
			},
			Execute:   findTransactionByHash,
			RateLimit: rate.NewLimiter(10, 1),
		},
		{
			Metadata: mcp.Tool{
				Name:        "find_block_by_height_and_chain",
				Description: strPtr("Retrieve block details by height and chain"),
				InputSchema: mcp.ToolInputSchema{
					Type: "object",
					Properties: mcp.ToolInputSchemaProperties{
						"chain": map[string]any{
							"type":        "string",
							"description": "Blockchain identifier (btc, eth, trx)",
						},
						"height": map[string]any{
							"type":        "integer",
							"description": "Block height",
						},
					},
					Required: []string{"chain", "height"},
				},
			},
			Execute:   findBlockByHeightAndChain,
			RateLimit: rate.NewLimiter(10, 1),
		},
		{
			Metadata: mcp.Tool{
				Name:        "find_address_balance_and_transactions",
				Description: strPtr("Retrieve address balance and transaction history"),
				InputSchema: mcp.ToolInputSchema{
					Type: "object",
					Properties: mcp.ToolInputSchemaProperties{
						"address": map[string]any{
							"type":        "string",
							"description": "Blockchain address",
						},
					},
					Required: []string{"address"},
				},
			},
			Execute:   findAddressBalanceAndTransactions,
			RateLimit: rate.NewLimiter(10, 1),
		},
	}

	// Start MCP server
	s := mcp.NewServer(serverInfo, tools)
	s.Serve()
}

// Helper function to create string pointers
func strPtr(s string) *string {
	return &s
}

// Tool: Find Transaction by Hash
func findTransactionByHash(params mcp.CallToolRequestParams) (mcp.CallToolResult, error) {
	hash := params.Arguments["hash"].(string)

	if len(hash) == 0 {
		return mcp.CallToolResult{}, errors.New("transaction hash cannot be empty")
	}

	// Call Blockscope API
	resp, err := http.Get(fmt.Sprintf("https://blockscope.pro/api/tx/%s", hash))
	if err != nil {
		return mcp.CallToolResult{}, fmt.Errorf("failed to fetch transaction: %v", err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return mcp.CallToolResult{}, fmt.Errorf("failed to decode response: %v", err)
	}

	var noError bool
	return mcp.CallToolResult{
		Content: []any{
			mcp.TextContent{
				Type: "text",
				Text: fmt.Sprintf("Transaction details: %v", result),
			},
		},
		IsError: &noError,
	}, nil
}

// Tool: Find Block by Height and Chain
func findBlockByHeightAndChain(params mcp.CallToolRequestParams) (mcp.CallToolResult, error) {
	chain := params.Arguments["chain"].(string)
	height := int(params.Arguments["height"].(float64))

	if len(chain) == 0 || height <= 0 {
		return mcp.CallToolResult{}, errors.New("invalid chain or height")
	}

	// Call Blockscope API
	resp, err := http.Get(fmt.Sprintf("https://blockscope.pro/api/block/%s/%d", chain, height))
	if err != nil {
		return mcp.CallToolResult{}, fmt.Errorf("failed to fetch block: %v", err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return mcp.CallToolResult{}, fmt.Errorf("failed to decode response: %v", err)
	}

	var noError bool
	return mcp.CallToolResult{
		Content: []any{
			mcp.TextContent{
				Type: "text",
				Text: fmt.Sprintf("Block details: %v", result),
			},
		},
		IsError: &noError,
	}, nil
}

// Tool: Find Address Balance and Transactions
func findAddressBalanceAndTransactions(params mcp.CallToolRequestParams) (mcp.CallToolResult, error) {
	address := params.Arguments["address"].(string)

	if len(address) == 0 {
		return mcp.CallToolResult{}, errors.New("address cannot be empty")
	}

	// Call Blockscope API
	resp, err := http.Get(fmt.Sprintf("https://blockscope.pro/api/address/%s", address))
	if err != nil {
		return mcp.CallToolResult{}, fmt.Errorf("failed to fetch address data: %v", err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return mcp.CallToolResult{}, fmt.Errorf("failed to decode response: %v", err)
	}

	var noError bool
	return mcp.CallToolResult{
		Content: []any{
			mcp.TextContent{
				Type: "text",
				Text: fmt.Sprintf("Address details: %v", result),
			},
		},
		IsError: &noError,
	}, nil
}

Deployment Documentation

Step 1: Build the Server

  1. Navigate to the directory containing the server code.
  2. Build the server binary for your platform:
GOOS=darwin GOARCH=arm64 go build -o blockscope-mcp-server

Replace `darwin` and `arm64` with your target OS and architecture.

Step 2: Add the Server to Claude Config

  1. Open the Claude configuration file:
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
  1. Add the Blockscope MCP server configuration:
{
  "mcpServers": {
    "blockscope": {
      "command": "/path/to/blockscope-mcp-server"
    }
  }
}

Replace `/path/to/blockscope-mcp-server` with the full path to the server binary.

Step 3: Interact with Blockscope via Claude

You can now ask Claude to query blockchain data using the Blockscope tools. For example:

Find Transaction by Hash:

What are the details of the transaction with hash `0x0e2dc0cc3b85613860234b17473d0ce3f049a6f5ebcdbada74d16e4de6fd6103`?

Find Block by Height and Chain:

What are the details of block height `1` on the Bitcoin blockchain?

Find Address Balance and Transactions:

What is the balance and transaction history of address `0x0854d862Eec294996DfF9d12da1Fe6DDdf46b549`?

Claude will use the Blockscope MCP server to fetch the requested data and return it in a user-friendly format.

Error Codes

List of possible error codes and their meanings.

Common Error Codes

  • 400: Bad Request - The request was invalid or cannot be served.
  • 401: Unauthorized - The request requires authentication.
  • 403: Forbidden - The server understood the request but refuses to authorize it.
  • 404: Not Found - The requested resource could not be found.
  • 429: Too Many Requests - You have sent too many requests in a given amount of time.
  • 500: Internal Server Error - We had a problem with our server.

If you have any questions about these error codes or need further assistance, please don't hesitate to contact us.