Using SDK

Gasless SDK (EOA), enables meta transactions or gasless transactions in your dApp out of the box.

Biconomy's Gasless SDK (EOA) is a javascript based implementation that can be easily integrated into your dApp. The SDK can be used on client side code running in a browser or a javascript based dApp running on a backend server.

It works alongside your existing Web3/Ethers library by acting as a Web3/Ether provider that submits meta transactions to our relayer infrastructure - instead of directly to the network.

Get your API Key first

In order to integrate SDK, you will need an API Key. Check out how to get API key from the dashboard.

This section is divided into Frontend and Backend integration of SDK. You can choose either of them based on your requirement.

SDK Frontend Integration

1. Installing and importing SDK

Biconomy Gasless SDK can be installed either via npm or yarn.

npm install @biconomy/mexa
yarn add @biconomy/mexa

You can use Gasless either with Web3.js or Ethers.js library. It works with both libraries.

const biconomy = new Biconomy(window.ethereum as ExternalProvider, {
  debug: true,
  contractAddresses: [<contractAddress1>, <contractAddress2>], // list of contract address you want to enable gasless on

// The first argument of the Biconomy class is an EIP 1193 type provider that has to be passed. 
// If there is a type mismatch you'll have to set the type of the provider as 
// External Provider
export type ExternalProvider = {
  isMetaMask?: boolean;
  isStatus?: boolean;
  host?: string;
  path?: string;
  sendAsync?: (request: { method: string, params?: Array<any> }, callback: (error: any, response: any) => void) => void
  send?: (request: { method: string, params?: Array<any> }, callback: (error: any, response: any) => void) => void
  request?: (request: { method: string, params?: Array<any> }) => Promise<any>

// To create contract instances you can do:
const contractInstance = new ethers.Contract(

If using SDK version 2.0.35 or earlier:

import { Biconomy } from "@biconomy/mexa";
const biconomyWithWeb3 = new Biconomy(<web3 provider>,{apiKey: <API Key>, debug: true});
web3 = new Web3(biconomyWithWeb3);

const biconomyWithEthers = new Biconomy(<ethers provider>,{apiKey: <API Key>, debug: true});
let ethersProvider = new ethers.providers.Web3Provider(biconomyWithEthers);

2. Initialize your dApp after SDK initialization

You need to call the init method. This method makes calls to the Biconomy backend to fetch data that you registered on the dashbaord.

await biconomy.init();

3. Example Code:

Since we have enabled native meta transaction in a custom way, instead of calling your smart contract methods directly, we will call executeMetaTransaction method and pass the target method info as a parameter to this function.

Refer to this link for extensive code examples for you to interact with the SDK.

Congratulations 👏

You have now enabled meta transactions in your dApp.

SDK Backend Integration

For using the SDK in the backend, use SDK version 2.0.35 or earlier

Here, we provide more freedom to the developer in case you want to use Biconomy in your project running at the backend where a raw transaction is signed by the user's private key.

Integration Steps

  1. Initialize the Gasless SDK (EOA) in the same way as mentioned above.

  2. Call executeMetaTransaction method via web3 or ethers using a private key.

Checkout example code below. Need more reference? check repositories for complete code.

Check the repository here for complete example code with this approach

let sigUtil = require("eth-sig-util"); // additional dependency 

let privateKey = <PRIVATE_KEY>;
let nonce = await contract.methods.getNonce(userAddress).call();
let functionSignature = contract.methods.setQuote(newQuote).encodeABI();

let message = {};
message.nonce = parseInt(nonce);
message.from = userAddress;
message.functionSignature = functionSignature;

//please refer to SDK front end example for domainType and domainData
const dataToSign = JSON.stringify({
  types: {
    EIP712Domain: domainType,
    MetaTransaction: metaTransactionType
  domain: domainData,
  primaryType: "MetaTransaction",
  message: message

/*Its important to use eth_signTypedData_v3 and not v4 to get EIP712 
signature because we have used salt in domain data instead of chainId*/
const signature = sigUtil.signTypedMessage(new Buffer.from(privateKey, 'hex'), { data: dataToSign }, 'V3');
let { r, s, v } = getSignatureParameters(signature); // same helper used in SDK frontend code
let executeMetaTransactionData = contract.methods.executeMetaTransaction(userAddress, functionSignature, r, s, v).encodeABI();

let txParams = {
                    "from": userAddress,
                    "to": config.contract.address,
                    "value": "0x0",
                    "gas": "100000", // (optional) your custom gas limit 
                    "data": executeMetaTransactionData
const signedTx = await web3.eth.accounts.signTransaction(txParams, `0x${privateKey}`);                                                                

let receipt = await web3.eth.sendSignedTransaction(signedTx.rawTransaction, (error, txHash) => {
                    if (error) {
                        return console.error(error);
                    console.log("Transaction hash is ", txHash);
                    // do something with transaction hash

If you don't wish to use the Gasless SDK (EOA), gasless meta transactions can be directly sent using Biconomy's APIs also. Check next section for implementation steps.

Last updated