HTTP Transport

Connect to Ethereum nodes via standard JSON-RPC over HTTP/HTTPS

The HTTP transport connects to Ethereum nodes via standard JSON-RPC over HTTP/HTTPS. It's the most common transport type.

The transport.HTTP(...) function returns a transport.TransportFactory that you pass into a client config (e.g. client.PublicClientConfig or client.WalletClientConfig).

Import

import (
  "github.com/ChefBingbong/viem-go/client"
  "github.com/ChefBingbong/viem-go/client/transport"
)

These are the most common imports for using the HTTP transport:

transport: HTTP transport factory and config types (e.g. transport.HTTP, transport.HTTPTransportConfig).
client: Client constructors/config (e.g. client.CreatePublicClient, client.PublicClientConfig).

Go notes

Transport factories

transport.HTTP(...) creates a factory, not an immediate connection. The client constructs the transport internally when you create the client.

Closing the client

Close the client when you're done: defer publicClient.Close(). This closes the underlying transport (and any batch scheduler if enabled).

Usage

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: transport.HTTP("https://eth.llamarpc.com"),
})
if err != nil {
  log.Fatal(err)
}
defer publicClient.Close()

Parameters

URL (optional)

Type: string

The RPC endpoint URL.

URL resolution order is:

Function argument: transport.HTTP(\"https://...\")
Config: transport.HTTP(\"\", transport.HTTPTransportConfig{ URL: \"https://...\" })
Chain default: params.Chain.RpcUrls[\"default\"].HTTP[0] (when a client provides a chain)

If no URL can be resolved, client creation fails with transport.ErrURLRequired.

tr := transport.HTTP("https://eth.llamarpc.com")

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

Timeout (optional)

Type: time.Duration
Default: 10s

Request timeout for each JSON-RPC call.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Timeout: 5 * time.Second,
})

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

RetryCount (optional)

Type: int
Default: 3

Maximum number of retry attempts for retryable errors.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  RetryCount: 5,
})

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

RetryDelay (optional)

Type: time.Duration
Default: 150ms

Base delay between retries. Retries use exponential backoff (delay * 2^attempt).

If a Retry-After header is present on an HTTP error, it will be used when possible.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  RetryDelay: 250 * time.Millisecond,
})

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

Headers (optional)

Type: map[string]string

Additional HTTP headers to include in requests (e.g. for authenticated endpoints).

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Headers: map[string]string{
      "Authorization": "Bearer YOUR_API_KEY",
  },
})

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

Batch (optional)

Type: *transport.BatchConfig

Enables JSON-RPC request batching at the transport layer.

When enabled, concurrent requests may be grouped into a single HTTP request.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Batch: &transport.BatchConfig{
      Enabled:   true,
      BatchSize: 1000,
      Wait:      10 * time.Millisecond,
  },
})

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

Batch.Enabled (optional)

Type: bool
Default: false

Whether batching is enabled.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Batch: &transport.BatchConfig{
      Enabled: true,
  },
})

Batch.BatchSize (optional)

Type: int
Default: 1000

Maximum number of requests per batch. If 0, viem-go defaults it to 1000.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Batch: &transport.BatchConfig{
      Enabled:   true,
      BatchSize: 500,
  },
})

Batch.Wait (optional)

Type: time.Duration

Maximum time to wait before sending a batch (gives more time for concurrent requests to coalesce).

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Batch: &transport.BatchConfig{
      Enabled: true,
      Wait:    10 * time.Millisecond,
  },
})

Methods (optional)

Type: *transport.MethodFilter

Restrict which JSON-RPC methods can be called by this transport.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Methods: &transport.MethodFilter{
      Include: []string{"eth_blockNumber", "eth_getBalance"},
      Exclude: []string{"eth_sendTransaction"},
  },
})

Methods.Include (optional)

Type: []string

If set, only methods in Include are allowed (except those blocked by Exclude).

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Methods: &transport.MethodFilter{
      Include: []string{"eth_blockNumber", "eth_getBalance"},
  },
})

Methods.Exclude (optional)

Type: []string

Methods to block (checked before Include).

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Methods: &transport.MethodFilter{
      Exclude: []string{"eth_sendTransaction", "eth_sendRawTransaction"},
  },
})

Raw (optional)

Type: bool
Default: false

When enabled, RPC error responses are returned as (*transport.RPCResponse, nil) instead of being wrapped into an error.

This can be useful if you want to inspect resp.Error yourself.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Raw: true,
})

OnRequest (optional)

Type: func(req any) error

Hook invoked before each request.

This field exists on HTTPTransportConfig, but it is not currently invoked by the transport implementation.

OnResponse (optional)

Type: func(resp any) error

Hook invoked after each response.

This field exists on HTTPTransportConfig, but it is not currently invoked by the transport implementation.

Key (optional)

Type: string
Default: "http"

Transport identifier key.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Key: "foo",
})

Name (optional)

Type: string
Default: "HTTP JSON-RPC"

Human-readable transport name.

tr := transport.HTTP("https://eth.llamarpc.com", transport.HTTPTransportConfig{
  Name: "Foo HTTP Transport",
})

Return Type

transport.HTTP(...) returns a transport.TransportFactory.