> ## 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.

# Connect to Metal

> RPC endpoints and application clients for Metal Testnet

> [!NOTE]
>
> **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](https://docs.metalntwx.com/start/connect-to-testnet.md#2-create-an-rpc-endpoint)
to configure testnet billing and obtain an endpoint URL from the
[Metal console](https://console-testnet.metalntwx.com). 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://docs.metalntwx.com/reference/typescript-sdk.md) 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.

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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.

```bash theme={null}
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](https://docs.metalntwx.com/build/operations/monitor-and-recover-your-integration.md). 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](https://docs.metalntwx.com/build/prepare/fund-a-test-account.md).


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