Reference

JSON-RPC API

Standard Ethereum JSON-RPC 2.0 over HTTPS. One endpoint per chain. Compatible with ethers.js, viem, web3.js, and any EVM toolchain.

Endpoint

HTTP method

POST https://rpc.kubernodes.com/{chainSlug}

Headers

X-API-Key: pk_live_YOUR_KEY
Content-Type: application/json

Authentication

Pass your API key in the X-API-Key header. Keys are prefixed pk_live_ for production and pk_test_ for test environment.

curl

curl -X POST https://rpc.kubernodes.com/eth \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Request format

{
  "jsonrpc": "2.0",
  "method":  "eth_getBalance",
  "params":  ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96044", "latest"],
  "id":      1
}

id can be any string or number — it is echoed back unchanged in the response.

Batch requests

Send an array to execute multiple calls in a single HTTP round trip. Responses are returned as an array in the same order.

curl -X POST https://rpc.kubernodes.com/eth-mainnet \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1},
    {"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":2}
  ]'

// Response:
[
  {"jsonrpc":"2.0","id":1,"result":"0x14aB4F2"},
  {"jsonrpc":"2.0","id":2,"result":"0x5D21DBA00"}
]

Supported methods

eth_blockNumber

Returns the current block number.

params

[]

result

"0x14aBcD5" // hex block number

eth_getBalance

Returns the balance in wei for an address at a given block.

params

["0xAddress", "latest"]

result

"0x14aBcD5" // wei as hex

eth_gasPrice

Returns the current gas price in wei.

params

[]

result

"0x5d21dba00" // hex wei

eth_maxPriorityFeePerGas

Returns the current max priority fee (tip) per gas. EIP-1559 chains only.

params

[]

result

"0x3b9aca00"

eth_getTransactionCount

Returns the number of transactions from an address (the nonce for its next tx).

params

["0xAddress", "latest"]

result

"0x2a" // hex nonce

eth_getBlockByNumber

Returns a block by number. Pass true as the second param for full Transaction objects.

params

["latest", false]

result

{ number, hash, transactions: ["0x..."], ... }

eth_getBlockByHash

Returns a block by hash.

params

["0xBlockHash", false]

result

{ number, hash, ... }

eth_getTransactionByHash

Returns a transaction by hash. Returns null if not found.

params

["0xTxHash"]

result

{ hash, from, to, value, input, ... } | null

eth_getTransactionReceipt

Returns the receipt for a mined transaction. Returns null if still pending.

params

["0xTxHash"]

result

{ status: "0x1", blockNumber, gasUsed, logs, ... } | null

eth_call

Executes a message call (no state change). Used for contract reads.

params

[{ "to": "0x...", "data": "0x..." }, "latest"]

result

"0x000...result" // ABI-encoded hex

eth_estimateGas

Estimates gas for a transaction. Reverts if the tx would fail.

params

[{ "to": "0x...", "data": "0x..." }]

result

"0x5208" // 21000 for plain ETH transfer

eth_getLogs

Returns logs matching a filter. Use blockHash OR fromBlock+toBlock, not both.

params

[{ "address": "0x...", "topics": ["0x..."], "fromBlock": "0xEC4E20" }]

result

[{ address, topics, data, blockNumber, transactionHash, logIndex, removed }, ...]

eth_sendRawTransaction

Broadcasts a signed transaction. Returns the transaction hash immediately (before mining).

params

["0x02f8...signedTxHex"]

result

"0xTxHash"

eth_chainId

Returns the chain ID as hex.

params

[]

result

"0x1" // Ethereum mainnet

eth_getCode

Returns the bytecode at a contract address. Returns "0x" for EOA addresses.

params

["0xContractAddress", "latest"]

result

"0x6060..." // deployed bytecode

eth_getStorageAt

Returns the value at a storage slot for a contract.

params

["0xContractAddress", "0x0", "latest"]

result

"0x000...value"

net_version

Returns the network ID as a string.

params

[]

result

"1"

Errors

Standard JSON-RPC errors use the error field instead of result. HTTP-level errors (401, 404, 429) are also returned.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: expected 2 arguments"
  }
}

Code	Name	Description
-32700	Parse error	Request body is not valid JSON.
-32600	Invalid Request	JSON-RPC envelope is malformed (missing jsonrpc, method, or id).
-32601	Method not found	The requested RPC method is not supported.
-32602	Invalid params	Method params are the wrong type or count.
-32603	Internal error	Upstream node returned an unexpected error.
3	Execution reverted	Smart contract call reverted. data field contains revert reason.
401	Unauthorized	Missing or invalid X-API-Key.
429	Rate limited	Request limit exceeded. Retry after the value in Retry-After header.
404	Chain not found	The chain slug in the URL is not recognized.

Use with ethers.js / viem

ethers.js v6

import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(
  "https://rpc.kubernodes.com/eth-mainnet",
  undefined,
  { headers: { "X-API-Key": process.env.KN_API_KEY } }
);

const block = await provider.getBlockNumber();

viem

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({
  chain: mainnet,
  transport: http("https://rpc.kubernodes.com/eth-mainnet", {
    fetchOptions: { headers: { "X-API-Key": process.env.KN_API_KEY } },
  }),
});

const block = await client.getBlockNumber();

← Supported Chains SDK Reference →