Adapters - Relay

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

What is an adapter anyway?

An adapter is a function that takes parameters and returns an object that adheres to this interface. Let’s review the interface in depth:

What adapters are available out of the box?

The following adapters are officially maintained and developed by the Relay team:

• SVM Adapter: This adapter gives the sdk the ability to submit transactions on SVM (Solana Virtual Machine) networks. It does not support signing messages and under the hood it uses the solana web3 sdk.
• Bitcoin Adapter: This adapter gives the sdk the ability to submit transactions to the Bitcoin blockchain. Under the hood it uses bitcoinjs-lib to sign and submit transactions. Note that bitcoin transactions have a long finalization period and unlike quicker vms are not polled in real time for confirmation.
• Viem Adapter: This adapter is the default one used when no adapter is provided. You can also import it yourself to convert any viem wallet client into an adapted wallet ready to be used in the sdk.
• Ethers Adapter: If your application uses ethers then you’ll need this adapter to use the SDK. You’ll still need to install viem as that’s required for polling transactions but you can pass in your ethers signer to submit transactions and sign messages.
• Tron Adapter: This adapter gives the sdk the ability to submit transactions to the Tron blockchain. Under the hood it uses the tronweb sdk.
• Lighter Adapter: This adapter gives the SDK the ability to deposit to Lighter from any Relay-supported chain. It owns the full Lighter session lifecycle — resolving the user’s Lighter account index, generating an in-memory API key, and registering it via changeApiKey on first transfer. Integrators who already run their own Lighter session (backend-provisioned key, wallet-level integration) can pass a pre-built signerClient to bypass the bootstrap entirely.
• TON Adapter: This adapter gives the SDK the ability to submit transactions on the TON blockchain. The user’s key stays in their wallet, so the adapter never signs — you pass a sendTransaction callback (for example wrapping Dynamic’s TON connector or TonConnect UI) that signs and broadcasts the request, while the adapter handles request building and on-chain confirmation. Confirmation reads use a read-only @ton/tonTonClient pointed at the TON chain’s httpRpcUrl from the Relay client’s chain configuration; to use a custom endpoint (e.g. a keyed provider in production), override that chain’s httpRpcUrl when configuring the SDK client rather than passing it to the adapter. TON support requires the @ton/core and @ton/ton peer dependencies in addition to viem and @relayprotocol/relay-sdk.

How can I use an adapter?

You can either make your own adapter, as long as it adheres to the interface above or you can use one of the officials adapters developed and maintained by the Relay team. All of our sdk methods handle a viem wallet or adapted wallet. The viem wallet adapter is used by default when a viem wallet is passed in for convenience. Refer below for implementation details:

Solana

import { getClient, Execute, getQuote } from "@relayprotocol/relay-sdk";
import { adaptSolanaWallet } from '@relayprotocol/relay-solana-wallet-adapter'
import { Connection, Keypair, clusterApiUrl, SystemProgram, Transaction } from '@solana/web3.js';
...

//In this example we are loading a keypair as the wallet, but if you have a connector like dynamic you can just fetch the connection from that library
const wallet = Keypair.generate();
const connection = new Connection(clusterApiUrl('devnet'), 'confirmed');
const walletAddress = wallet.publicKey.toString()

const adaptedWallet = adaptSolanaWallet(
  walletAddress,
  792703809, // Chain ID that Relay uses to identify Solana
  connection, // The Solana web3.js Connection instance for interacting with the network
  connection.sendTransaction // Function to sign and send a transaction, returning a promise with a base58 encoded transaction signature
)

const options = ... // define this based on getQuote options

const quote = await getClient().actions.getQuote(options)

getClient().actions.execute({
  quote,
  wallet: adaptedWallet,
  onProgress: ({steps, fees, breakdown, currentStep, currentStepItem, txHashes, details}) => {
        // custom handling
  },
  ...
})

Viem

import { getClient, Execute, getQuote, adaptViemWallet } from "@relayprotocol/relay-sdk";
import { createWalletClient } from 'wagmi'
import { mainnet } from 'viem/chains'

...

const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum!)
})

const options = ... // define this based on getQuote options

const quote = await getClient().actions.getQuote(options)

getClient().actions.execute({
  quote,
  wallet: adaptViemWallet(walletClient),
  onProgress: ({steps, fees, breakdown, currentStep, currentStepItem, txHashes, details}) => {
        // custom handling
  },
  ...
})

Bitcoin

import { getClient, Execute, getQuote } from "@relayprotocol/relay-sdk";
import { adaptBitcoinWallet } from '@relayprotocol/relay-bitcoin-wallet-adapter'
import { createWalletClient } from 'wagmi'
import { mainnet } from 'viem/chains'

...

const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum!)
})

const options = ... //define this based on getQuote options

const quote = await getClient().actions.getQuote(options)

const adaptedWallet = adaptBitcoinWallet(
  primaryWallet.address,
  async (_address, _psbt, dynamicParams) => {
    try {
      // Request the wallet to sign the PSBT (this is using dynamic but you could use whatever framework you want)
      const response = await primaryWallet.signPsbt(dynamicParams)
      if (!response) {
        throw 'Missing psbt response'
      }
      return response.signedPsbt
    } catch (e) {
      throw e
    }
  }
)

getClient().actions.execute({
  quote,
  wallet: adaptedWallet,
  onProgress: ({steps, fees, breakdown, currentStep, currentStepItem, txHashes, details}) => {
        //custom handling
  },
  ...
})

Ethers

import { getClient } from '@relayprotocol/relay-sdk'
import { adaptEthersSigner } from '@relayprotocol/relay-ethers-wallet-adapter'
import { useSigner } from 'wagmi'

...

const { data: signer } = useSigner()
const adaptedWallet = adaptEthersSigner(signer)

const options = ... //define this based on getQuote options

const quote = await getClient().actions.getQuote(options)

#### Tron

```javascript
import { TronWallet } from 'tronweb'
import { getClient, Execute, getQuote } from "@relayprotocol/relay-sdk"
import { adaptTronWallet } from '@relayprotocol/relay-tron-wallet-adapter'

// Create a TronWeb instance, we recommend using a provider like dynamiclabs if using this on the frontend
// Note: you should never share your private key with anyone or use on the frontend
const tronWeb = new TronWeb({fullHost: 'xxx', privateKey: 'privateKey'});
const walletAddress = tronWeb.defaultAddress.base58
if (!tronWeb) {
  throw 'Unable to setup Tron wallet'
}

const adaptedWallet = adaptTronWallet(
  walletAddress,
  tronWeb
)
const options = ... //define this based on getQuote options

const quote = await getClient().actions.getQuote(options)

#### Lighter

```javascript
import { getClient, getQuote } from '@relayprotocol/relay-sdk'
import { adaptLighterWallet } from '@relayprotocol/relay-lighter-wallet-adapter'
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'

// Lighter deposits are authorized by an L1 (EVM) signature, so the adapter
// only needs the user's connected EVM address and a signMessage callback.
const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum!)
})

const [address] = await walletClient.requestAddresses()

const adaptedWallet = adaptLighterWallet({
  l1Address: address,
  signL1Message: (message) =>
    walletClient.signMessage({ account: address, message })
})

const options = ... // define this based on getQuote options (destinationChainId: 3586256, recipient: <Lighter account index>)

const quote = await getClient().actions.getQuote(options)

getClient().actions.execute({
  quote,
  wallet: adaptedWallet,
  onProgress: ({ steps, fees, breakdown, currentStep, currentStepItem, txHashes, details }) => {
    // custom handling
  }
})

TON

import { getClient, Execute, getQuote } from "@relayprotocol/relay-sdk"
import { adaptTonWallet } from '@relayprotocol/relay-ton-wallet-adapter'

// The user's key lives in their TON wallet, so the adapter never signs. You
// provide a sendTransaction callback that forwards the TonConnect-style request
// to your wallet provider (e.g. Dynamic's TON connector or tonConnectUI), signs
// + broadcasts it, and returns the result. The adapter accepts a signed
// external-message { boc } (what most TonConnect wallets return) or a
// { transactionHash }. The confirmation RPC is read from the TON chain's
// httpRpcUrl in your Relay client config — there is no adapter-level endpoint.
const adaptedWallet = adaptTonWallet(walletAddress, async (request) => {
  const { boc } = await wallet.sendTransaction(request)
  return { boc }
})

const options = ... // define this based on getQuote options

const quote = await getClient().actions.getQuote(options)

getClient().actions.execute({
  quote,
  wallet: adaptedWallet,
  onProgress: ({ steps, fees, breakdown, currentStep, currentStepItem, txHashes, details }) => {
    // custom handling
  },
  ...
})

Viem adapter options

adaptViemWallet accepts an optional second argument for adapter-level configuration:

import { adaptViemWallet } from "@relayprotocol/relay-sdk";

const adaptedWallet = adaptViemWallet(walletClient, {
  disableCapabilitiesCheck: true,
});

The same flag is available directly on getQuote, execute, and claimAppFees when you pass a raw viem WalletClient — the SDK forwards it to adaptViemWallet internally.