> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metalntwx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metal JSON-RPC

> Send JSON-RPC requests to Metal's public RPC endpoints on testnet and devnet

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](https://console-testnet.metalntwx.com)
and replace `<endpoint-id>` below with your endpoint ID. See
[RPC endpoint setup](https://docs.metalntwx.com/start/connect-to-testnet.md#2-create-an-rpc-endpoint) 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:

```bash theme={null}
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](https://docs.metalntwx.com/network/endpoints.md#an-endpoint-for-your-agent)
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](https://docs.metalntwx.com/reference/network-fundamentals/blobs.md) 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.

> [card] [Error codes](https://docs.metalntwx.com/reference/error-codes.md)
>
> Match Metal admission and MIP20 transfer failures to corrective actions.

> [card] [Connect to testnet](https://docs.metalntwx.com/start/connect-to-testnet.md)
>
> Wallet and SDK connection details for the public testnet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.