Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

SDK Overview

The Mirage SDK turns a private transfer into a sequence your application can display and control. Your app supplies a wallet, a public client, a token, an amount, and a recipient. The SDK handles the protocol-specific work between that input and a completed transfer.

The integration in one view

A typical integration has four parts:

  1. Connect: your app creates viem wallet and public clients.
  2. Prepare: prepareTransfer validates the request and gets a signed quote.
  3. Execute: execute guides the wallet through approval and escrow deployment, then submits the private transfer request.
  4. Observe: your app reads the emitted events to update its interface and records the final transaction hash.
Your form
   ↓
prepareTransfer(...)  →  quote and funding requirements
   ↓
prepared.execute()    →  approval → escrow → private signal → delivery
   ↓
Your interface        →  progress, receipt, or recovery

The sender signs normal wallet transactions. The recipient receives a normal stablecoin transfer. Mirage coordinates the private relationship between those two sides.

What belongs to your app

Your application remains responsible for:

  • Connecting the user's wallet
  • Collecting and validating the recipient and amount
  • Displaying token amounts in human-readable units
  • Showing progress from SDK events
  • Securely saving transfer secrets after escrow deployment
  • Deciding how users resume or cancel an interrupted transfer

The SDK does not provide UI components, React state, wallet connection, or persistent storage.

What the SDK handles

The SDK handles:

  • Quote requests and exact funding requirements
  • ERC-20 approvals
  • Escrow deployment
  • Compliance authorization
  • Encrypted signal submission to Nomad
  • Transfer monitoring and completion events
  • Resume and cancellation primitives

A useful mental model

prepareTransfer creates a prepared operation. It does not move funds. You can safely show its quote and ask the user to confirm.

execute begins the state-changing flow. Once its deploy event is emitted, funds are in the escrow and the accompanying secrets must be saved. Those secrets are the recovery path if the browser closes or the network fails.

Most integrations should begin with the single execute flow. Use staged execution only when your interface genuinely needs separate approval and deployment actions.

Recommended path

  1. Install and configure the SDK.
  2. Send one transaction in a test environment.
  3. Read Advanced Transfers when you need batches, staged execution, cancellation, or resuming.
  4. Add production handling for quotes and fees, tokens and networks, and errors.

If you want to understand what happens beneath the SDK, continue to the Protocol Architecture.