Why StableitReach out

Methods

Find Routes

findRoutes(intent)

Returns available routes to fulfill the intent.

Parameters

1

intent

Defines the transfer details: origin, destination, amount, sender/recipient addresses, and optional gas drop-off.

const routes = await stable.findRoutes({
  sourceChain: string,
  targetChain: string,
  sender: string | EvmAddress,
  amount: string | bigint | Amount,
  recipient: string, // 0x-prefixed address
  gasDropoffDesired?: bigint,  // Optional. Native gas token amount to include on the destination chain
  paymentToken?: "usdc" | "native",
  usePermit?: true, // Optional. Defaults to true
});

// You can also use utility classes like Amount and EvmAddress
const routes = await stable.findRoutes({
  sender: new EvmAddress("0x..."), // or just a string
  amount: usdc(0.5),               // or string "0.5" or bigint in atomic units
  ...
});

// Access different route options
console.log("Fastest route:", routes.fastest);
console.log("Cheapest route:", routes.cheapest);
console.log("All routes:", routes.all);

Returns

A routes object containing:

  • all: list of route objects

  • fastest: reference to the fastest route

  • cheapest: reference to the cheapest route

Each route includes:

  • intent: original intent used to compute the route

  • estimatedDuration: number (in seconds)

  • estimatedTotalCost: cost in USD

  • fees: detailed fee breakdown

  • corridor: route type (e.g., "v1", "v2Direct", "avaxHop")

  • steps: transaction actions (e.g., sign-and-send-transaction, sign-message, sign-permit)

  • requiresMessageSignature: whether the route uses permit (vs approval)

  • transactionListener: emits blockchain tx-level events

  • progress: emits high-level transfer lifecycle events

  • workflow: async generator for manual execution flows

Example return

Authorization Methods

Each route either uses:

  • Approval: Requires an on-chain approval transaction. Suitable for users who trust the CCTPR contract and interact frequently — often done outside the SDK for better gas optimization.

  • Permit: Requires a signed message. Preferable for users who interact less frequently or want to minimize trust assumptions. Slightly more secure for one-off interactions.

You can detect this via:

route.requiresMessageSignature // true = uses permit

Gasless Transfers

Allow users to pay transaction fees using USDC instead of native tokens like ETH or MATIC. No need to hold gas tokens to complete transfers.

Check if sender has enough funds

checkHasEnoughFunds(route)

Checks whether the sender has enough USDC/native tokens to cover all required fees for the given route.

Parameters

1

route

One of the objects returned from findRoutes.

Returns

Boolean: true if sufficient funds, otherwise false.

Example return

Execute route

executeRoute(route)

Executes the given route. Automatically handles pre-approvals or permits.

Parameters

1

route

One of the objects returned from findRoutes.

Returns

An object describing the full lifecycle of the transfer:

  • transferHash: hash of the transaction that originated the transfer on the source chain

  • redeemHash: hash of the transaction that redeemed the transfer on the target chain

  • transactions: array of transaction hashes signed and paid by the user (e.g. approval, transfer)

  • attestations: Circle attestations of the transfer (can include two if using Avax Hop)

  • redeems: redemption transaction data (can include two if using Avax Hop)

Example return

executeRoute() resolves after the transfer is redeemed on the destination chain. To monitor transfer progress, use route.progress. To observe signed blockchain transactions, use route.transactionListener.

Transaction tracking

route.progress

route.progress emits events representing each step in the lifecycle of the transfer.

Lifecycle Events

1

message-signed

The user signed a message to authorize part of the transfer (e.g., permit or other message types).

Example
2

approval-sent

The user signed and sent an approval transaction.

Example
3

transfer-initiated

The transfer process has started. This event signals that the SDK is ready to submit the transfer transaction. Useful for UI state changes (e.g., loading spinners).

4

transfer-sent

The user signed and sent the transfer transaction.

Example
5

transfer-confirmed

Circle attestation service confirmed the transfer (v1 or v2 format).

Example

transfer-confirmed may differ between CCTPv1 and CCTPv2.

6

hop-redeemed (If using Avax Hop)

The first transfer was redeemed on avalanche.

7

hop-confirmed (If using Avax Hop)

The second transfer was confirmed by circle

8

transfer-redeemed

The transfer was redeemed on the destination chain.

Example
9

step-completed

Special event that fires on every step. The payload includes name and data.

Example

route.transactionListener

These events monitor wallet transactions, specifically those the user signs and pays for.

Lifecycle Events

1

transaction-sent

The transaction was sent to the blockchain.

Example
2

transaction-included

The transaction was included in a block.

Example

Error Handling

Handle transfer errors using the progress event system:

Advanced: Custom Step Execution

Each route exposes an async generator via route.workflow. This allows advanced developers to handle signing and transaction submission step-by-step.

Useful for advanced integrations that require granular control over the execution flow, including special handling of permit transactions.

PreviousConfigureNextKey Concepts

Last updated

Was this helpful?