Connect to Metal

What you’ll be able to do

Connect an application to Metal Testnet.
Verify the chain ID and confirm that blocks are advancing.

Get an RPC endpoint

Follow Create an RPC endpoint to configure testnet billing and obtain an endpoint URL from the Metal console. This procedure does not require the quickstart’s command-line tools. Set METAL_RPC_URL in the terminal that runs the application, replacing the placeholder with the full URL copied from the console:

export METAL_RPC_URL="https://rpc-testnet.metalntwx.com/v1/<endpoint-id>"

For a deployed service, supply METAL_RPC_URL through its environment or secret configuration. Keep endpoint URLs out of source control and application logs.

Setting	Expected value
Network	Metal Testnet
Chain ID	`63825` (`0xf951` in JSON-RPC)
RPC transport	HTTPS

Add a client

Use Node.js 22 or later and pnpm 10.4 or later. Add the client to an existing project without replacing its package or compiler configuration. To start a new project:

mkdir metal-client
cd metal-client
pnpm init

From the project directory, install viem and the TypeScript tools. Keep compatible versions already installed in the project:

pnpm add viem@2
pnpm add -D typescript@6 tsx@4 @types/node@22 --allow-build=esbuild

The --allow-build=esbuild option permits the build step required by tsx. Review it against the project’s dependency policy. Viem’s public client handles these read requests. Later guides introduce the Metal SDK for Metal-specific transaction signing and encoding.

Initialize the public client

A public client needs only the endpoint URL. Reading chain data requires no signing key.

import { createPublicClient, http } from "viem";

const rpcUrl = process.env.METAL_RPC_URL?.trim();
if (!rpcUrl) throw new Error("Set METAL_RPC_URL.");
const client = createPublicClient({ transport: http(rpcUrl) });

Create this client once and reuse it for reads.

Check the network

const chainId = await client.getChainId();
if (chainId !== 63825) throw new Error("Expected Metal Testnet (63825).");

Check block progress

Use the same client and bypass its block-number cache for each sample:

import { setTimeout } from "node:timers/promises";

const firstBlock = await client.getBlockNumber({ cacheTime: 0 });
await setTimeout(5_000);
const laterBlock = await client.getBlockNumber({ cacheTime: 0 });
if (laterBlock <= firstBlock) throw new Error("No block progress observed; retry.");

Run and check the result

Run these checks when initializing the connection. To run them separately, put the code in order in check-connection.mts and add console.log({ chainId, firstBlock, laterBlock }) at the end. The .mts extension enables ES modules and top-level await. The command below uses --ignoreConfig to check this file with explicit compiler options, leaving the project’s tsconfig.json unchanged.

pnpm exec tsc --ignoreConfig --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --types node --strict --skipLibCheck check-connection.mts
node --import tsx check-connection.mts

A successful run reports chain ID 63825 and a laterBlock greater than firstBlock. Check the failure paths separately. Running with METAL_RPC_URL="" should stop before any RPC request. An in-process mock returning 0x1 for eth_chainId should trigger the wrong-network error. Use the live endpoint for the successful connection check. In a service, catch provider errors at the application boundary and redact endpoint URLs before logging them.

Diagnose connection failures

Failure	What to check
Missing or invalid URL	Supply the full endpoint URL in the process environment and replace placeholders.
Cannot read chain ID	Confirm the endpoint is active, its access settings permit this application, and the RPC credit balance covers the requests.
Wrong network	Copy an endpoint for Metal Testnet and keep the expected chain ID check.
Block read fails or block number does not advance	Retry, then follow Monitor and recover your integration. One failed observation does not establish a network outage.

Once this check passes, the application can read Metal through its public client. Before submitting transactions, choose a signing account and fund it using the Faucet.

Prepare an integration

Process payments

Control spending

Deploy and automate contracts

Use data and signatures

Connect other chains

Operate your integration

Get an RPC endpoint

Add a client

Initialize the public client

Check the network

Check block progress

Run and check the result

Diagnose connection failures

​Get an RPC endpoint

​Add a client

​Initialize the public client

​Check the network

​Check block progress

​Run and check the result

​Diagnose connection failures

Get an RPC endpoint

Add a client

Initialize the public client

Check the network

Check block progress

Run and check the result

Diagnose connection failures