Layerswap
Layerswap manual transfers fund swaps through deposit addresses
Layerswap manual transfers fund a swap by sending the selected source token to a deposit address that Layerswap assigns to that swap. The payment can come from a wallet or exchange on a supported source network. Layerswap waits for enough source confirmations before processing the route toward the chosen destination token and recipient. Completion requires delivery at that destination; a successful source payment establishes funding, while the payout transaction records the receiving-side transfer.
Key takeaway: A supplied source-network refund address enables execution refunds after exhausted retries, unless the refund amount is smaller than gas fees.
The deposit address and the destination recipient
The deposit address receives the source payment, while the destination address identifies the recipient on the receiving network. The selected source token funds the request; the route determines which asset can arrive at the destination. A swap ID connects the overall request with its deposit, payout and any refund transactions. Each transaction also has its own type and status, so funding and destination execution remain separately observable.
What does the sender authorize during a manual transfer?
The sender authorizes a source-network payment to the assigned deposit address through a wallet transaction or an exchange withdrawal.
Deposit-address funding requires no source-side wallet connection to the Layerswap interface. The address or QR code supports payment from a wallet app, hardware wallet or exchange account. The sender uses that source's own authorization process and the source network, token and exact amount shown in the manual-transfer instructions. The source payment moves tokens from the sending balance to the swap's assigned deposit address. When an on-chain transaction is required, its sender normally pays the source-network fee. The amount that Layerswap actually receives determines whether the deposit meets the route minimum.
Quote fields and the refund recipient
Quote fields distinguish the source-token payment from the estimated destination payout. The swap request can also supply a source-network recipient for an execution refund.
| Field | Value and scope | Execution or recovery condition |
|---|---|---|
requested_amount
|
Intended send amount in source-token units | Quote creation fails if the source amount is outside the selected route's live limits. |
receive_amount
|
Estimated payout in destination-token units | A quote alone does not establish delivery. |
min_receive_amount
|
Minimum destination amount after applying the quote's slippage tolerance | Unmet slippage tolerance triggers execution retries. |
refund_address
|
Specified refund recipient on the source network |
Enables
pending_refund
after exhausted execution retries.
|
Limits and pricing can change with the funding method, destination address or Refuel selection. Keep those options consistent across limits, quoting and swap creation. Changing an option calls for refreshed limits and a fresh quote before funding. An ordinary quote estimates the outcome for one chosen amount. A detailed quote instead describes the route's fixed and percentage fee components and supported amount range.
From source confirmation to destination execution
A swap moves into processing after the source deposit reaches the required confirmations. The quote's path lists the providers expected to execute the route in order. Bridging and token conversion can both contribute to the payout, depending on the selected pair. The swap's transaction list distinguishes deposit, payout, Refuel and refund operations when they occur. Each entry describes its own operation; the overall status describes the swap.
Which transaction confirms that the recipient received funds?
The destination blockchain's successful payout record confirms delivery when its asset movement matches the selected recipient, network and token. Inspect the actual transfer amount and relate its transaction hash to the swap. A transaction hash provides a lookup identifier; the successful asset movement supplies the evidence. A pending payout transaction shows an intermediate state without establishing that funds reached the recipient.
Layerswap uses
completed
for the swap-level state in which funds have reached the destination address. Its Explorer provides a public view of swap progress and related transactions. Save the swap ID alongside the relevant source and destination hashes so the payment and settlement remain traceable across both networks.
Why can a swap remain pending after its source payment confirms?
A swap can remain pending after its source payment confirms while it awaits further confirmations or destination execution. The
user_transfer_pending
state means that Layerswap still awaits the
source transaction. A deposit must reach the required confirmations before processing starts, so a source receipt alone does not establish that Layerswap can execute the destination leg.
An unfunded swap expires if no deposit arrives within 6 hours. That
user_transfer_pending
window does not set a completion deadline for a funded swap.
The
ls_transfer_pending
state covers execution after sufficient source confirmations. Layerswap retries when execution encounters liquidity shortages, unavailable routes, slippage, blockchain problems or decentralized exchange issues. A deposit below the minimum receives
failed
status. That funding condition differs from an execution problem that triggers the retry-and-refund branch.
A supplied
refund_address
allows exhausted execution retries to move the swap into
pending_refund
and then
refunded
.
Execution refunds return the source token on the source network, less gas fees.
If the refund amount is smaller than the gas fee, Layerswap issues no refund. The refund recipient therefore needs an address on the source network.
Without
refund_address
, an execution problem leaves the swap in
ls_transfer_pending
while Layerswap keeps retrying until resolution. A pending state establishes neither an automatic refund nor a delivered payout. Inspect that swap's current status and related transactions before treating the transfer as resolved.
Funding availability for the next request
Deposit-address funding requires support for that method on the selected source network and route. A supported network name alone does not establish every source-token and destination-token pairing. The API distinguishes general network support from currently routable sources and destinations. The Deposit Widget can offer deposit-address funding for a fixed destination, with available methods determined by the route. Its method allow-list cannot enable an unsupported payment path.
For a new transfer, review the current funding instructions and destination quote before sending the source payment. Confirm that the intended source amount remains within the applicable limits, then retain the destination recipient and any refund recipient with the swap ID. A changed route, funding method or Refuel setting calls for updated limits and pricing. Proceed with the quoted configuration or choose another available route before funding the new request.
Layerswap manual transfers FAQs
Does a gasless signature replace a manual payment to a deposit address?
Gasless funding uses a separate authorization flow on supported routes and tokens. The user signs the exact EIP-712 payload that the API supplies, and a relayer submits the deposit. The relayer pays source-network gas, with that cost included in the gasless quote. If authorization fails, use another supported funding method; do not reconstruct the signing payload.
Are deposit-address funding and Depository funding interchangeable?
Deposit-address funding and Depository funding require different source actions. The first receives a transfer to an assigned address; the second uses the contract call that the API returns. A swap request cannot enable both use_deposit_address and use_depository. Follow the returned action for the selected method rather than treating a Depository contract address as ordinary payment instructions.
Where can an integration find a manual swap using its funding transaction hash?
An integration can look up the swap through GET /swaps/by_transaction_hash/{hash}. The funding transaction hash helps locate the associated request when the swap ID is unavailable. Inspect the returned overall status and related transactions to distinguish a detected source payment from completed destination delivery.
How do API status filters differ from returned manual-swap statuses?
The GET /swaps filter accepts status names that differ from those returned in swap responses. For example, a response uses pending_refund, while the corresponding filter value is PendingRefund. Preserve the spelling required by each interface when locating manual transfers; copying a response status directly into a filter can use the wrong value.
Will Refuel arrive within the main destination-token payout?
Refuel sends a separate native-token top-up on supported destination routes. Its cost comes from the source amount and reduces the quoted destination-token receive amount. The quote reports that cost in refuel_in_source rather than total_fee, while data.refuel describes the top-up asset and amount. The swap can include a separate refuel transaction.
Is the quoted completion time a deadline for a manual transfer?
The quote's avg_completion_time is a historical average rather than a completion deadline. It describes the selected route using a .NET-style duration string. Network confirmations and route execution determine when an individual funded swap progresses, so the estimate does not establish a fixed arrival time.