Using API

Use native meta transaction APIs to easily implement meta transactions!

Before using this API, make sure your smart contracts inherits from one of the contracts mentioned in Custom Implementation , and you have removed the dependency on msg.sender property from your smart contracts by replacing it with msgSender() method.

/api/v2/meta-tx/native

POST https://api.biconomy.io/api/v2/meta-tx/native

Our API lets you relay transactions directly to your smart contract without having the end user paying the transaction/gas fee. Just register your dApp on the developer dashboard, upload your smart contracts with meta transaction type as Custom and select executeMetaTransaction method under Manage API section.

Headers

Name	Type	Description
x-api-key	string	API key present on your dashboard for your DApp after DApp registration. This is specific to DApp registered.

Request Body

Name	Type	Description
gasLimit	string	Gas limit to be set in the transaction. It can be a decimal number or hexadecimal string. If omitted web3 estimateGas method will be used to calculate the gasLimit for the transaction.
to	string	Target Contract Address. In case of SCW, It represents user's proxy wallet address.
apiId	string	API id corresponding to the method you want to call in your smart contract. Select executeMetaTransaction method on the dashboard under 'Manage APIs' section or other methods that support native meta transaction like DAI permit method.
params	array	Array of all the parameters required to call the method in the same order they appear in your Smart Contract.
from	string	User client wallet public address who is supposed to be sending the transaction eg. metamask wallet address.

200 Success response after the transaction is relayed by Biconomy

{
    "txHash": "0x19847abea387b5086e4ff35a5e27cc18b72e04c29e81a85dd27316b05c27b818",
    "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.

404 Required data not found

409 When Limits set on dashboard are reached. Check the code field to see which limit is reached. See "Check Limit" under API section to see all possible values of code field. code = 150, when DApp limits are reached code = 151, when User limits are reached code = 152, when API per user limits are reached

417 When gas estimation is failed due to any revert on your contracts due to any business logic. Usually you'll see the revert error message in response, but to debug the issue, try sending the same transaction without Biconomy to see the actual error on explorer.

Example Curl Request

curl 
--request POST 'https://api.biconomy.io/api/v2/meta-tx/native'
--header 'x-api-key: <api_key_from_dashboard>'
--header 'Content-Type: application/json'
--data-raw '{ 
"userAddress": "<user_public_address>",
"apiId": "<api_id_from_dashboard>", 
"params": [<param1>,<param2>,...... ],
"gasLimit":"0xF4240" 
}'

Example Code Snippets

Web3 + EIP712Sign

Check the repository here for complete example code.

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);

// Initialize constants
const domainType = [
    { name: "name", type: "string" },
    { name: "version", type: "string" },
    { name: "verifyingContract", type: "address" },
    { name: "salt", type: "bytes32" },
];
const metaTransactionType = [
    { name: "nonce", type: "uint256" },
    { name: "from", type: "address" },
    { name: "functionSignature", type: "bytes" }
];
// replace the chainId 42 if network is not kovan
let domainData = {
    name: "TestContract",
    version: "1",
    verifyingContract: config.contract.address,
    // converts Number to bytes32. pass your chainId instead of 42 if network is not Kovan
    salt : '0x' + (42).toString(16).padStart(64, '0')
};

let userAddress = <selected address>;
let contract = new web3.eth.Contract(
            <Your Contract ABI>,
            <Your Contract Address>
          );
  
let nonce = await contract.methods.getNonce(userAddress).call();
// Create your target method signature.. here we are calling setQuote() method of our contract
let functionSignature = contract.methods.setQuote(newQuote).encodeABI();
let message = {};
message.nonce = parseInt(nonce);
message.from = userAddress;
message.functionSignature = functionSignature;

const dataToSign = JSON.stringify({
  types: {
    EIP712Domain: domainType,
    MetaTransaction: metaTransactionType
  },
  domain: domainData,
  primaryType: "MetaTransaction",
  message: message
});


web3.currentProvider.send(
  {
    jsonrpc: "2.0",
    id: 999999999999,
    method: "eth_signTypedData_v4",
    params: [userAddress, dataToSign]
  },
   function (error, response) {
          console.info(`User signature is ${response.result}`);
          if (error || (response && response.error)) 
           {
            showErrorMessage("Could not get user signature");
           }
           else if (response && response.result) 
           {
             let { r, s, v } = getSignatureParameters(response.result);
             sendTransaction(userAddress, functionSignature, r, s, v);
           }
  }
);

///////////
//helpers//

const sendTransaction = async (userAddress, functionData, r, s, v) => {
        if (web3 && contract) {
            try {
                fetch(`https://api.biconomy.io/api/v2/meta-tx/native`, {
                    method: "POST",
                    headers: {
                      "x-api-key" : <BICONOMY_DAPP_API_KEY>,
                      'Content-Type': 'application/json;charset=utf-8'
                    },
                    body: JSON.stringify({
                      "to": config.contract.address,
                      "apiId": <METHOD_API_ID>,
                      "params": [userAddress, functionData, r, s, v],
                      "from": userAddress
                    })
                  })
                  .then(response=>response.json())
                  .then(async function(result) {
                    console.log(result);
                    showInfoMessage(`Transaction sent by relayer with hash ${result.txHash}`);
          
                    let receipt = await getTransactionReceiptMined(result.txHash, 2000);
                    setTransactionHash(result.txHash);
                    showSuccessMessage("Transaction confirmed on chain");
                    getQuoteFromNetwork();
                  }).catch(function(error) {
                      console.log(error)
                    });
            } catch (error) {
                console.log(error);
            }
        }
    };
    
const getTransactionReceiptMined = (txHash, interval) => {
        const self = this;
        const transactionReceiptAsync = async function(resolve, reject) {
          var receipt = await web3.eth.getTransactionReceipt(txHash);
          if (receipt == null) {
              setTimeout(
                  () => transactionReceiptAsync(resolve, reject),
                  interval ? interval : 500);
          } else {
              resolve(receipt);
          }
        };
    
        if (typeof txHash === "string") {
            return new Promise(transactionReceiptAsync);
        } else {
            throw new Error("Invalid Type: " + txHash);
        }
      };
      
      
const getSignatureParameters = signature => {
        if (!web3.utils.isHexStrict(signature)) {
            throw new Error(
                'Given value "'.concat(signature, '" is not a valid hex string.')
            );
        }
        var r = signature.slice(0, 66);
        var s = "0x".concat(signature.slice(66, 130));
        var v = "0x".concat(signature.slice(130, 132));
        v = web3.utils.hexToNumber(v);
        if (![27, 28].includes(v)) v += 27;
        return {
            r: r,
            s: s,
            v: v
        };
    };      

Web3 + PersonalSign

Ethers + EIP712Sign

Ethers + PersonalSign

Congratulations 👏

You're now ready to use the custom approach and enable gasless transactions in your dApp using SDK and/or APIs.