Magic

Integrate Magic signers with Rhinestone smart accounts.

Overview

Magic provides wallet infrastructure with two integration paths:

• Embedded Wallets: Client-side Magic SDK handles authentication and signing. Keys are managed by Magic and signing happens through their RPC provider.
• Server Wallets: Backend-managed wallets via Magic Express API. Keys live in Magic’s TEE (Trusted Execution Environment) and signing happens through server-side API calls.

Both paths produce a viem-compatible account that becomes the owner of a Rhinestone smart account, enabling cross-chain functionality.

Integration

Embedded Wallet

Prerequisites

• A Magic account and publishable API key
• Rhinestone API key
• React application setup

1. Install Dependencies

   npm

   npm install magic-sdk @rhinestone/sdk viem
   
2. Set Up Magic SDK

   Initialize the Magic SDK in your application:

   import { Magic } from 'magic-sdk'
   
   const magic = new Magic(process.env.NEXT_PUBLIC_MAGIC_API_KEY)
   
3. Authenticate and Get Wallet Address

   Use Magic’s client-side SDK for authentication:

   // Login with Magic email OTP
   await magic.auth.loginWithEmailOTP({ email: "[e-mail]" })
   
   // Get the wallet address
   const accounts = (await magic.rpcProvider.request({
     method: "eth_accounts",
   })) as string[]
   
   const address = accounts[0]
   

   Magic also supports SMS, social login, WebAuthn, and more. See Magic’s authentication overview for all options.

4. Create Rhinestone Account

   Create a viem account from Magic’s provider and pass it to Rhinestone:

   import { RhinestoneSDK, walletClientToAccount } from "@rhinestone/sdk"
   import { createWalletClient, custom } from "viem"
   import { toAccount } from "viem/accounts"
   import type { SignableMessage, TypedDataDefinition } from "viem"
   
   // Magic RPC requires BigInts as decimal strings
   function serializeBigInts(obj: unknown): unknown {
     if (obj === null || obj === undefined) return obj
     if (typeof obj === "bigint") return obj.toString(10)
     if (Array.isArray(obj)) return obj.map(serializeBigInts)
     if (typeof obj === "object") {
       const result: Record<string, unknown> = {}
       for (const key in obj) {
         result[key] = serializeBigInts((obj as Record<string, unknown>)[key])
       }
       return result
     }
     return obj
   }
   
   // 1. Create a viem wallet client using Magic's provider
   const walletClient = createWalletClient({
     account: address as `0x${string}`,
     transport: custom(magic.rpcProvider as any),
   })
   
   const wrappedWalletClient = walletClientToAccount(walletClient)
   
   // 2. Wrap with toAccount to handle BigInt serialization
   //    for signTypedData (required by Magic's RPC)
   const account = toAccount({
     address: wrappedWalletClient.address,
     async signMessage({ message }: { message: SignableMessage }) {
       return wrappedWalletClient.signMessage({ message })
     },
     async signTransaction(transaction: any) {
       return wrappedWalletClient.signTransaction(transaction)
     },
     async signTypedData(typedData: TypedDataDefinition) {
       const serialized = serializeBigInts(typedData)
       return wrappedWalletClient.signTypedData(serialized as any)
     },
   })
   
   // 3. Create the Rhinestone account
   const rhinestone = new RhinestoneSDK({
     apiKey: process.env.NEXT_PUBLIC_RHINESTONE_API_KEY,
   })
   const rhinestoneAccount = await rhinestone.createAccount({
     owners: {
       type: "ecdsa",
       accounts: [account],
     },
   })
   

Server Wallet

Prerequisites

• A Magic account, publishable API key, and secret key
• Rhinestone API key
• A backend server (Node.js, Bun, etc.)
• An OIDC provider registered with Magic Express (see below)

1. Install Dependencies

   npm

   npm install @rhinestone/sdk viem
   

   Server wallets don’t need the magic-sdk client package. You interact with the Magic Express API directly from your backend.
2. Register OIDC Provider

   Server wallets use the Magic Express API, which requires OIDC-based authentication. Your backend acts as an OIDC provider: it signs JWTs that Magic Express verifies using your public keys.

   Generate an RS256 key pair and register it with Magic (one-time setup):

   // register-oidc-provider.ts
   const res = await fetch(
     "https://tee.express.magiclabs.com/v1/identity/provider",
     {
       method: "POST",
       headers: {
         "X-Magic-Secret-Key": process.env.MAGIC_SECRET_KEY,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         issuer: "https://your-app.com", // Your backend URL
         audience: "magic-express",
         jwks_uri: "https://your-app.com/.well-known/jwks.json",
       }),
     }
   )
   
   const { id } = await res.json()
   // Save this as MAGIC_OIDC_PROVIDER_ID
   

   Your backend must expose a /.well-known/jwks.json endpoint serving the public key in JWKS format. Magic Express uses this to verify JWTs from your server.
3. Set Up Backend API

   Create helper functions to interact with the Magic Express API:

   const MAGIC_EXPRESS_API = "https://tee.express.magiclabs.com"
   
   function magicHeaders(jwt: string) {
     return {
       Authorization: `Bearer ${jwt}`,
       "X-Magic-API-Key": process.env.MAGIC_API_KEY!,
       "X-OIDC-Provider-ID": process.env.MAGIC_OIDC_PROVIDER_ID!,
       "X-Magic-Chain": "ETH",
       "Content-Type": "application/json",
     }
   }
   
   export async function getOrCreateWallet(jwt: string) {
     const res = await fetch(`${MAGIC_EXPRESS_API}/v1/wallet`, {
       method: "POST",
       headers: magicHeaders(jwt),
     })
     return res.json() as Promise<{ public_address: string }>
   }
   
   export async function signHash(jwt: string, hash: string) {
     const res = await fetch(`${MAGIC_EXPRESS_API}/v1/wallet/sign/data`, {
       method: "POST",
       headers: magicHeaders(jwt),
       body: JSON.stringify({ raw_data_hash: hash }),
     })
     return res.json() as Promise<{ signature: string }>
   }
   

   Expose wallet and signing endpoints for your frontend. These routes authenticate the user session, issue a JWT for Magic Express, and proxy the request:

   // GET /api/wallet
   app.get("/api/wallet", async (c) => {
     const user = getAuthenticatedUser(c) // Your auth middleware
     if (!user) return c.json({ error: "Unauthorized" }, 401)
   
     const jwt = await issueJwt(user.id) // Sign JWT with your RS256 private key
     const data = await getOrCreateWallet(jwt)
     return c.json(data)
   })
   
   // POST /api/sign
   app.post("/api/sign", async (c) => {
     const user = getAuthenticatedUser(c)
     if (!user) return c.json({ error: "Unauthorized" }, 401)
   
     const { hash } = await c.req.json()
     const jwt = await issueJwt(user.id)
     const data = await signHash(jwt, hash)
     return c.json(data)
   })
   
4. Create Rhinestone Account

   On the frontend, create a viem account that delegates signing to your backend, then pass it to Rhinestone:

   import { RhinestoneSDK } from "@rhinestone/sdk"
   import { toAccount } from "viem/accounts"
   import { hashTypedData, hashMessage } from "viem"
   import type { SignableMessage, TypedDataDefinition, Hex } from "viem"
   
   // 1. Get wallet address from your backend
   const walletRes = await fetch("/api/wallet", {
     credentials: "include",
   })
   const { public_address } = await walletRes.json()
   
   // 2. Create a viem account that signs via your backend
   const account = toAccount({
     address: public_address as Hex,
     async signMessage({ message }: { message: SignableMessage }) {
       const hash = hashMessage(message)
       const res = await fetch("/api/sign", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         credentials: "include",
         body: JSON.stringify({ hash }),
       })
       if (!res.ok) throw new Error((await res.json()).error)
       return (await res.json()).signature as Hex
     },
     async signTransaction() {
       throw new Error("signTransaction not supported")
     },
     async signTypedData(typedData: TypedDataDefinition) {
       const hash = hashTypedData(typedData)
       const res = await fetch("/api/sign", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         credentials: "include",
         body: JSON.stringify({ hash }),
       })
       if (!res.ok) throw new Error((await res.json()).error)
       return (await res.json()).signature as Hex
     },
   })
   
   // 3. Create the Rhinestone account
   const rhinestone = new RhinestoneSDK({
     apiKey: process.env.NEXT_PUBLIC_RHINESTONE_API_KEY!,
   })
   const rhinestoneAccount = await rhinestone.createAccount({
     owners: { type: "ecdsa", accounts: [account] },
   })
   

   The key pattern: toAccount creates a viem account where signMessage and signTypedData hash data locally, then send the hash to your backend. Your backend forwards it to Magic Express for signing. The private key never leaves Magic’s TEE.

Cross-Chain Transactions

Once initialized, both wallet types use the same Rhinestone API:

async function handleCrossChainTransfer() {
  const transaction = await rhinestoneAccount.sendTransaction({
    sourceChains: [baseSepolia],
    targetChain: arbitrumSepolia,
    calls: [
      {
        to: "USDC",
        data: encodeFunctionData({
          abi: erc20Abi,
          functionName: "transfer",
          args: ["0xrecipient", parseUnits("10", 6)],
        }),
      },
    ],
    tokenRequests: [
      {
        address: "USDC",
        amount: parseUnits("10", 6),
      },
    ],
  })
}

Next Steps

• See it in action: Check out our complete Magic example for a full working app
• Learn more about Magic’s wallet types
• Explore chain abstraction capabilities
• Check out creating an account for more details