Ethereum API Reference

This document describes the native Ethereum API methods that are supported by Coinbase Node.

Servers

The Ethereum API supports the following blockchain networks:

Name	Endpoint
Ethereum Mainnet	https://mainnet.ethereum.coinbasecloud.net
Goerli Testnet	https://goerli.ethereum.coinbasecloud.net

Authentication:

This endpoint uses HTTP Basic Auth.

To authenticate to this API:

• Create a project in the Coinbase Cloud Console
• Grab your project-specific API Access Token username and password from the project overview page
• Include your username and password as auth in each HTTP request

Methods

web3_clientVersion

Gets the version of the current client.

Parameters

None

Returns

Type	Description
String	The client version.

net_version

Gets the network ID associated with the network.

Parameters

None

Returns

Type	Description
String	The network ID associated with the network.

eth_blockNumber

Gets the number of most recent block.

Parameters

None

Returns

Type	Description
String	The block number.

eth_call

Executes a new message call (locally) immediately without creating a transaction on the block chain.

Parameters

Name	Type	Description
transaction	Transaction	REQUIRED. The transaction.
blockNumber	String	REQUIRED. The block number.

Returns

Type	Description
String	The return value of the executed contract.

eth_chainId

Gets the currently configured chain ID, a value used in replay-protected transaction signing as introduced by EIP-155.

Parameters

None

Returns

Type	Description
String	Hex format integer of the current chain ID. Defaults are ETC=61, ETH=1, Morden=62.

eth_estimateGas

Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance.

Parameters

Name	Type	Description
transaction	Transaction	REQUIRED. The transaction.

Returns

Type	Description
String	The amount of gas used.

eth_feeHistory

Gets transaction base fee per gas and effective priority fee per gas for the requested/supported block range.

Parameters

Name	Type	Description
blockCount	String	REQUIRED. Requested range of blocks. Clients will return less than the requested range if not all blocks are available.
newestBlock	String	REQUIRED. Highest block of the requested range.
rewardPercentiles	Number[]	REQUIRED. A monotonically increasing list of percentile values. For each block in the requested range, the transactions will be sorted in ascending order by effective tip per gas and the coresponding effective tip for the percentile will be determined, accounting for gas consumed.

Returns

Type	Description
FeeHistoryResults	Fee history for the returned block range. This can be a subsection of the requested range if not all blocks are available.

eth_gasPrice

Gets the current price per gas in wei

Parameters

None

Returns

Type	Description
String	Integer of the current gas price in wei.

eth_getCode

Gets code at a given contract address

Parameters

Name	Type	Description
address	String	REQUIRED. The address of the contract.
blockNumber	String	A BlockNumber of which the code existed.

Returns

Type	Description
String	The code from the given address.

eth_getBalance

Gets Ether balance of a given or account or contract.

Parameters

Name	Type	Description
address	String	REQUIRED. The address of the account or contract.
blockNumber	String	A BlockNumber at which to request the balance.

Returns

Type	Description
String | Null	Integer of the current balance in wei or null.

eth_getBlockByHash

Gets a block for a given hash.

Parameters

Name	Type	Description
blockHash	String	REQUIRED. The hash of a block.
includeTransactions	Boolean	REQUIRED. If true it returns the full transaction objects, if false only the hashes of the transactions.

Returns

Type	Description
Block | Null	The block, or null when no block is found.

eth_getBlockByNumber

Gets a block for a given number.

Parameters

Name	Type	Description
blockNumber	String	REQUIRED. The block number.
includeTransactions	Boolean	REQUIRED. If true it returns the full transaction objects, if false only the hashes of the transactions.

Returns

Type	Description
Block | Null	The block, or null when no block is found.

eth_getBlockTransactionCountByHash

Gets the number of transactions in a block from a block matching the given block hash.

Parameters

Name	Type	Description
blockHash	String	REQUIRED. The hex representation of the Keccak 256 of the RLP encoded block.

Returns

Type	Description
String | Null	The number of total transactions in the given block, or null.

eth_getBlockTransactionCountByNumber

Gets the number of transactions in a block from a block matching the given block number.

Parameters

Name	Type	Description
blockNumber	String	REQUIRED. The block number.

Returns

Type	Description
String | Null	The number of total transactions in the given block, or null.

eth_getLogs

Gets an array of all logs matching a given filter object. Block range must be less than 2,000 blocks.

Parameters

Name	Type	Description
filter	Filter	REQUIRED. A filter used to monitor the blockchain for log/events. Block range must be less than 2,000 blocks.

Returns

Type	Description
Log[]	An array of all logs matching filter with given id.

eth_getTransactionByBlockHashAndIndex

Gets the information about a transaction requested by the block hash and index of which it was mined.

Parameters

Name	Type	Description
blockHash	String	REQUIRED. The hex representation of the Keccak 256 of the RLP encoded block.
index	String	REQUIRED. The ordering in which a transaction is mined within its block.

Returns

Type	Description
Transaction | Null	A transaction or null.

Examples

Null Example

cURL

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByBlockHashAndIndex",
  "params": {
    "blockHashExample": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "indexExample": "0x0"
  }
}'

Request (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByBlockHashAndIndex",
  "params": {
    "blockHashExample": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "indexExample": "0x0"
  }
}

Response (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": null
}

eth_getTransactionByBlockNumberAndIndex

Gets the information about a transaction requested by the block number and index of which it was mined.

Parameters

Name	Type	Description
blockNumber	String	REQUIRED. The block number.
index	String	REQUIRED. The ordering in which a transaction is mined within its block.

Returns

Type	Description
Transaction | Null	A transaction or null.

eth_getTransactionByHash

Gets the information about a transaction requested by transaction hash.

Parameters

Name	Type	Description
transactionHash	String	REQUIRED. Keccak 256 Hash of the RLP encoding of a transaction.

Returns

Type	Description
Transaction | Null	A transaction or null.

eth_getTransactionCount

Gets the number of transactions sent from an address.

Parameters

Name	Type	Description
address	String	REQUIRED. An address.
blockNumber	String	REQUIRED. The block number.

Returns

Type	Description
String | Null	The number of transactions send from the given address, or null.

eth_getTransactionReceipt

Gets the receipt information of a transaction by its hash.

Parameters

Name	Type	Description
transactionHash	String	REQUIRED. Keccak 256 Hash of the RLP encoding of a transaction.

Returns

Type	Description
Receipt | Null	A receipt or null.

eth_getUncleByBlockHashAndIndex

Gets information about a uncle of a block by hash and uncle index position.

Parameters

Name	Type	Description
blockHash	String	REQUIRED. The hex representation of the Keccak 256 of the RLP encoded block.
index	String	REQUIRED. The ordering in which a uncle is included within its block.

Returns

Type	Description
Block | Null	The uncle block, or null when no block is found.

eth_getUncleByBlockNumberAndIndex

Gets information about a uncle of a block by hash and uncle index position.

Parameters

Name	Type	Description
uncleBlockNumber	String	REQUIRED. The block in which the uncle was included.
index	String	REQUIRED. The ordering in which a uncle is included within its block.

Returns

Type	Description
Block | Null	The uncle block, or null when no block is found.

Examples

Null Example

cURL

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getUncleByBlockNumberAndIndex",
  "params": {
    "uncleBlockNumberExample": "0x0",
    "uncleBlockNumberIndexExample": "0x0"
  }
}'

Request (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getUncleByBlockNumberAndIndex",
  "params": {
    "uncleBlockNumberExample": "0x0",
    "uncleBlockNumberIndexExample": "0x0"
  }
}

Response (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": null
}

eth_getUncleCountByBlockHash

Gets the number of uncles in a block from a block matching the given block hash.

Parameters

Name	Type	Description
blockHash	String	REQUIRED. The hex representation of the Keccak 256 of the RLP encoded block.

Returns

Type	Description
String | Null	The number of total uncles in the given block, or null.

eth_getUncleCountByBlockNumber

Gets the number of uncles in a block from a block matching the given block number.

Parameters

Name	Type	Description
blockNumber	String	REQUIRED. The block number.

Returns

Type	Description
String | Null	The Number of total uncles in the given block.

eth_protocolVersion

Gets the current Ethereum protocol version.

Parameters

None

Returns

Type	Description
String	The current Ethereum protocol version.

eth_sendRawTransaction

Creates new message call transaction or a contract creation for signed transactions.

Parameters

Name	Type	Description
signedTransactionData	String	REQUIRED. The signed transaction data

Returns

Type	Description
String	The transaction hash, or the zero hash if the transaction is not yet available.

eth_syncing

Gets an object with data about the sync status or false.

Parameters

None

Returns

Type	Description
SyncingData | Boolean	An object with sync status data, or false when not syncing.

Types

Transaction

Properties

Name	Type	Description
blockHash	String | Null	The block hash or null when its the pending block.
blockNumber	String | Null	The block number or null when its the pending block
from	String	The origin address of the transaction.
gas	String	REQUIRED. The gas limit provided by the sender in Wei.
gasPrice	String	REQUIRED. The gas price willing to be paid by the sender in Wei.
hash	String	Keccak 256 Hash of the RLP encoding of a transaction.
data	String	Hash of the method signature and encoded parameters. See the Ethereum contract ABI specification.
nonce	String	REQUIRED. The total number of prior transactions made by the sender.
to	String | Null	The destination address of the transaction. null if it was a contract create.
transactionIndex	String | Null	The index of the transaction. null when its pending.
value	String	Value of Ether being transferred in Wei.
v	String	ECDSA recovery id.
r	String	ECDSA signature r.
s	String	ECDSA signature s.

FeeHistoryResults

Properties

Name	Type	Description
oldestBlock	String	Lowest number block of returned range.
baseFeePerGas	String[]	REQUIRED. An array of block base fees per gas. This includes the next block after the newest of the returned range, because this value can be derived from the newest block. Zeroes are returned for pre-EIP-1559 blocks.
reward	String[][]	A two-dimensional array of effective priority fees per gas at the requested block percentiles.

Block

Properties

Name	Type	Description
number	String | Null	The block number or null when its the pending block.
hash	String | Null	The block hash or null when its the pending block.
parentHash	String	Keccak hash of the parent block.
nonce	String | Null	Randomly selected number to satisfy the proof-of-work or null when its the pending block
sha3Uncles	String	Keccak hash of the uncles data in the block.
logsBloom	String	The bloom filter for the logs of the block or null when its the pending block.
transactionsRoot	String	The root of the transactions trie of the block.
stateRoot	String	The root of the final state trie of the block
receiptsRoot	String	The root of the receipts trie of the block
miner	String | Null	The address of the miner, or null.
difficulty	String	Integer of the difficulty for this block.
totalDifficulty	String | Null	Integer of the total difficulty of the chain until this block, or null.
extraData	String	The 'extra data' field of this block.
size	String	Integer the size of this block in bytes.
gasLimit	String	The maximum gas allowed in this block.
gasUsed	String	The total used gas by all transactions in this block.
timestamp	String	The unix timestamp for when the block was collated.
transactions	Transaction | String[]	Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter.
uncles	String[]	Array of uncle hashes.

Filter

Properties

Name	Type	Description
fromBlock	String	The block number for the start block of the block range.
toBlock	String	The block number for the end block of the block range.
address	String | String[]	An address or list of addresses.
topics	String[]	Topics are order-dependent. Each topic can also be an array of DATA with 'or' options.

Log

Properties

Name	Type	Description
address	String	Sender of the transaction.
blockHash	String	The hex representation of the Keccak 256 of the RLP encoded block.
blockNumber	String	The hex representation of the block's height.
data	String	The data/input string sent along with the transaction.
logIndex	String	The index of the event within its transaction, null when its pending.
removed	Boolean	Whether or not the log was orphaned off the main chain.
topics	String[]	Topics are order-dependent. Each topic can also be an array of DATA with 'or' options.
transactionHash	String	Keccak 256 Hash of the RLP encoding of a transaction.
transactionIndex	String | Null	The index of the transaction. null when its pending.

Receipt

Properties

Name	Type	Description
blockHash	String	REQUIRED. The hex representation of the Keccak 256 of the RLP encoded block.
blockNumber	String	REQUIRED. The hex representation of the block's height.
contractAddress	String | Null	REQUIRED. The contract address created, if the transaction was a contract creation, otherwise null.
cumulativeGasUsed	String	REQUIRED. The gas units used by the transaction.
from	String	REQUIRED. The sender of the transaction.
gasUsed	String	REQUIRED. The total gas used by the transaction.
logs	Log[]	REQUIRED. An array of all the logs triggered during the transaction.
logsBloom	String	REQUIRED. A 2048 bit bloom filter from the logs of the transaction. Each log sets 3 bits though taking the low-order 11 bits of each of the first three pairs of bytes in a Keccak 256 hash of the log's byte series
to	String | Null	REQUIRED. Destination address of the transaction. Null if it was a contract create.
transactionHash	String	REQUIRED. Keccak 256 Hash of the RLP encoding of a transaction.
transactionIndex	String | Null	REQUIRED. The index of the transaction. null when its pending.
postTransactionState	String	The intermediate stateRoot directly after transaction execution.
status	Boolean	Whether or not the transaction threw an error.

SyncingData

Properties

Name	Type	Description
startingBlock	String	Block at which the import started (will only be reset, after the sync reached his head).
currentBlock	String	The current block, same as eth_blockNumber.
highestBlock	String	The estimated highest block.
knownStates	String	The known states.
pulledStates	String	The pulled states.