Deposit Addresses

Bridge assets by sending funds to a deposit address — no wallet connection or signing required.

export const SolverCurrencies = ({id}) => {
  const key = 'solver-currencies-data';
  if (typeof window === "undefined") {
    return null;
  }
  if (typeof document === "undefined") {
    return null;
  }
  if (!window[key]) {
    window[key] = {
      fetching: false,
      data: null,
      observer: null
    };
  }
  if (!window[key].fetching) {
    const showLoading = () => {
      const rootElement = document.getElementById(id);
      if (!rootElement) {
        return;
      }
      rootElement.innerHTML = `<tr><td colspan="2" style="text-align: center; padding: 20px;">Loading...</td></tr>`;
    };
    const appendCurrencies = data => {
      const rootElement = document.getElementById(id);
      if (!rootElement) {
        return;
      }
      const priorityChains = ['Ethereum', 'Base', 'Arbitrum', 'Optimism', 'BNB', 'Polygon', 'Solana', 'Bitcoin'];
      const rows = data.filter(chain => chain.solverCurrencies && chain.solverCurrencies.length > 0).slice().sort((a, b) => {
        const aIndex = priorityChains.indexOf(a.displayName);
        const bIndex = priorityChains.indexOf(b.displayName);
        if (aIndex !== -1 && bIndex !== -1) {
          return aIndex - bIndex;
        }
        if (aIndex !== -1) return -1;
        if (bIndex !== -1) return 1;
        return a.displayName.localeCompare(b.displayName);
      }).map(chain => {
        const currencies = chain.solverCurrencies.slice().sort((a, b) => {
          const priority = ['ETH', 'USDC', 'USDT', 'WETH'];
          const aIndex = priority.indexOf(a.symbol);
          const bIndex = priority.indexOf(b.symbol);
          if (aIndex !== -1 && bIndex !== -1) {
            return aIndex - bIndex;
          }
          if (aIndex !== -1) return -1;
          if (bIndex !== -1) return 1;
          return a.symbol.localeCompare(b.symbol);
        }).map(c => c.symbol).join(', ');
        return `<tr key=${chain.id}>
          <td>${chain.displayName}</td>
          <td>${currencies}</td>
        </tr>`;
      });
      rootElement.innerHTML = `<div id="${id}-marker"></div>${rows.join("")}`;
      if (!window[key].observer) {
        let observer = new MutationObserver(function (mutations) {
          if (!document.getElementById(`${id}-marker`)) {
            appendCurrencies(data);
          }
        });
        observer.observe(document.body, {
          childList: true,
          subtree: true
        });
        window[key].observer = observer;
      }
    };
    const fetchChains = async () => {
      try {
        if (window[key].fetching) return;
        window[key].fetching = true;
        window[key].data = null;
        showLoading();
        const response = await fetch("https://api.relay.link/chains");
        const data = await response.json();
        window[key].fetching = false;
        window[key].data = data.chains;
        appendCurrencies(data.chains);
      } catch (e) {
        console.error('Error fetching chains:', e);
        window[key].fetching = false;
        window[key].data = false;
      }
    };
    if (window[key].data) {
      appendCurrencies(window[key].data);
    } else {
      showLoading();
      fetchChains();
    }
  }
  return <table style={{
    width: "100%"
  }} className="relay-table">
<thead style={{
    borderBottom: "1px solid rgb(227 226 230)",
    paddingBottom: 5,
    width: "100%",
    fontSize: 16
  }}>
<tr style={{
    textAlign: "left"
  }}>
<th>Chain</th>
<th>Solver Currencies</th>
</tr>
</thead>
<tbody id={id}></tbody>
</table>;
};

Deposit addresses let users bridge or swap tokens by simply sending funds to an address — no wallet connection or signing required. This works for both cross-chain bridges and same-chain swaps. The integrator requests a quote with useDepositAddress: true, receives a deposit address, and the user transfers funds there. Relay detects the deposit and fills on the destination chain.

This makes deposit addresses ideal for CEX withdrawals, fiat onramps, and headless systems where the sender can't sign transactions. The user just sends to an address — same UX as a normal transfer.

How It Works

1. Quote — Integrator requests a quote with useDepositAddress: true. The response includes a depositAddress and requestId.
2. User Deposit — User sends funds to the deposit address (wallet transfer or exchange withdrawal).
3. Detect + Sweep — Relay detects the deposit onchain and sweeps funds to the depository contract. For open-ended addresses, the amount, currency, and chain are validated and the quote may be regenerated if different from the original. For strict addresses, the deposit is validated against the original order.
4. Fill — Relay fills on the destination chain from pre-positioned liquidity. Funds are delivered to the recipient address.

Key Parameters

Address Reuse

Open deposit addresses can be reused for the same route (same origin currency, origin chain, destination currency, and destination chain). Each new deposit triggers a fresh quote and fill.

Strict addresses should not be presented as reusable. They are bound to the original order and intended for single-use payment instructions.

Open vs Strict Deposit Addresses

Relay supports two deposit address modes that differ in how flexible they are when handling deposits.

Open Deposit Addresses

Open-ended deposit addresses are the flexible mode for supported routes. They can handle variable deposit amounts, and on some supported chain families they can also adapt to a different supported input token or a deposit on a different chain within the same VM. Adapting to a different token or a wrong chain is not always automatic — recovery may require manual reindexing before the deposit is recognized.

• refundTo is recommended. Omitting refundTo disables automatic refund — there is no internal fallback.
• Best for: general-purpose integrations where you want tolerance for user variability.

Strict Deposit Addresses

Strict deposit addresses are bound to the original order and should be treated as predictable payment instructions. They are not flexible intake points.

• refundTo is required. The request will fail without it.
• Set strict: true in your /quote/v2 request.
• Best for: integrations that need predictable behavior and explicit refund handling (e.g., payment processors).

Comparison

Example Request and Response

Open Deposit Address

Bridging 0.01 ETH from Base to Optimism using an open deposit address:

curl -X POST \
    'https://api.relay.link/quote/v2' \
    -H 'Content-Type: application/json' \
    -d '{\n   "user": "0xF0AE622e463fa757Cf72243569E18Be7Df1996cd",\n   "originChainId": 8453,\n   "originCurrency": "0x0000000000000000000000000000000000000000",\n   "destinationChainId": 10,\n   "destinationCurrency": "0x0000000000000000000000000000000000000000",\n   "tradeType": "EXACT_INPUT",\n   "recipient": "0xF0AE622e463fa757Cf72243569E18Be7Df1996cd",\n   "amount": "100000000000000000",\n   "useDepositAddress": true,\n   "refundTo": "0xF0AE622e463fa757Cf72243569E18Be7Df1996cd"\n  }'

Strict Deposit Address

Same route, but using a strict deposit address. Note the addition of strict: true and the required refundTo:

Key differences in the strict request:

• strict is set to true
• refundTo is required — the request fails without it
• The deposit address is bound to this specific order and is not reusable

Quote Regeneration

When funds arrive at a deposit address, Relay evaluates what was sent versus what was originally quoted. How mismatches are handled depends on the deposit address mode.

Open-Ended Addresses

Same Token, Different Amount

• Exact match — The original quote is reused and the fill proceeds directly.
• More than quoted — A new quote is generated for the larger amount, and the fill proceeds.
• Less than quoted — If the smaller amount still covers fees and the minimum fill, a new quote is generated and the fill proceeds. If not, the deposit is refunded to the refundTo address (if set).

Different Token (Solver Currency)

On some chain families, if the user sends a different token that is a solver currency, Relay can regenerate the quote using the actual currency deposited and fill the order. This is not universal across all chains — some chain families will fail or refund on token mismatch. If a different supported token was sent and nothing happens immediately, use the reindex endpoint as a fallback.

Different Chain (Same VM)

Open and custodial deposit addresses exist at the same address across chains within a VM family (e.g. all EVM chains), so a deposit can land on a chain other than the one quoted. This is supported but not always automatic: Relay's background monitor watches the chain the address was registered on, so a wrong-chain deposit may not be recognized until it is reindexed.

If a wrong-chain deposit isn't picked up within a few minutes, trigger detection manually with the Deposit Address Reindex endpoint, setting targetChainId to the chain the funds actually landed on. Once detected, Relay sweeps the funds and proceeds with a fresh quote and fill.

Behavior varies by chain family — some families refund a wrong-chain deposit instead of re-routing it. Strict addresses have no wrong-chain recovery (see Strict Addresses).

Different Chain (Different VM)

This is not possible — deposit address formats differ across VM types (e.g., EVM vs Solana vs Bitcoin), so a user cannot accidentally send to the wrong VM.

Strict Addresses

Strict addresses are bound to the original order. The handling is narrower:

• Exact amount — The fill proceeds using the original order.
• Underpayment — The deposit fails and is refunded to refundTo. The fill does not proceed.
• Overpayment — The fill proceeds for the originally quoted amount and the excess is returned to refundTo as a separate refund leg. The fill itself is never scaled up.
• Wrong token or wrong chain — Not supported. Strict addresses do not have automatic wrong-token or wrong-chain recovery paths.

Refund Behavior

What happens when a deposit can't be processed depends on the token type and the refundTo configuration.

Refund Flows

There are two distinct refund scenarios:

1. Correct currency, fill failed (e.g., slippage, network issues) — If refundTo is set, the deposit is automatically refunded to that address, minus the cost of gas. No additional fees are taken.
2. Wrong currency (non-solver token) — Not supported and not currently recoverable.

refundTo Configuration

recoveryAddress

recoveryAddress is for cases where Relay cannot auto-refund. It should be an integrator-controlled EOA on the origin chain.

Use recoveryAddress when an integrator wants to use Relay's depositor detection, but also needs a fallback recovery path if the detected depositor cannot safely receive an automatic refund. This is most relevant for deposits from custodial sources like centralized exchanges, unsupported currency deposits, or blocked depositor addresses.

When recoveryAddress is supplied:

• Relay still attempts to auto-refund where possible.
• If Relay cannot auto-refund, the integrator can recover funds using recoveryAddress.
• Existing refundTo behavior remains unchanged for flows that do not supply recoveryAddress.

Recommended Setup

• Open deposit addresses: Set refundTo to the user's address for automatic refunds.
• Strict deposit addresses: Always set refundTo. If the sender is unknown (e.g., CEX withdrawal), use an app-controlled address so your support team can manage refunds.
• Auto-refund to depositor: When users deposit from wallets they control, you can pass refundTo as the origin chain's native-currency address (EVM 0x0000000000000000000000000000000000000000, Bitcoin bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8, Solana 11111111111111111111111111111111) to refund to the original depositor automatically. The first of the two resulting outTxs is the transfer to the depositor — track that one for refund delivery. Avoid this when deposits may originate from a centralized exchange, or pair it with a recoveryAddress so funds Relay cannot safely auto-refund remain recoverable.

Tracking Transactions

Querying by Deposit Address

The most reliable way to track deposit address transactions is to poll the Get Requests API using the depositAddress query parameter:

curl -X GET "https://api.relay.link/requests/v2?depositAddress=<DEPOSIT_ADDRESS>&sortBy=updatedAt&sortDirection=desc&limit=20"

Handling Quote Regeneration

When a quote is regenerated (different amount, token, or chain), a new requestId may be generated. Use includeChildRequests=true to find all related requests, including regenerated ones:

curl -X GET "https://api.relay.link/requests/v2?depositAddress=<DEPOSIT_ADDRESS>&includeChildRequests=true"

Caveats

Gas Overhead

Deposit addresses add gas overhead compared to direct calldata execution because Relay must sweep funds from the deposit address:

For very small amounts, the gas overhead may make deposit addresses less cost-effective than direct calldata execution.

Supported Currencies

Only tokens listed as solver currencies for a given chain can be processed by deposit addresses. The input token must be a solver-depositable currency for the requested route. The destination token can differ and be completed through a destination-side swap — in that case, refundTo is required.

Relay treats certain tokens as equivalent within currency groups (e.g., ETH and WETH) — depositing any token in a group triggers the same fill behavior.

Other Limitations

• Calldata execution on destination is not allowed.