Metal JSON-RPC

Metal exposes Ethereum JSON-RPC over HTTP with targeted overrides for MIP20 gas and additive methods for finality, retained blob sidecars, node metadata, and MIP20 diagnostics. The method pages in this tab document each method and send real requests to Metal’s public endpoints.

Choose a network

Every method page has a server selector with both networks:

Network	RPC URL	Chain ID
Testnet	`https://rpc-testnet.metalntwx.com/v1/<endpoint-id>`	`0xf951` (63825)
Devnet	`https://rpc-devnet.metalntwx.com`	`0x539` (1337)

Testnet is the default, and the developer examples in these docs target it. Devnet state may be wiped at any time, so don’t rely on devnet block numbers, hashes, or balances staying valid. To send testnet requests from a method page, open Try it and paste your endpoint ID into the endpointId field under Server. Your endpoint ID is a credential: anyone who has it can spend your account’s credits. The playground keeps it in this browser for every method page, and sends each request from your browser straight to Metal.

Test the connection

Create an endpoint in the Metal console and replace <endpoint-id> below with your endpoint ID. See RPC endpoint setup for the setup steps. Requests can be batched. This asks for the chain ID, latest block height, and finalized consensus state in one round trip:

export METAL_RPC_URL="https://rpc-testnet.metalntwx.com/v1/<endpoint-id>"
curl "$METAL_RPC_URL" \
  -H 'content-type: application/json' \
  --data '[
    {"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]},
    {"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]},
    {"jsonrpc":"2.0","id":3,"method":"consensus_status","params":[]}
  ]'

How requests work

Metal follows JSON-RPC 2.0. Send each request as an HTTP POST to your /v1/<endpoint-id> URL, with jsonrpc, method, ordered params, and an id in the body. The response echoes the id. Use the same endpoint URL for every method, without appending a method name to the path. The bare https://rpc-testnet.metalntwx.com/v1 answers 402 with a price: an agent with only a wallet buys an endpoint there over x402. Each page pre-fills a valid request, so once your endpoint ID is set, read-only methods succeed as-is. Methods that take a transaction hash, block hash, or address are pre-filled with placeholders; replace them with real values from the network you selected. Calling eth_getBlockByNumber with "latest" is an easy way to get a current block hash.

Wallet-facing overrides

Metal adapts several Ethereum methods so standard wallets can quote and submit transactions against its MIP20-denominated gas model.

Method	Metal behavior
`eth_getBalance`	Returns the account’s default MIP20 gas-token balance
`eth_gasPrice`	Returns `0x1`, in gas-token base units per gas
`eth_maxPriorityFeePerGas`	Returns `0x1`
`eth_feeHistory`	Reports zero base fees and priority-fee rewards in MIP20 base units
`eth_sendRawTransaction`	Applies Metal envelope, chain ID, value, gas-token, fee, affordability, nonce, and replacement checks
`metal_nativeCurrency`	Returns wallet display metadata for the default gas token

State proofs and blob sidecars

eth_getProof returns account and storage proofs against a block’s state root. Its balance field is the EVM account’s native balance, rather than the MIP20 balance returned by Metal’s eth_getBalance override. Proving a MIP20 balance requires a storage proof at the token contract address for keccak256(abi.encode(holder, uint256(0))). Slot 0 is the base slot of the _balances mapping, rather than a holder’s balance. For holder 0x0000000000000000000000000000000000000001, the derived key is 0xada5013122d395ba3c54772283fb069b10426056ef8ca54750cb9bb552a59e7d. metal_getBlobSidecars retrieves retained EIP-7594 sidecars by execution block hash. It returns null for blocks outside the canonical finalized chain or without a retained verified sidecar. See Blob Transactions and Sidecars for ordering and verification requirements.

Block tags and finality

Block-reading methods accept the standard Ethereum block selectors.

Selector	Metal meaning
`"latest"`	Most recent execution head; equals `"finalized"` in steady state, since the head advances at finalization
`"pending"`	Speculative next block built from the node’s transaction pool; may be ahead of the head
`"safe"`	Alias for `"finalized"` on Metal, kept for Ethereum tooling compatibility
`"finalized"`	Block committed by Simplex consensus
`"earliest"`	Genesis block
`"0x<n>"`	Specific block number as a hex quantity

For settlement decisions, use "finalized" or compare the receipt’s block against consensus_status.finalized. A transaction hash identifies a submission, and a successful receipt reports EVM execution; neither alone proves finality.

Errors

Errors come back in-band as a JSON-RPC error object with code and message in place of result. Protocol-level errors use the standard codes:

Code	Meaning
`-32700`	Invalid JSON
`-32600`	Invalid request shape, or a body or batch over its limit
`-32601`	Method not found or unavailable
`-32602`	Invalid method parameters
`-32603`	Internal RPC or provider error

Transaction admission failures are returned by eth_sendRawTransaction with a more specific message.

Error codes

Match Metal admission and MIP20 transfer failures to corrective actions.

Connect to testnet

Wallet and SDK connection details for the public testnet.

Getting started

Chain

Consensus

Blocks

State

Gas

Transactions

Logs

MIP20

Choose a network

Test the connection

How requests work

Wallet-facing overrides

State proofs and blob sidecars

Block tags and finality

Errors

Error codes

Connect to testnet

​Choose a network

​Test the connection

​How requests work

​Wallet-facing overrides

​State proofs and blob sidecars

​Block tags and finality

​Errors

Error codes

Connect to testnet

Choose a network

Test the connection

How requests work

Wallet-facing overrides

State proofs and blob sidecars

Block tags and finality

Errors