0xtrails 0.6.6 → 0.7.0

package/src/widget/hooks/usePayMessage.tsx

@@ -69,6 +69,7 @@ export function usePayMessage(): UsePayMessageReturn {
     toChainId,
     toAmount,
     toToken,
+    toCalldata,
   } = useWidgetProps()
 
   const { targetAmountUsdFormatted } = useTargetAmount()
@@ -121,12 +122,24 @@ export function usePayMessage(): UsePayMessageReturn {
         case "APP_DESCRIPTION":
           parts.push({ type: "text", value: appDescription || "" })
           break
-        case "TO_AMOUNT_USD":
-          parts.push({
-            type: "amount",
-            value: targetAmountUsdFormatted || "$0.00",
-          })
+        case "TO_AMOUNT_USD": {
+          const usdValue = targetAmountUsdFormatted || "$0.00"
+          // If USD value is $0, use token amount + symbol instead
+          if (usdValue === "$0.00" || usdValue === "$0") {
+            const tokenAmount = toAmount || "0"
+            const tokenSymbol = tokenInfo?.symbol || ""
+            parts.push({
+              type: "amount",
+              value: `${tokenAmount} ${tokenSymbol}`.trim(),
+            })
+          } else {
+            parts.push({
+              type: "amount",
+              value: usdValue,
+            })
+          }
           break
+        }
         case "TO_ADDRESS":
           parts.push({ type: "toAddress", value: toAddress || "" })
           break
@@ -228,11 +241,17 @@ export function usePayMessage(): UsePayMessageReturn {
           {/* Large amount in center */}
           <div className="font-bold text-center">
             {(() => {
-              const amountToShow = targetAmountUsdFormatted || toAmount || "0"
+              const usdValue = targetAmountUsdFormatted || "$0.00"
+              const tokenAmount = toAmount || "0"
               const tokenSymbol = tokenInfo?.symbol || ""
-              const displayText = targetAmountUsdFormatted
-                ? amountToShow
-                : `${amountToShow} ${tokenSymbol}`.trim()
+
+              // If USD value is $0, show token amount + symbol instead
+              const displayText =
+                usdValue === "$0.00" || usdValue === "$0"
+                  ? `${tokenAmount} ${tokenSymbol}`.trim()
+                  : targetAmountUsdFormatted
+                    ? usdValue
+                    : `${tokenAmount} ${tokenSymbol}`.trim()
 
               // Dynamic font size based on text length
               const textLength = displayText.length
@@ -255,8 +274,8 @@ export function usePayMessage(): UsePayMessageReturn {
           {/* Recipient info below */}
           {toAddress && (
             <div className="flex items-center space-x-2 text-center">
-              <span className="text-sm text-gray-600 dark:text-gray-400">
-                to
+              <span className="text-sm text-gray-900 dark:text-gray-100">
+                {toCalldata ? "to" : "Recipient"}
               </span>
               <Identicon value={toAddress} size={20} />
               <a
@@ -434,6 +453,7 @@ export function usePayMessage(): UsePayMessageReturn {
     tokenInfo,
     toChainId,
     toAddress,
+    toCalldata,
     targetAmountUsdFormatted,
     toAmount,
   ])

package/src/widget/hooks/usePriceImpactWarning.ts

@@ -11,7 +11,7 @@ const PriceImpactWarningContext =
 
 export const PriceImpactWarningProvider = PriceImpactWarningContext.Provider
 
-export const usePriceImpactWarning = (): PriceImpactWarningConfig => {
+export function usePriceImpactWarning(): PriceImpactWarningConfig {
   const context = useContext(PriceImpactWarningContext)
   return context || {}
 }

package/src/widget/hooks/useQuote.ts

@@ -14,29 +14,48 @@ import { prepareSend } from "../../prepareSend.js"
 import { abortControllerRegistry } from "../../abortController.js"
 import { TradeType } from "../../prepareSend.js"
 import { getChainInfo, useChainRpcClient } from "../../chains.js"
-import type { IntentTransaction } from "@0xsequence/trails-api"
+import type { IntentTransaction } from "@0xtrails/api"
 import type { PrepareSendOptions } from "../../transactionIntent/types.js"
 import type { Chain } from "../../chains.js"
-import type { SupportedToken } from "../../tokens.js"
+import type { Token } from "../../tokens.js"
 import type { TransactionState } from "../../transactions.js"
 import type { PrepareSendFees } from "../../prepareSend.js"
 import { getTokenPrice } from "../../prices.js"
 import { useCommitIntent, useExecuteIntent } from "../../mutations.js"
 import type { CheckoutOnHandlers } from "./useCheckout.js"
-import type { FeeOption } from "@0xsequence/trails-api"
-
+import type { FeeOption } from "@0xtrails/api"
+
+/**
+ * Configuration options for the `useQuote` hook.
+ *
+ * All parameters are optional, but the hook will not fetch a quote until all required
+ * parameters are provided (walletClient, fromTokenAddress, fromChainId, toTokenAddress,
+ * toChainId, swapAmount, toRecipient).
+ */
 export type UseQuoteProps = {
+  /** The wallet client from wagmi (e.g., from `useWalletClient()`). Required for quote fetching. */
   walletClient?: any // TODO: fix this, has to do with viem/wagmi versions
+  /** The contract address of the origin token. */
   fromTokenAddress?: string | null
+  /** The chain ID of the origin chain */
   fromChainId?: number | null
+  /** The contract address of the destination token. */
   toTokenAddress?: string | null
+  /** The chain ID of the destination chain. */
   toChainId?: number | null
+  /** Optional custom calldata for the destination chain. Used for executing arbitrary contract calls. */
   toCalldata?: string | null
+  /** The amount to swap, as a string or bigint in the token's smallest unit (wei/smallest unit). For example, 1 USDC (6 decimals) = '1000000'. */
   swapAmount?: string | bigint
+  /** The recipient address for the destination token. */
   toRecipient?: string | null
+  /** The trade type: `TradeType.EXACT_INPUT` (you specify input amount) or `TradeType.EXACT_OUTPUT` (you specify output amount). Defaults to `EXACT_OUTPUT`. */
   tradeType?: TradeType | null
+  /** Slippage tolerance as a decimal string or number (e.g., '0.005' for 0.5%, '0.01' for 1%). Defaults to a reasonable value if not provided. */
   slippageTolerance?: string | number | null
+  /** Optional callback function that receives transaction state updates during swap execution. */
   onStatusUpdate?: ((transactionStates: TransactionState[]) => void) | null
+  /** Optional quote provider ID to use. If not specified, the best available provider will be selected. */
   quoteProvider?: string | null
   /**
    * Optional checkout event handlers for tracking the states of a Trails transaction.
@@ -67,14 +86,26 @@ export type UseQuoteProps = {
    * - `triggerCheckoutStatusUpdate`
    */
   checkoutOnHandlers?: Partial<CheckoutOnHandlers>
+  /** Optional paymaster URL for gasless ERC-4337 transactions. */
   paymasterUrl?: string
+  /** Optional fee option selection (e.g., user selects USDC as the fee token instead of ETH) */
   selectedFeeOption?: FeeOption | null
+  /** Optional AbortSignal to cancel the quote request. */
   abortSignal?: AbortSignal
+  /** Optional API key override for Trails API access. */
   apiKey?: string | null
+  /** Optional environment override for node gateway ('prod' | 'dev' | 'local' | 'cors-anywhere'). */
   nodeGatewayEnv?: "prod" | "dev" | "local" | "cors-anywhere"
+  /** Optional flag to indicate if the wallet is a smart wallet. */
   isSmartWallet?: boolean | null
 }
 
+/**
+ * Return type for the `swap` function returned by {@link useQuote}.
+ *
+ * Contains information about both the origin and destination transactions,
+ * including transaction hashes, explorer URLs, and receipts.
+ */
 export type SwapReturn = {
   originTransaction: {
     transactionHash?: string | null
@@ -89,24 +120,35 @@ export type SwapReturn = {
   totalCompletionSeconds?: number
 }
 
+/**
+ * Information about a quote provider (LiFi, CCTP, Relay, etc.) used for routing the swap.
+ */
 export type QuoteProviderInfo = {
   id: string
   name: string
   url: string
 }
 
+/**
+ * A quote object containing all the details about a Trails intent transaction.
+ *
+ * Includes token amounts, fees, price impact, estimated completion time,
+ * and other relevant information for displaying to the user.
+ */
 export type Quote = {
   fromAmount: string
   fromAmountMin: string
   toAmount: string
   toAmountMin: string
-  originToken: SupportedToken
-  destinationToken: SupportedToken
+  originToken: Token
+  destinationToken: Token
   originChain: Chain
   destinationChain: Chain
   fees: PrepareSendFees
   slippageTolerance: string
   priceImpact: string
+  priceImpactUsd?: string
+  priceImpactUsdDisplay?: string
   completionEstimateSeconds: number
   transactionStates?: TransactionState[]
   originTokenRate?: string
@@ -118,19 +160,147 @@ export type Quote = {
   gasCostUsdDisplay?: string
   gasCost?: string
   gasCostFormatted?: string
+  totalFeesUsd?: number
+  totalFeesUsdDisplay?: string
+  totalGasUsd?: number
+  totalGasUsdDisplay?: string
+  allProviderFeesUsd?: number
+  allProviderFeesUsdDisplay?: string
 }
 
+/**
+ * Return type for the {@link useQuote} hook.
+ *
+ * Provides the quote data, swap function, loading state, error information,
+ * and utility functions for managing the quote lifecycle.
+ */
 export type UseQuoteReturn = {
+  /** The quote object with swap details, or `null` if not available. */
   quote: Quote | null
+  /** A function to execute the swap, or `null` if not available. Returns a Promise that resolves to swap result with transaction receipts. */
   swap: (() => Promise<SwapReturn | null>) | null
+  /** Boolean indicating if a quote is currently being fetched. */
   isLoadingQuote: boolean
+  /** Any error that occurred while fetching the quote, or `null`. */
   quoteError: unknown
+  /** A user-friendly error message string. */
   quoteErrorPrettified: string
+  /** Function to manually refetch the quote (useful for refreshing stale quotes). */
   refetchQuote: () => void
+  /** Function to abort any in-flight quote requests. */
   abort: () => void
 }
 
 // TODO: consolidate useSendForm, prepareSend, and useQuote hooks into a single hook
+
+/**
+ * React hook for fetching quotes and executing cross-chain or same-chain intent transactions.
+ *
+ * This hook provides a simple interface to get quotes for intent transactions and execute them.
+ * It handles both cross-chain and same-chain intent transactions, automatically fetching token balances,
+ * calculating fees, and providing transaction state updates.
+ *
+ * @example
+ * Cross-chain swap example:
+ * ```tsx
+ * import { useQuote, TradeType } from '0xtrails'
+ * import { useEffect } from 'react'
+ * import { useWalletClient, useAccount } from 'wagmi'
+ *
+ * export const Swap = () => {
+ *   const { data: walletClient } = useWalletClient()
+ *   const { address } = useAccount()
+ *
+ *   const { quote, swap, isLoadingQuote, quoteError, refetchQuote } = useQuote({
+ *     walletClient,
+ *     fromTokenAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
+ *     fromChainId: 1, // Ethereum
+ *     toTokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
+ *     toChainId: 8453, // Base
+ *     swapAmount: '1000000', // 1 USDC (6 decimals)
+ *     tradeType: TradeType.EXACT_INPUT,
+ *     toRecipient: address,
+ *     slippageTolerance: '0.005', // 0.5%
+ *     onStatusUpdate: (states) => {
+ *       console.log('Transaction states:', states)
+ *     }
+ *   })
+ *
+ *   // Quotes can become stale; refetch every ~30 seconds
+ *   useEffect(() => {
+ *     const id = setInterval(() => {
+ *       refetchQuote?.()
+ *     }, 30000)
+ *     return () => clearInterval(id)
+ *   }, [refetchQuote])
+ *
+ *   const handleSwap = async () => {
+ *     if (!swap) return
+ *
+ *     try {
+ *       const result = await swap()
+ *       console.log('Swap completed:', result)
+ *     } catch (error) {
+ *       console.error('Swap failed:', error)
+ *     }
+ *   }
+ *
+ *   if (isLoadingQuote) return <div>Getting quote...</div>
+ *   if (quoteError) return <div>Error: {String(quoteError)}</div>
+ *   if (!quote) return <div>No quote available</div>
+ *
+ *   return (
+ *     <div>
+ *       <div>From: {quote.fromAmount} {quote.originToken.symbol}</div>
+ *       <div>To: {quote.toAmount} {quote.destinationToken.symbol}</div>
+ *       <button onClick={handleSwap}>Execute Swap</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @param props - Configuration options for the quote
+ * @param props.walletClient - The wallet client from wagmi (e.g., from `useWalletClient()`)
+ * @param props.fromTokenAddress - The contract address of the token to swap from.
+ * @param props.fromChainId - The chain ID of the origin chain
+ * @param props.toTokenAddress - The contract address of the token to swap to. Use `zeroAddress` for native tokens
+ * @param props.toChainId - The chain ID of the destination chain
+ * @param props.swapAmount - The amount to swap, as a string or bigint in the token's smallest unit (wei/smallest unit). For example, 1 USDC (6 decimals) = '1000000'
+ * @param props.tradeType - The trade type: `TradeType.EXACT_INPUT` (you specify input amount) or `TradeType.EXACT_OUTPUT` (you specify output amount). Defaults to `EXACT_OUTPUT`
+ * @param props.toRecipient - The recipient address for the destination token.
+ * @param props.slippageTolerance - Slippage tolerance as a decimal string or number (e.g., '0.005' for 0.5%, '0.01' for 1%). Defaults to a reasonable value if not provided
+ * @param props.toCalldata - Optional custom calldata for the destination chain. Used for executing arbitrary contract calls (e.g., swap and mint an NFT on destination chain)
+ * @param props.onStatusUpdate - Optional callback function that receives transaction state updates during swap execution
+ * @param props.quoteProvider - Optional quote provider ID to use (auto, lifi, relay, cctp, direct). If not specified, the best available provider will be selected
+ * @param props.checkoutOnHandlers - Optional event handlers for tracking checkout/transaction lifecycle events
+ * @param props.paymasterUrl - Optional paymaster URL for gasless ERC-4337 transactions
+ * @param props.selectedFeeOption - Optional fee option selection (e.g., user selects USDC as the fee token instead of ETH)
+ * @param props.abortSignal - Optional AbortSignal to cancel the quote request
+ * @param props.apiKey - Optional API key override for Trails API access
+ * @param props.nodeGatewayEnv - Optional environment override ('prod' | 'dev' | 'local' | 'cors-anywhere')
+ * @param props.isSmartWallet - Optional flag to indicate if the wallet is a smart wallet
+ *
+ * @returns An object containing:
+ * - `quote` - The quote object with swap details, or `null` if not available
+ * - `swap` - A function to execute the swap, or `null` if not available. Returns a Promise that resolves to swap result with transaction receipts
+ * - `isLoadingQuote` - Boolean indicating if a quote is currently being fetched
+ * - `quoteError` - Any error that occurred while fetching the quote, or `null`
+ * - `quoteErrorPrettified` - A user-friendly error message string
+ * - `refetchQuote` - Function to manually refetch the quote (useful for refreshing stale quotes)
+ * - `abort` - Function to abort any in-flight quote requests
+ *
+ * @remarks
+ * - The hook uses React Query internally, so quotes are cached and automatically refetched based on query key changes
+ * - Quotes are considered stale after 30 seconds. You may want to periodically call `refetchQuote()` to keep quotes fresh
+ * - The hook will not fetch a quote until all required parameters are provided (walletClient, token addresses, chain IDs, swap amount, recipient)
+ * - For native tokens (ETH, MATIC, etc.), use the zero address (`0x0000000000000000000000000000000000000000`)
+ *
+ * @see {@link TradeType} for available trade types
+ * @see {@link Quote} for the quote object structure
+ * @see {@link SwapReturn} for the swap result structure
+ *
+ * For more information go to {@link https://docs.trails.build/sdk/hooks#usequote-hook}
+ */
 export function useQuote({
   walletClient,
   fromTokenAddress,
@@ -471,6 +641,8 @@ export function useQuote({
           originPublicClient: originPublicClient ?? undefined,
           destinationPublicClient: destinationPublicClient ?? undefined,
           isSmartWallet: isSmartWallet ?? undefined,
+          trailsApiKey,
+          trailsApiUrl,
         }
 
         logger.console.log("[trails-sdk] options", options)
@@ -488,6 +660,9 @@ export function useQuote({
           destinationChain: prepareSendQuote.destinationChain,
           fees: prepareSendQuote.fees,
           priceImpact: prepareSendQuote.priceImpact,
+          priceImpactUsd: prepareSendQuote.priceImpactUsd ?? undefined,
+          priceImpactUsdDisplay:
+            prepareSendQuote.priceImpactUsdDisplay ?? undefined,
           completionEstimateSeconds: prepareSendQuote.completionEstimateSeconds,
           slippageTolerance: prepareSendQuote.slippageTolerance,
           transactionStates: prepareSendQuote.transactionStates,
@@ -502,6 +677,14 @@ export function useQuote({
           gasCostUsdDisplay: prepareSendQuote.gasCostUsdDisplay ?? undefined,
           gasCost: prepareSendQuote.gasCost ?? undefined,
           gasCostFormatted: prepareSendQuote.gasCostFormatted ?? undefined,
+          totalFeesUsd: prepareSendQuote.grandTotalUsd ?? undefined,
+          totalFeesUsdDisplay:
+            prepareSendQuote.grandTotalUsdDisplay ?? undefined,
+          totalGasUsd: prepareSendQuote.totalGasUsd ?? undefined,
+          totalGasUsdDisplay: prepareSendQuote.totalGasUsdDisplay ?? undefined,
+          allProviderFeesUsd: prepareSendQuote.allProviderFeesUsd ?? undefined,
+          allProviderFeesUsdDisplay:
+            prepareSendQuote.allProviderFeesUsdDisplay ?? undefined,
         }
 
         const swap = async (): Promise<SwapReturn> => {

package/src/widget/hooks/useRecentTokens.ts

@@ -1,17 +1,17 @@
-import { JsonEncode } from "@0xsequence/trails-api"
+import { JsonEncode } from "@0xtrails/api"
 import { useState, useEffect, useCallback } from "react"
-import type { SupportedToken } from "../../tokens.js"
+import type { Token } from "../../tokens.js"
 import { logger } from "../../logger.js"
 
 interface RecentTokensStorage {
-  [accountAddress: string]: SupportedToken[]
+  [accountAddress: string]: Token[]
 }
 
 const RECENT_TOKENS_KEY = "trails_recent_tokens"
 const MAX_RECENT_TOKENS = 10
 
 export function useRecentTokens(accountAddress?: string) {
-  const [recentTokens, setRecentTokens] = useState<SupportedToken[]>([])
+  const [recentTokens, setRecentTokens] = useState<Token[]>([])
 
   // Load recent tokens from localStorage for the current account
   useEffect(() => {
@@ -38,7 +38,7 @@ export function useRecentTokens(accountAddress?: string) {
 
   // Add or update a recent token
   const addRecentToken = useCallback(
-    (token: SupportedToken) => {
+    (token: Token) => {
       if (!accountAddress) return
 
       try {
@@ -55,7 +55,7 @@ export function useRecentTokens(accountAddress?: string) {
           (t) =>
             !(
               t.contractAddress === token.contractAddress &&
-              t.chainId === token.chainId
+              (t.chainId || 0) === (token.chainId || 0)
             ),
         )
 

package/src/widget/hooks/useRecipients.ts

@@ -12,7 +12,7 @@ export interface RecentRecipient {
 const STORAGE_KEY = "trails-recent-recipients"
 const MAX_RECENT_RECIPIENTS = 10
 
-export const useRecipients = () => {
+export function useRecipients() {
   const [recentRecipients, setRecentRecipients] = useState<RecentRecipient[]>(
     [],
   )

package/src/widget/hooks/useSelectedFeeOption.tsx

@@ -7,7 +7,7 @@ import React, {
   useMemo,
   type ReactNode,
 } from "react"
-import type { FeeOption } from "@0xsequence/trails-api"
+import type { FeeOption } from "@0xtrails/api"
 import { formatRawAmount, formatUsdAmountDisplay } from "../../tokenBalances.js"
 import { logger } from "../../index.js"
 import { isNativeToken, normalizeAddress } from "../../utils.js"
@@ -301,7 +301,7 @@ export const SelectedFeeOptionProvider: React.FC<
   )
 }
 
-export const useSelectedFeeOption = (): SelectedFeeOptionContextType => {
+export function useSelectedFeeOption(): SelectedFeeOptionContextType {
   const context = useContext(SelectedFeeOptionContext)
 
   if (context === undefined) {

package/src/widget/hooks/useSelectedFundMethod.tsx

@@ -30,7 +30,7 @@ export const SelectedFundMethodProvider = ({
   )
 }
 
-export const useSelectedFundMethod = (): SelectedFundMethodContextType => {
+export function useSelectedFundMethod(): SelectedFundMethodContextType {
   const context = useContext(SelectedFundMethodContext)
   if (context === undefined) {
     throw new Error(

package/src/widget/hooks/useSelectedRecipient.tsx

@@ -47,7 +47,7 @@ export const SelectedRecipientProvider: React.FC<
   )
 }
 
-export const useSelectedRecipient = () => {
+export function useSelectedRecipient() {
   const context = useContext(SelectedRecipientContext)
   if (context === undefined) {
     throw new Error(