> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gelato.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Relay SDK to Gasless SDK Migration

> Migrate from @gelatonetwork/relay-sdk sponsoredCall to @gelatocloud/gasless

<Warning>
  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.
</Warning>

## 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](/gasless-with-relay/additional-resources/migration-to-turbo-relayer/erc2771)
* `callWithSyncFee()` and `callWithSyncFeeERC2771()` methods — **no longer supported**, see [SyncFee Migration Guide](/gasless-with-relay/additional-resources/migration-to-turbo-relayer/syncFee)

```typescript theme={null}
// 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](/gasless-with-relay/additional-resources/migration-to-turbo-relayer/erc2771) |
| `callWithSyncFee()`        | **Not supported** — see [SyncFee Migration Guide](/gasless-with-relay/additional-resources/migration-to-turbo-relayer/syncFee)  |
| `callWithSyncFeeERC2771()` | **Not supported** — see [SyncFee Migration Guide](/gasless-with-relay/additional-resources/migration-to-turbo-relayer/syncFee)  |

## 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

<Steps>
  <Step title="Update Dependencies">
    Remove the old SDK and install the new one:

    ```bash theme={null}
    # Remove old SDK
    npm uninstall @gelatonetwork/relay-sdk

    # Install new SDK
    npm install @gelatocloud/gasless viem
    ```
  </Step>

  <Step title="Update Imports">
    **Before (Relay SDK):**

    ```typescript theme={null}
    import { GelatoRelay, SponsoredCallRequest } from "@gelatonetwork/relay-sdk";
    ```

    **After (Gasless SDK):**

    ```typescript theme={null}
    import { createGelatoEvmRelayerClient } from "@gelatocloud/gasless";
    ```
  </Step>

  <Step title="Update Client Initialization">
    **Before (Relay SDK):**

    ```typescript theme={null}
    const relay = new GelatoRelay();
    ```

    **After (Gasless SDK):**

    ```typescript theme={null}
    const relayer = createGelatoEvmRelayerClient({
      apiKey: process.env.GELATO_API_KEY,
    });
    ```
  </Step>

  <Step title="Update Sponsored Call">
    **Before (Relay SDK):**

    ```typescript theme={null}
    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):**

    ```typescript theme={null}
    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}`);
    }
    ```
  </Step>

  <Step title="Update Status Tracking">
    **Before (Relay SDK):**

    ```typescript theme={null}
    const relayResponse = await relay.sponsoredCall(request, apiKey);
    const taskId = relayResponse.taskId;

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

    **After (Gasless SDK):**

    ```typescript theme={null}
    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:

    ```typescript theme={null}
    // sendTransactionSync waits for inclusion and returns the receipt
    const receipt = await relayer.sendTransactionSync({
      chainId: baseSepolia.id,
      to: targetAddress,
      data: encodedData,
    });
    ```
  </Step>
</Steps>

## Key Differences

### API Key Configuration

**Before:** API key passed with every call

```typescript theme={null}
relay.sponsoredCall(request, SPONSOR_API_KEY);
```

**After:** API key configured once at client creation

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

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

### Request Format

**Before:**

```typescript theme={null}
const request: SponsoredCallRequest = {
  chainId: chainId,
  target: contractAddress,
  data: encodedData,
};
```

**After:**

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

## Complete Migration Example

<Tabs>
  <Tab title="Before (Relay SDK)">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="After (Gasless SDK)">
    ```typescript theme={null}
    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}`);
    }
    ```
  </Tab>
</Tabs>

## 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:

<CardGroup cols={2}>
  <Card title="ERC-2771 Migration" icon="arrow-right" href="/gasless-with-relay/additional-resources/migration-to-turbo-relayer/erc2771">
    Migrate from trusted forwarders to your own forwarder
  </Card>

  <Card title="SyncFee Migration" icon="arrow-right" href="/gasless-with-relay/additional-resources/migration-to-turbo-relayer/syncFee">
    Migrate from SyncFee to sponsored transactions
  </Card>
</CardGroup>

## 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](https://github.com/gelatodigital).