Relay SDK to Gasless SDK Migration

Gelato is deprecating the Relay SDK (@gelatonetwork/relay-sdk) in favor of the new Gasless SDK (@gelatocloud/gasless). The new SDK only supports sponsored transactions. ERC-2771 and SyncFee methods are no longer supported.

What’s Being Deprecated?

The following packages and patterns will no longer be supported:

@gelatonetwork/relay-sdk package
GelatoRelay class and all its methods
sponsoredCall() method
sponsoredCallERC2771() method — no longer supported, see ERC-2771 Migration Guide
callWithSyncFee() and callWithSyncFeeERC2771() methods — no longer supported, see SyncFee Migration Guide

// DEPRECATED - Will no longer work
import { GelatoRelay, SponsoredCallRequest } from "@gelatonetwork/relay-sdk";

const relay = new GelatoRelay();

const request: SponsoredCallRequest = {
  chainId: 84532n,
  target: contractAddress,
  data: encodedData,
};

const relayResponse = await relay.sponsoredCall(request, SPONSOR_API_KEY);

What’s Supported in the Gasless SDK?

The Gasless SDK only supports sponsored transactions (Gas Tank). The following legacy methods have no equivalent in the new SDK:

Old Method	New SDK
`sponsoredCall()`	`sendTransaction({ chainId, to, data })`
`sponsoredCallERC2771()`	Not supported — see ERC-2771 Migration Guide
`callWithSyncFee()`	Not supported — see SyncFee Migration Guide
`callWithSyncFeeERC2771()`	Not supported — see SyncFee Migration Guide

Migration Overview

Old (Relay SDK)	New (Gasless SDK)
`@gelatonetwork/relay-sdk`	`@gelatocloud/gasless`
`new GelatoRelay()`	`createGelatoEvmRelayerClient()`
`relay.sponsoredCall(request, apiKey)`	`relayer.sendTransaction({ chainId, to, data })`
`SponsoredCallRequest`	`{ chainId, to, data }`
Sponsor API Key per call	API Key configured once in client
`relayResponse.taskId`	Task ID + `waitForReceipt()`

Migration Steps

Update Dependencies

Remove the old SDK and install the new one:

# Remove old SDK
npm uninstall @gelatonetwork/relay-sdk

# Install new SDK
npm install @gelatocloud/gasless viem

Update Imports

Before (Relay SDK):

import { GelatoRelay, SponsoredCallRequest } from "@gelatonetwork/relay-sdk";

After (Gasless SDK):

import { createGelatoEvmRelayerClient } from "@gelatocloud/gasless";

Update Client Initialization

Before (Relay SDK):

const relay = new GelatoRelay();

After (Gasless SDK):

const relayer = createGelatoEvmRelayerClient({
  apiKey: process.env.GELATO_API_KEY,
});

Update Sponsored Call

Before (Relay SDK):

import { GelatoRelay, SponsoredCallRequest } from "@gelatonetwork/relay-sdk";
import { ethers } from "ethers";

const relay = new GelatoRelay();

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const contract = new ethers.Contract(targetAddress, abi, signer);
const { data } = await contract.increment.populateTransaction();

const request: SponsoredCallRequest = {
  chainId: (await provider.getNetwork()).chainId,
  target: targetAddress,
  data: data,
};

const relayResponse = await relay.sponsoredCall(request, SPONSOR_API_KEY);
console.log(`Task ID: ${relayResponse.taskId}`);

After (Gasless SDK):

import { createGelatoEvmRelayerClient } from "@gelatocloud/gasless";
import { encodeFunctionData } from "viem";
import { baseSepolia } from "viem/chains";

const relayer = createGelatoEvmRelayerClient({
  apiKey: process.env.GELATO_API_KEY,
});

const data = encodeFunctionData({
  abi: [{ name: "increment", type: "function", inputs: [], outputs: [] }],
  functionName: "increment",
});

const id = await relayer.sendTransaction({
  chainId: baseSepolia.id,
  to: targetAddress,
  data: data,
});

console.log(`Task ID: ${id}`);

try {
  const receipt = await relayer.waitForReceipt({ id });
  console.log(`Transaction hash: ${receipt.transactionHash}`);
} catch (error) {
  console.log(`Transaction failed: ${error.message}`);
}

Update Status Tracking

Before (Relay SDK):

const relayResponse = await relay.sponsoredCall(request, apiKey);
const taskId = relayResponse.taskId;

// Manual polling required
const taskStatus = await relay.getTaskStatus(taskId);

After (Gasless SDK):

const id = await relayer.sendTransaction({
  chainId: baseSepolia.id,
  to: targetAddress,
  data: encodedData,
});

// Built-in wait for receipt
try {
  const receipt = await relayer.waitForReceipt({ id });
  console.log(`Transaction hash: ${receipt.transactionHash}`);
} catch (error) {
  console.log(`Transaction failed: ${error.message}`);
}

Or use the synchronous method that waits automatically:

// sendTransactionSync waits for inclusion and returns the receipt
const receipt = await relayer.sendTransactionSync({
  chainId: baseSepolia.id,
  to: targetAddress,
  data: encodedData,
});

Key Differences

API Key Configuration

Before: API key passed with every call

relay.sponsoredCall(request, SPONSOR_API_KEY);

After: API key configured once at client creation

const relayer = createGelatoEvmRelayerClient({
  apiKey: process.env.GELATO_API_KEY, // Set once
});

relayer.sendTransaction({ ... }); // No API key needed per call

Request Format

Before:

const request: SponsoredCallRequest = {
  chainId: chainId,
  target: contractAddress,
  data: encodedData,
};

After:

await relayer.sendTransaction({
  chainId: chainId,
  to: contractAddress,  // "target" → "to"
  data: encodedData,
});

Complete Migration Example

Before (Relay SDK)
After (Gasless SDK)

import { GelatoRelay, SponsoredCallRequest } from "@gelatonetwork/relay-sdk";
import { ethers } from "ethers";

const relay = new GelatoRelay();

const COUNTER_ADDRESS = "0xEEeBe2F778AA186e88dCf2FEb8f8231565769C27";
const SPONSOR_API_KEY = process.env.SPONSOR_API_KEY;

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const abi = ["function increment()"];
const contract = new ethers.Contract(COUNTER_ADDRESS, abi, signer);
const { data } = await contract.increment.populateTransaction();

const request: SponsoredCallRequest = {
  chainId: (await provider.getNetwork()).chainId,
  target: COUNTER_ADDRESS,
  data: data,
};

const relayResponse = await relay.sponsoredCall(request, SPONSOR_API_KEY);
console.log(`Task ID: ${relayResponse.taskId}`);

// Manual polling for status
const interval = setInterval(async () => {
  const status = await relay.getTaskStatus(relayResponse.taskId);
  if (status?.taskState === "ExecSuccess") {
    console.log(`Transaction hash: ${status.transactionHash}`);
    clearInterval(interval);
  }
}, 2000);

import { createGelatoEvmRelayerClient } from "@gelatocloud/gasless";
import { encodeFunctionData } from "viem";
import { baseSepolia } from "viem/chains";

const COUNTER_ADDRESS = "0xEEeBe2F778AA186e88dCf2FEb8f8231565769C27";

const relayer = createGelatoEvmRelayerClient({
  apiKey: process.env.GELATO_API_KEY,
});

const data = encodeFunctionData({
  abi: [{ name: "increment", type: "function", inputs: [], outputs: [] }],
  functionName: "increment",
});

const id = await relayer.sendTransaction({
  chainId: baseSepolia.id,
  to: COUNTER_ADDRESS,
  data: data,
});

console.log(`Task ID: ${id}`);

// Built-in receipt waiting
try {
  const receipt = await relayer.waitForReceipt({ id });
  console.log(`Transaction hash: ${receipt.transactionHash}`);
} catch (error) {
  console.log(`Transaction failed: ${error.message}`);
}

Migrating from ERC-2771 or SyncFee?

If you were using sponsoredCallERC2771, callWithSyncFee, or callWithSyncFeeERC2771, these methods are not available in the new Gasless SDK. See the dedicated migration guides:

ERC-2771 Migration

Migrate from trusted forwarders to your own forwarder

SyncFee Migration

Migrate from SyncFee to sponsored transactions

Migration Checklist

Uninstall @gelatonetwork/relay-sdk
Install @gelatocloud/gasless and viem
Replace new GelatoRelay() with createGelatoEvmRelayerClient()
Replace sponsoredCall() with sendTransaction({ chainId, to, data })
Update target field to to in request
Replace manual polling with waitForReceipt() or use sendTransactionSync()
If using ERC-2771 or SyncFee, follow the dedicated migration guides above
Test on testnet
Deploy to production

Need Help?

If you have questions about migrating from the Relay SDK, please reach out through our GitHub.

​What’s Being Deprecated?

​What’s Supported in the Gasless SDK?

​Migration Overview

​Migration Steps

​Key Differences

​API Key Configuration

​Request Format

​Complete Migration Example

​Migrating from ERC-2771 or SyncFee?

ERC-2771 Migration

SyncFee Migration

​Migration Checklist

​Need Help?

What’s Being Deprecated?

What’s Supported in the Gasless SDK?

Migration Overview

Migration Steps

Key Differences

API Key Configuration

Request Format

Complete Migration Example

Migrating from ERC-2771 or SyncFee?

Migration Checklist

Need Help?