0.3.4 • Public • Published

    HttpHeaderProvider - A Replacement Web3.js HttpProvider supporting custom HTTP Headers

    This module can be used in place of HttpProvider from web3.js.

    Once in place, the constructor offers a headers parameter that is a key/value object that has the headers to be set.


    First you need to grab the npm package and then reference it.

    npm install --save httpheaderprovider

    Debug Mode

    The module supports emitting debug information by adding an environment variable:

    export DEBUG=ethereumex:httpheaderprovider
    # windows cmd 
    SET DEBUG=ethereumex:httpheaderprovider
    # posh 

    Debug messages

    Once debug is enabled you see things like:

    talking to remote Geth on https://<yourAPI>
      ethereumex:httpheaderprovider constructor:begin +0ms
      ethereumex:httpheaderprovider constructor:end +2ms
      ethereumex:httpheaderprovider Request: {"jsonrpc":"2.0","id":1,"method":"web3_clientVersion","params":[]} +1ms
      ethereumex:httpheaderprovider prepareRequest:begin +1ms
      ethereumex:httpheaderprovider setting headers +13ms
      ethereumex:httpheaderprovider prepareRequest:end +0ms
      ethereumex:httpheaderprovider Result:  {"jsonrpc":"2.0","id":1,"result":"Geth/v1.5.4-stable-b70acf3c/linux/go1.7.3"} +371ms
    ethereum client info: Geth/v1.5.4-stable-b70acf3c/linux/go1.7.3
      ethereumex:httpheaderprovider Request: {"jsonrpc":"2.0","id":2,"method":"net_peerCount","params":[]} +1ms
      ethereumex:httpheaderprovider prepareRequest:begin +0ms
      ethereumex:httpheaderprovider setting headers +1ms
      ethereumex:httpheaderprovider prepareRequest:end +0ms
      ethereumex:httpheaderprovider Result:  {"jsonrpc":"2.0","id":2,"result":"0x19"} +249ms
    Peer Count: 25
      ethereumex:httpheaderprovider Request: {"jsonrpc":"2.0","id":3,"method":"eth_coinbase","params":[]} +3ms
      ethereumex:httpheaderprovider prepareRequest:begin +0ms
      ethereumex:httpheaderprovider setting headers +0ms
      ethereumex:httpheaderprovider prepareRequest:end +0ms
      ethereumex:httpheaderprovider Result:  {"jsonrpc":"2.0","id":3,"result":"0x13015840b5b4641f3ad441e36ec428d7a1c9934c"} +431ms
    web3.eth.coinbase: 0x13015840b5b4641f3ad441e36ec428d7a1c9934c
      ethereumex:httpheaderprovider Request: {"jsonrpc":"2.0","id":4,"method":"eth_getBalance","params":["0x13015840b5b4641f3ad441e36ec428d7a1c9934c","latest"]} +2ms
      ethereumex:httpheaderprovider prepareRequest:begin +0ms
      ethereumex:httpheaderprovider setting headers +0ms
      ethereumex:httpheaderprovider prepareRequest:end +1ms
      ethereumex:httpheaderprovider Result:  {"jsonrpc":"2.0","id":4,"result":"0x8cf23f909c0fa000"} +277ms
    web3.eth.getBalance(coinbase) 10156250000000000000

    Adding to your web3.js project

    In your JavaScript project instead of create an instance of the web3.providers.HttpProvider in place, create an instance of HttpHeaderProvider with the same parameters along with a object that is a key/value property object.

    var Web3 = require('web3');
    var web3 = new Web3();
    var HttpHeaderProvider = require('httpheaderprovider');
    var headers = {
      "Ocp-Apim-Subscription-Key": "mykeyfromtheapiportal",
      "header2": "foobar"
    var provider = new HttpHeaderProvider('', headers);
    var coinbase = web3.eth.coinbase;
    var balance = web3.eth.getBalance(coinbase);


    The JSON-RPC endpoint on an Ethereum client provides no authentication or authorization boundary. All validation happens after the client receives the reqeust and processes it, and true validation is based upon the presence of a signed transaction or not.

    With no protection at layer 7, this does pose a DoS risk vector. However, by putting a simple layer 7 proxy in front of Geth or whatever Ethereum client is being used that has the RPC endpoint open, that proxy could validate something simple like an API key or potentially an OAuth token.

    Plus using a proxy that can add HTTPS and terminate it is nice as well. If the Get instance and the RPC client are distributed, this easily allows adding HTTPS to the transport.

    Microsoft Azure API Management

    A reason to employ a Service such as Azure API Management off-loads other resposibilities such as dealing with both Layer 3/4 and layer 7 DoS issues.


    API Managment employs simple token or API Key approach in addition to OAuth bearer tokens that can be granted by Azure Active Directory, then added to the Authorization : Bearer <token> header.


    API Manaement can also throttle based on various policies, as well as authorize only certiain calls to specific clients, all through a configuration oriented approach.

    Usage and Approach

    For a scenario recently encountered, a goal was to utilize Microsoft Azure API Management for this purpose, but there is a need to inject a custom header that the web3.js libraries today do not offer a way.


    This library takes advantage of subclassing and create a virtual function for HttpProvider.prepareRequest. The approach in the library uses pre-es2015 JavaScript. However, to make it clear what is being done, here is the es2015 compatible module:

    class HttpHeaderProvider extends Web3.providers.HttpProvider {
      constructor(host, headers) {
        debug('in prv constructor');
      prepareRequest(async) {
        debug('in prepare');
        var request = super.prepareRequest(async);
        if (this.headers){
          debug('setting headers')
          for (var header in this.headers){
            request.setRequestHeader( header, this.headers[header]);
        return request;



    npm i httpheaderprovider

    DownloadsWeekly Downloads






    Last publish


    • cicorias