EVM API Controllers

Purpose

The EVM API Controllers provide a specialized RESTful interface tailored for Ethereum and EVM-compatible blockchains. This subtopic addresses the need for standardized access to blockchain account data, transaction history, transaction broadcasting, gas fee estimation, and token metadata retrieval specifically for EVM-based networks. It solves the challenge of abstracting complex node and indexer interactions into a clean, consistent API that clients can easily consume.

Unlike the broader Unified API Layer that covers multiple blockchain architectures, the EVM API Controllers focus on EVM-specific data structures, RPC methods, and workflows such as handling internal transactions traced via node debug APIs and ERC token standards (ERC20, ERC721, ERC1155). This specialization enables richer and more accurate data representations for Ethereum-like chains.

Functionality

The EVM API Controllers expose a set of key endpoints managing common EVM operations:

The controller methods delegate core logic to a dedicated service class that orchestrates data retrieval from the Blockbook indexer, Ethereum node RPC, external explorer APIs, and token contracts. This separation ensures clean API routing while encapsulating complex data processing within the service layer.

Key Workflow Highlights

Integration

This subtopic is a specialized extension of the Unified API Layer, tailored explicitly for EVM-compatible blockchains. It complements sibling API subtopics like the UTXO API Controllers by handling the unique account and transaction models of Ethereum-like chains.

The controllers rely on shared common API interfaces and utilities but implement EVM-specific models, validation, and error handling. They integrate tightly with:

This layered integration ensures the EVM API Controllers provide the richest possible data and interaction surface for Ethereum-like chains while maintaining consistent API contracts within the broader platform.

Code Snippet Illustrations

Controller Method Example: Getting Account Details

@Get('account/{pubkey}')
async getAccount(@Path() pubkey: string): Promise<Account> {
  return EVM.service.getAccount(pubkey)
}

This endpoint delegates to the service's `getAccount` method, which fetches balances and tokens via Blockbook.

Service Method Example: Fetching and Formatting Account Tokens

const tokens = (data.tokens ?? []).reduce<Array<TokenBalance>>((prev, token) => {
  if (token.balance && token.contract) {
    prev.push({ balance: token.balance, contract: token.contract, decimals: token.decimals ?? 0, ... })
  }
  token.ids?.forEach(id => { ... })       // ERC721 token handling
  token.multiTokenValues?.forEach(multiToken => { ... }) // ERC1155 multi-token handling

  return prev
}, [])

The service normalizes multiple token standards into a unified token balance list.

Service Method Example: Sending a Raw Transaction

const request: RPCRequest = {
  jsonrpc: '2.0',
  id: rpcId(),
  method: 'eth_sendRawTransaction',
  params: [body.hex],
}

const { data } = await axiosNoRetry.post<RPCResponse>(this.rpcUrl, request, config)

Raw transaction hex is broadcast via JSON-RPC to the node.

Diagram: EVM API Controller Workflow for Transaction History Retrieval

sequenceDiagram
    participant Client
    participant EVM_API_Controller
    participant Service
    participant Blockbook
    participant Explorer_API
    participant Ethereum_Node

    Client->>EVM_API_Controller: GET /account/{address}/txs
    EVM_API_Controller->>Service: getTxHistory(address, cursor, pageSize, from, to)
    Service->>Blockbook: Fetch transactions page
    Blockbook-->>Service: Return transactions
    Service->>Explorer_API: Fetch internal txs page
    Explorer_API-->>Service: Return internal txs
    alt Node tracing enabled and recent txs
      Service->>Ethereum_Node: debug_traceTransaction / trace_transaction
      Ethereum_Node-->>Service: Return internal txs
    end
    Service->>EVM_API_Controller: Merge & format txs + internal txs + cursor
    EVM_API_Controller->>Client: Return paginated TxHistory response

This sequence illustrates how the controller requests transaction history and internal transactions from multiple sources, merges results, and returns a comprehensive response to the client.

This subtopic enriches the Unified API Layer by providing EVM-specific blockchain data access and operations, enabling clients to interact with Ethereum and compatible chains efficiently and with detailed insights into on-chain activity.