Embedded Wallet: USDC Bridging

Overview

The 1Shot embedded wallet ships a built-in Circle CCTP V2 bridge for native USDC. Source burns use TokenMessengerV2.depositForBurnWithHook and are submitted gaslessly through the 1Shot Public Relayer — the same USDC fee path as Send. Destination mints are handled by Circle's Forwarding Service, so users never sign on the destination chain and never need native gas there.

This is native CCTP integration — not Circle BridgeKit. Mainnet and testnet destinations must match the source network type (mainnet → mainnet, testnet → testnet).

In-wallet experience

When a user views native USDC on a relayer CCTP source chain, Asset Details shows a Bridge action alongside Send and Buy. The bridge modal walks through quote, confirm, burn, and destination mint.

• Resume in-flight transfers — if the user closes the modal after the burn is submitted, reopening Bridge resumes polling until the destination mint completes or times out.
• Insufficient balance — the quote includes CCTP protocol fee, forwarding fee, and relayer fee; the wallet rejects amounts that cannot cover all three.

1. Enter amount, pick destination network, and choose Fast or Standard transfer speed.
2. Tap Get quote — the wallet fetches CCTP protocol fees, Circle forwarding fees, and the relayer USDC fee.
3. Review total burned vs net received, then Confirm bridge — one passkey ceremony for approve + burn when needed.
4. The wallet submits the burn via the relayer, polls Circle Iris for the destination mint, and shows source and destination explorer links on success.

Trigger from your Host app

Call the custom Branding RPC bridge after OWSProxy.create(). The wallet must be unlocked (user has completed passkey unlock). The RPC shows the wallet shell, opens the CCTP bridge modal, and hides the shell when the flow completes or is cancelled.

Omit optional params to let the user choose amount, destination, or source chain in the UI — useful for a generic "Bridge USDC" button in your app.

import { OWSProxy } from "@1shotapi/ows-provider";

const proxy = await OWSProxy.create(container, "https://wallet.1shotapi.com/");

// Minimal — user picks everything in the wallet UI
await proxy.rpc("bridge", {});

// Pre-fill source, destination, and amount
const result = await proxy.rpc("bridge", {
  amount: "10.50",           // human USDC on source chain
  sourceChainId: 8453,       // decimal; omit → session chain
  destinationChainId: 42161, // decimal; omit → user picks in UI
});

// { ok: true, burnTxHash, forwardTxHash? }

Parameters and errors

• amount (optional string) — human-readable USDC on the source chain (e.g. "10.50"). Omit to let the user enter the amount. Must parse to a value greater than zero.
• sourceChainId (optional number) — decimal EVM chain ID for the burn. Omit to use the wallet's current session chain. Source must be a relayer chain with native CCTP USDC.
• destinationChainId (optional number) — decimal EVM chain ID for the mint. Omit to let the user pick in the modal. Must be a valid CCTP destination for the source on the same network type (mainnet/testnet).
• Locked wallet — "Wallet is locked — unlock before bridge" if no EVM address is available.
• OwsInvalidParamsError — no CCTP USDC on source, source is not a relayer chain, invalid destination, or malformed amount.
• OwsUserRejectedError — user cancelled or closed the bridge before confirming.

Fees and balances

Everything is paid from the user's source-chain USDC balance. The quote breaks out transfer amount, CCTP protocol fee, Circle forwarding fee, and relayer fee. The total burned on source must fit within the user's balance.

• Relayer fee — same USDC fee path as in-wallet Send; submitted through EIP-7710 delegated execution.
• Single ceremony — when an ERC-20 approve is required, approve and burn are bundled into one passkey signing flow.
• No destination gas — Circle's Forwarding Service mints USDC on the destination; the user does not need ETH (or other native gas) on the destination chain.

Built-in capabilities

USDC bridging is a first-class wallet feature — no separate SDK, BridgeKit install, or destination-chain wallet setup. Users bridge from the same passkey account they use for Send and gas abstraction.

• Native USDC only — burns and mints real Circle USDC via CCTP V2; no wrapped or pooled liquidity.
• Two entry points — Asset Details Bridge button for in-wallet users, and host bridge RPC to open the same flow from your app.
• Fast and Standard speeds — users choose finality vs cost; quotes show CCTP protocol fee, Circle forwarding fee, and relayer fee before confirm.
• Gasless on source, signature-free on destination — source burn goes through the Public Relayer (USDC fee); Circle Forwarding Service handles the destination mint.
• Resume support — in-flight burns persist locally so users can close the modal and pick up Iris polling later.
• Same-network routing — mainnet sources bridge to mainnet destinations; testnet to testnet. Destination lists are scoped to valid CCTP routes for the selected source chain.

Customization

Override bridge copy via configure before showing wallet UI. copy.bridgeLabel controls the Asset Details button; copy.cctpBridge patches modal strings (title, fee labels, confirm/cancel, success copy, and error messages).

await proxy.rpc("configure", {
  copy: {
    bridgeLabel: "Move USDC",
    cctpBridge: {
      title: "Cross-chain USDC",
      confirmLabel: "Confirm transfer",
    },
  },
});

Webhooks and analytics

• Webhooks — the source burn is a relayer transaction. If you set destinationUrl via configure, your backend receives signed status webhooks for the burn the same way as Send. See Embedded Wallet: Webhooks.
• Analytics — bridge burns surface on proxy.analytics as TransactionSubmitted, TransactionSubmitFailed, and TransactionSubmitCancelled with chainId, to, and txHash. See Embedded Wallet: Analytics.

Test in the playground

Open the wallet playground and use the Bridge panel (or Onramp / Bridge when Arc mainnet onramp is enabled). Connect the wallet, pick source and destination chains, optionally pre-fill amount, then click Bridge to exercise the same proxy.rpc("bridge", …) path your Host app uses.