Quickstart: Direct RPC

Connect to a gateway, check the chain ID, and use that same URL in your application. The examples use Ethereum mainnet and familiar JSON-RPC libraries.

For direct peer-to-peer access with no centralized gateway in the request path, run a Local gateway alongside your application. To get started without installing anything, use a Managed gateway and an HTTPS URL.

Your first requests need no funds: until you add some, your client uses free providers on Ethereum and Base, within limits. Each copy of the client you run is a device of your account, and to go past the free tier you add USDC to your account's own address on Base. See Managing payments and spending.

Local gateway

The Direct client provides a gateway on your own machine. Keep it running while your application uses RPC, and send requests to the local address it reports.

1. Install and run Direct

Install the Direct CLI and RPC client with npm. The installer automatically detects your operating system and architecture and downloads the matching executable:

npm install -g @direct.dev/cli @direct.dev/rpc

Check the installation:

direct --version

Start the RPC client:

direct rpc

The terminal interface shows the gateway address. For a server or another unattended process, use headless mode instead:

direct rpc --headless

direct rpc: listening on http://127.0.0.1:1337

The reported base address is your gateway URL. In this example it is http://127.0.0.1:1337; use the address and port shown by your own client. If you host the gateway behind a proxy, use the base address exposed by that deployment.

2. Choose a chain and make a request

Your RPC URL is the gateway URL followed by the service URL of a chain. For Ethereum mainnet, the service URL is service/ethereum:

http://127.0.0.1:1337/service/ethereum

Use your own gateway's address and port if they differ; the examples below write it as <gateway-url>. For WebSocket, use the same path on ws://127.0.0.1:1337. For another network, use its service URL from Supported chains.

In Marketplace, select the network and open Provider selection to set your maximum request price and choose whether to favor price, latency, or a balance of both. Pricing explains how these settings affect provider choice.

Send eth_chainId to confirm that the provider serves Ethereum mainnet:

curl -s "<gateway-url>/service/ethereum" \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "eth_chainId", "params": [] }'

{ "jsonrpc": "2.0", "id": 1, "result": "0x1" }

0x1 is Ethereum mainnet’s chain ID. This confirms that the gateway can obtain a provider response for the selected network.

If the request fails, check the gateway address and selected network. Troubleshooting requests walks through connection and provider errors.

3. Point your library at it

Use the full <gateway-url>/service/ethereum URL as your library’s RPC transport. These examples target Ethereum mainnet; if you chose another network, update both the URL and the library's chain configuration.

viem

Install with npm install viem.

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

const client = createPublicClient({
  chain: mainnet,
  transport: http("<gateway-url>/service/ethereum"),
})

const block = await client.getBlockNumber()

ethers

Install with npm install ethers.

import { JsonRpcProvider } from "ethers"

const provider = new JsonRpcProvider("<gateway-url>/service/ethereum")
const block = await provider.getBlockNumber()

web3.py

Install with python -m pip install web3.

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("<gateway-url>/service/ethereum"))
block = w3.eth.block_number

plain fetch

const res = await fetch("<gateway-url>/service/ethereum", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_getBalance", params: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest"] }),
})
const { result } = await res.json()

Managed gateway

Direct runs the gateway for you. Create an endpoint and use its HTTPS URL from your application.

1. Get an endpoint

Sign in to Direct and open Gateways. Select Create gateway, choose the blockchain network, and give the gateway a name you can recognize, such as my-app-development. Copy its gateway URL, including any access prefix containing the key. The base address ends before the network’s service/<network> path. You can also create a gateway from Account › Gateways in the Direct client.

Create a separate gateway for each application so you can manage its access independently. Preserve the access prefix when appending service URLs. If the interface displays a complete network endpoint, its gateway URL is the portion before /service/<network>; do not append that service path twice.

A URL embedded in a web page is visible to its users. Configure origin restrictions; see Restrict access.

2. Choose a chain and make a request

Open the gateway's Provider selection settings to set your maximum request price and choose whether to favor price, latency, or a balance of both. See Pricing for details.

Your RPC URL is the gateway URL you copied, including its access prefix, followed by the service URL of a chain. For Ethereum mainnet, the service URL is service/ethereum:

<gateway-url>/service/ethereum

If WebSocket access is enabled, the gateway lists its own wss:// address; use the same service path there. For another network, append the service URL listed in Supported chains. The request below checks the chain ID.

curl -s "<gateway-url>/service/ethereum" \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "eth_chainId", "params": [] }'

{ "jsonrpc": "2.0", "id": 1, "result": "0x1" }

If the request fails, check the gateway address and selected network. Troubleshooting requests walks through connection and provider errors.

3. Point your library at it

Set your library’s RPC transport to the full <gateway-url>/service/ethereum URL. Keep the library's chain configuration aligned with the network in that URL.

viem

Install with npm install viem.

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

const client = createPublicClient({
  chain: mainnet,
  transport: http("<gateway-url>/service/ethereum"),
})

const block = await client.getBlockNumber()

ethers

Install with npm install ethers.

import { JsonRpcProvider } from "ethers"

const provider = new JsonRpcProvider("<gateway-url>/service/ethereum")
const block = await provider.getBlockNumber()

You can later switch to a local gateway by updating the RPC URL. Choosing a local or managed gateway explains when that may be useful.

Build your RPC URL

The gateway URL is the base address of your gateway. The service URL is the relative path for the blockchain network you want to use. Combine them with one slash:

<gateway-url>/<service-url>

For Ethereum mainnet, the service URL is service/ethereum. A gateway at http://127.0.0.1:1337 therefore gives the full RPC URL http://127.0.0.1:1337/service/ethereum.

The examples above use <gateway-url> because your host, port, and access credentials depend on your setup. Replace it with your own gateway URL, without a trailing slash. Keep any access prefix included in that URL. Supported chains lists the service URLs to append.

For WebSocket access, use the gateway's WebSocket base address with the same service path. A local gateway might expose ws://127.0.0.1:1337; a hosted deployment supplies its own wss:// address if WebSocket access is enabled.

Next steps

• Use another network or method. Find the endpoint in Supported chains, or explore Supported methods for contract reads, historical queries, and transaction submission.
• Receive live updates. Use Subscriptions for blocks and logs.
• Prepare for ongoing usage. Review Pricing and Managing payments and spending to add funds and manage your devices.
• Deploy in your environment. Follow Hosting a local gateway for persistent identity, backend access, and your own public endpoint.
• Resolve a failed call. Start with Troubleshooting requests.
• Look under the hood. Behind the service explains RPC requirements and guarantees; The Direct network explains the underlying marketplace and protocol.