Gas on arrival

Gas on arrival delivers a small amount of the destination chain's native gas token (ETH on Arbitrum or Base, POL on Polygon, BNB on BNB Chain…) to the recipient together with the swap output. Someone bridging USDC to a chain they have never used can then move or swap it right away, without first finding gas. Add gasOnArrival=true to GET /v1/quote; quotes that include it report what they add in gasOnArrival.

When does it apply?#

Gas on arrival applies to a route when all of these hold:

• it is cross-chain (srcChain ≠ dstChain);
• the destination is an EVM chain (not Solana, and not Hyperliquid, where trading needs no gas);
• the output token is not already the native coin (USDC → ETH needs no extra ETH).

Otherwise the parameter is ignored, never an error. Today Relay delivers gas on arrival. Other providers ignore the request, and their quotes have no gasOnArrival. When you ask for gas, quotes that include it rank first: their dstAmount is lower by the gas they add, so comparing them with routes that skip it would always put them last.

Request it#

curl "https://api.layerhop.com/v1/quote?srcChain=base&srcToken=USDC&amount=20000000\
&dstChain=arbitrum&dstToken=USDC&sender=0xYou&recipient=0xYou&gasOnArrival=true"

With the TypeScript SDK, pass gasOnArrival: true (for $2) or a USD amount:

const { best } = await lh.quote({
  srcChain: "base", srcToken: "USDC", amount: "20000000",   // 20 USDC
  dstChain: "arbitrum", dstToken: "USDC",
  sender: address, recipient: address,
  gasOnArrival: true,                                       // or 5 for $5
});

Read the quote#

A quote that includes gas carries gasOnArrival:

{
  "provider": "relay",
  "dstAmount": "17919945",
  "gasOnArrival": {
    "amount": "832291636081249",
    "token": "0x0000000000000000000000000000000000000000",
    "symbol": "ETH",
    "decimals": 18,
    "usd": 2
  }
}

• amount is in base units of the native token (here 0.000832 ETH), sent to recipient on the destination chain.
• The gas is paid out of the swap: dstAmount is already lower by its value (about 18 USDC instead of about 20 for 20 USDC in). Nothing extra is charged on the source chain.
• LayerHop's fee is unchanged: it is a percentage of the input, as always (see Fees & channels). The provider fee in fees.providerFeeUsd does not include the gas itself.
• No gasOnArrival on a quote means that route delivers no gas, even if you asked for it. Show the user which one they picked.

The swap is still one transaction from the user's wallet; nothing changes when you build and send it.

In the swap app and widget#

The LayerHop swap app shows a Get gas on arrival switch when the route qualifies (cross-chain, EVM destination, output not native), and adds a Gas on arrival line to the route details. The embeddable widget has the same switch; pass gasOnArrival=1 (or gasOnArrival: true to mount()) to start with it on. Your users can still turn it off.

Limits#

• $0.50 to $20 per swap. Too little input for the gas plus fees returns AMOUNT_TOO_SMALL from Relay; other routes may still quote without gas.
• Deposit addresses don't take gas on arrival yet.