Using API

Use our APIs to easily implement meta transactions!


Before using this API, make sure you have Trusted Forwarder support in your smart contracts i.e., you have removed the dependency on msg.sender property from your smart contracts and trusted forwarder is added.



Our API lets you relay transactions directly to your smart contract without your end users having to pay any transaction/gas fee. Just register your dApp on the developer dashboard, upload your smart contracts as meta transaction type as Trusted Forwarder and select your methods in which you want to enable native meta transaction support.


Request Body

    "txHash": "0x84bc6f25b964f794f90c59b4f97a16aadc878ce53187703124b5e0ee52e15af9",
    "message": "Meta transaction sent to blockchain",
    "retryDuration": 158, 
    "flag": 200
//retryDuration: time in seconds after which you 
//can check resubmitted endpoint for new hash in case of
//potential resubmits.

Example Curl Request

--request POST ''  
--header 'x-api-key: <api_key_from_dashboard>'  
--header 'Content-Type: application/json'  
--data-raw '{ 
"from": "<user_public_address>",
"apiId": "<api_id_from_dashboard>", 
"params": [<param1>,<param2>,...... ],
"to": "<recipient_contract_address>",

If the signature type is EIP712, params are [request, domainSeperator, signature] params = [request, domainSeparator, sig];

If signature type is personal sign, (assumed default if signatureType parameter is omitted in API request body) params are [request, signature]. params = [request, sig];

Biconomy has helpers available to build above mentioned parameters from your dapp transaction.

For EIP2771, below is an example code on how to use Biconomy helpers JS to build request, domain separator and data to sign for each signature type and then send API request to the Biconomy servers where our relayer infrastructure will process your transaction.

Sample code

Check the repository here for complete example code

import {
  } from './biconomyForwarderHelpers';
let sigUtil = require("eth-sig-util"); // additional dependency 

// This web3 instance is used to get user signature from connected wallet
let walletWeb3 = new Web3(window.ethereum);

let userAddress = <selected address>;
let networkId = <your provider networkId here>;

// Initialize Contracts
let contract = new web3.eth.Contract(

let functionSignature = contract.methods
let txGas = await contract.methods
                  .estimateGas({ from: userAddress });
let forwarder = await getBiconomyForwarderConfig(networkId);
let forwarderContract = new web3.eth.Contract(

//const batchId = await forwarderContract.methods.getBatch(userAddress).call();
const batchNonce = await forwarderContract.methods.getNonce(address,0).call();
const gasLimitNum = Number(txGas);
const to = <CONTRACT_ADDRESS>;

const request = await buildForwardTxRequest({account:userAddress,to,gasLimitNum,batchId,batchNonce,data:functionSignature});

/* If you wish to use EIP712 Signature type check below code*/

const hashToSign = getDataToSignForPersonalSign(request);
const sig = await walletWeb3.eth.personal.sign("0x" + hashToSign.toString("hex"), userAddress);
sendTransaction({userAddress, request, sig, signatureType:biconomy.PERSONAL_SIGN});
// notice domain seperator is not passed here


 // If you wish to use EIP712 Signature type  
 //build the request as mentioned above
   const domainSeparator = await getDomainSeperator(42);
   const dataToSign =  await getDataToSignForEIP712(request,networkId);

                        jsonrpc: "2.0",
                        id: 999999999999,
                        method: "eth_signTypedData_v4",
                        params: [userAddress, dataToSign]
                    function (error, response) {
              `User signature is ${response.result}`);
                        if (error || (response && response.error)) {
                            showErrorMessage("Could not get user signature");
                        } else if (response && response.result) {
                            let sig = response.result;
                            sendTransaction({userAddress, request, domainSeparator, sig, signatureType:biconomy.EIP712_SIGN});

Great! Once your parameters are built you are ready to make the API call to send gasless transactions!

const sendTransaction = async ({userAddress, request, sig, domainSeparator, signatureType}) => {
        if (web3 && contract) {
          let params;
          if (domainSeparator) {
            params = [request, domainSeparator, sig];
          } else {
            params = [request, sig];
          try {
            fetch(``, {
              method: "POST",
              headers: {
                "x-api-key": <YOUR_DAPP_API_KEY>,
                "Content-Type": "application/json;charset=utf-8",
              body: JSON.stringify({
                to: <CONTRACT_ADDRESS>,
                apiId: <METHOD_API_ID>,
                params: params,
                from: userAddress,
                signatureType: signatureType
              .then((response) => response.json())
              .then(async function (result) {
                  `Transaction sent by relayer with hash ${result.txHash}`

                let receipt = await getTransactionReceiptMined(
                showSuccessMessage("Transaction confirmed on chain");
              .catch(function (error) {
          } catch (error) {

  //for web3  
  const getTransactionReceiptMined = (txHash, interval) => {
        const self = this;
        const transactionReceiptAsync = async function(resolve, reject) {
          var receipt = await web3.eth.getTransactionReceipt(txHash);
          if (receipt == null) {
                  () => transactionReceiptAsync(resolve, reject),
                  interval ? interval : 500);
          } else {
        if (typeof txHash === "string") {
            return new Promise(transactionReceiptAsync);
        } else {
            throw new Error("Invalid Type: " + txHash);

Congratulations 👏

You're now ready to use the trusted forwarder approach and enable gasless transactions in your dApp using SDK and/or APIs. Check out other implementations and in-depth technical details in the following sections.

Last updated