Skip to main content
Trails is designed with user sovereignty at its core. While the protocol includes automatic refund mechanisms for failed transactions, users always retain full control over their funds and can initiate manual recovery at any time.

​
Automatic Refunds

Trails has an automatic refund mechanism built in to protect your assets in the event of a transaction failure. The protocol handles refunds automatically without requiring user intervention:
Failure ScenarioRefund Action
Failure on the Source ChainIf the transaction fails before your funds leave the initial blockchain, the user receives a full refund (minus gas fees) on the source chain to the sender address.
Failure on the Destination ChainIf the funds successfully bridged but the final step fails on the destination chain, the assets are refunded to your sender address on the destination chain.
For more details on how refunds work within the Trails architecture, see the How Trails Works documentation.

​
User Control & Ownership

Trails is non-custodial by design. Only the user always retains control over their account and funds:
  • Intent-Scoped Authorization: Intent addresses only authorize the specific transaction calldata the user has explicitly permitted—nothing more
  • User Control: Users can take direct action over their funds at any time, even in emergencies
  • Non-Custodial: Trails never takes custody; execution happens via the user’s wallet permissions, preserving full control and auditability
The user’s wallet is the only party with control over the intent address. This cryptographic guarantee ensures the funds are always recoverable.
Recovery is implemented in the Trails Explorer as well as in the Transaction History within the Trails Widget which will automatically detect intents that are eligible for a recovery.

​
Manual Fund Recovery with useTrailsRefund

While Trails automatically refunds upon transaction failures, there may be edge cases where funds are stuck without an explicit revert. The useTrailsRefund hook provides utilities to manually sign and execute refund transactions to recover funds from intent addresses if you’d like to add to your own app.

​
Basic Usage

import { useTrailsRefund } from '0xtrails'
import { useWalletClient, useAccount } from 'wagmi'

export const RefundComponent = ({ intentId }: { intentId: string }) => {
  const { data: walletClient } = useWalletClient()
  const { address } = useAccount()

  const {
    intent,
    isLoadingIntent,
    hasIntentBalance,
    signPayload,
    getRefundTx,
    intentError,
  } = useTrailsRefund({
    intentId,
    walletClient,
    refundToAddress: address, // Optional: defaults to connected wallet
  })

  const handleRefund = async () => {
    try {
      // Step 1: Sign the refund payload
      const { signature, payload } = await signPayload()
      
      // Step 2: Get the refund transaction
      const refundTx = await getRefundTx({
        signedHash: signature,
        payload,
      })
      
      // Step 3: Execute the refund transaction
      const txHash = await walletClient.sendTransaction({
        to: refundTx.to,
        data: refundTx.data,
        chain: refundTx.chain,
      })
      
      console.log('Refund transaction sent:', txHash)
    } catch (error) {
      console.error('Refund failed:', error)
    }
  }

  if (isLoadingIntent) return <div>Loading intent...</div>
  if (intentError) return <div>Error: {intentError.message}</div>
  if (!hasIntentBalance) return <div>No balance to refund</div>

  return (
    <button onClick={handleRefund}>
      Recover Funds
    </button>
  )
}

​
When to Use Manual Refunds

Automatic Refunds

Most common scenario — Trails automatically handles refunds when transactions explicitly fail or revert. No user action required.

Manual Recovery

Edge cases only — Use useTrailsRefund when funds are stuck without an explicit revert, or when you want to proactively recover funds from a pending intent.

​
Security Guarantees

The refund mechanism maintains Trails’ security principles:
  • Only the original sender can authorize refunds via wallet signature
  • Cryptographic verification ensures refund transactions are valid
  • Non-custodial — Trails cannot access or move your funds without your signature
  • Onchain execution — All refund operations are verifiable onchain
For more information, see: