HTTP Transport

The http Transport connects to a JSON-RPC API via HTTP.

Import

import { http } from 'viem'

import { http } from 'viem'

Usage

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

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...')

const client = createPublicClient({
  chain: mainnet,
  transport,
})

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

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...')

const client = createPublicClient({
  chain: mainnet,
  transport,
})

WARNING

If no url is provided, then the transport will fall back to a public RPC URL on the chain. It is highly recommended to provide an authenticated RPC URL to prevent rate-limiting.

Batch JSON-RPC

The http Transport supports Batch JSON-RPC. This means that multiple JSON-RPC requests can be sent in a single HTTP request.

The Transport will batch up Actions over a given period and execute them in a single Batch JSON-RPC HTTP request. By default, this period is a zero delay meaning that the batch request will be executed at the end of the current JavaScript message queue. Consumers can specify a custom time period wait (in ms).

You can enable Batch JSON-RPC by setting the batch flag to true:

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: true 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: true 
})

Now when you invoke Actions, the http Transport will batch and send over those requests at the end of the message queue (or custom time period) in a single Batch JSON-RPC HTTP request:

// The below will send a single Batch JSON-RPC HTTP request to the RPC Provider.
const [blockNumber, balance, ensName] = await Promise.all([
  client.getBlockNumber(),
  client.getBalance({ address: '0xd2135CfB216b74109775236E36d4b433F1DF507B' }),
  client.getEnsName({ address: '0xd2135CfB216b74109775236E36d4b433F1DF507B' }),
])

// The below will send a single Batch JSON-RPC HTTP request to the RPC Provider.
const [blockNumber, balance, ensName] = await Promise.all([
  client.getBlockNumber(),
  client.getBalance({ address: '0xd2135CfB216b74109775236E36d4b433F1DF507B' }),
  client.getEnsName({ address: '0xd2135CfB216b74109775236E36d4b433F1DF507B' }),
])

Parameters

url (optional)

Type: string
Default: chain.rpcUrls.default.http[0]

URL of the JSON-RPC API.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...')

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...')

batch (optional)

Type: boolean | BatchOptions
Default: false

Toggle to enable Batch JSON-RPC

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: true 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: true 
})

batch.batchSize (optional)

Type: number
Default: 1_000

The maximum number of JSON-RPC requests to send in a batch.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: {
    batchSize: 2_000 
  }
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: {
    batchSize: 2_000 
  }
})

batch.wait (optional)

Type: number
Default: 0 (zero delay)

The maximum number of milliseconds to wait before sending a batch.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: {
    wait: 16 
  }
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  batch: {
    wait: 16 
  }
})

fetchOptions (optional)

Type: RequestInit

Fetch options to pass to the internal fetch function. Useful for passing auth headers or cache options.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  fetchOptions: { 
    headers: {
      'Authorization': 'Bearer ...'
    }
  }
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  fetchOptions: { 
    headers: {
      'Authorization': 'Bearer ...'
    }
  }
})

key (optional)

Type: string
Default: "http"

A key for the Transport.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  key: 'alchemy', 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  key: 'alchemy', 
})

name (optional)

Type: string
Default: "HTTP JSON-RPC"

A name for the Transport

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  name: 'Alchemy HTTP Provider', 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  name: 'Alchemy HTTP Provider', 
})

retryCount (optional)

Type: number
Default: 3

The max number of times to retry when a request fails.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  retryCount: 5, 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  retryCount: 5, 
})

retryDelay (optional)

Type: number
Default: 150

The base delay (in ms) between retries. By default, the Transport will use exponential backoff (~~(1 << count) * retryDelay), which means the time between retries is not constant.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  retryDelay: 100, 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  retryDelay: 100, 
})

timeout (optional)

Type: number
Default: 10_000

The timeout for requests.

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  timeout: 60_000, 
})

const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
  timeout: 60_000, 
})

HTTP Transport ​

Import ​

Usage ​

Batch JSON-RPC ​

Parameters ​

url (optional) ​

batch (optional) ​

batch.batchSize (optional) ​

batch.wait (optional) ​

fetchOptions (optional) ​

key (optional) ​

name (optional) ​

retryCount (optional) ​

retryDelay (optional) ​

timeout (optional) ​