Migration guide

This guide targets @rhinestone/sdk 2.16.1. Upgrade and run your type checker before changing behavior:

npm install @rhinestone/sdk@2.16.1 viem@^2.55.0

The 2.x package is ESM-only. Use import syntax and only published entry points such as @rhinestone/sdk, @rhinestone/sdk/utils, @rhinestone/sdk/actions/*, and @rhinestone/sdk/smart-sessions.

Initialize the SDK and account

createRhinestoneAccount is removed. Create one SDK instance for shared authentication, RPC, bundler, and paymaster configuration, then create accounts from it.

import { RhinestoneSDK } from '@rhinestone/sdk'

const rhinestone = new RhinestoneSDK({
  auth: {
    mode: 'apiKey',
    apiKey: process.env.RHINESTONE_API_KEY!,
  },
})

const account = await rhinestone.createAccount({
  owners: {
    type: 'ecdsa',
    accounts: [owner],
  },
})

Keep API-key mode server-side. If the SDK runs in a browser, migrate to short-lived JWTs as described in security.

The default account is Nexus 1.2.1. If a 1.x integration derived an unfunded Nexus 1.2.0 address that you must preserve, set account: { type: 'nexus', version: '1.2.0' }. Verify the expected address before funding or deploying.

Replace transaction shortcuts

account.sendTransaction is removed for intents. Use the explicit lifecycle:

const prepared = await account.prepareTransaction(transaction)
const signed = await account.signTransaction(prepared)
const result = await account.submitTransaction(signed)
const status = await account.waitForExecution(result)

Update the surrounding transaction code as follows:

Pass token addresses, not symbols such as USDC or WETH.
Read the recommended route from prepared.quotes.best; all routes are in prepared.quotes.all.
To select another route, call signTransaction(prepared, { intentId }) with an ID from quotes.all.
Change settlementLayers arrays to { include: [...] } or { exclude: [...] }.
Pass EIP-7702 authorizations as submitTransaction(signed, { authorizations }).
Remove the second acceptsPreconfirmations argument from waitForExecution.
Store intent IDs as strings before passing them to rhinestone.getIntentStatus(intentId).

A valid 2.x token request uses the token address for the target chain:

import type { Transaction } from '@rhinestone/sdk'
import { base } from 'viem/chains'

const baseUsdc = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
const amount = 10_000_000n

const transaction = {
  targetChain: base,
  tokenRequests: [{ address: baseUsdc, amount }],
  settlementLayers: { include: ['ACROSS'] },
} satisfies Transaction

Migrate session keys

The 1.x experimental session names became stable in 2.x. Replace experimental_sessions and type: 'experimental_session' with sessions and type: 'session', then remove the experimental_ prefix from session account methods. Do not copy a 1.x resolved Session.actions object into 2.x. Recreate the permission with the current ABI-driven configuration and verify its permission ID before enabling it. Continue with create a session for the current session workflow.

Update account and provider configuration

Alchemy’s { type: 'alchemy', apiKey } provider configuration is removed. Supply complete per-chain URLs with { type: 'custom', urls }; see JSON-RPC providers.
passport accounts are removed.
Nexus supports 1.2.0 and 1.2.1; Kernel supports 3.3. Remove older pinned versions.
submitTransaction options are now an object, including EIP-7702 authorizations.
PortfolioToken.decimals and aggregate balances moved to per-chain entries as chains[].decimals and chains[].amount.

Update imports and removed helpers

Use these published 2.x locations:

import {
  experimental_getRhinestoneInitData,
  experimental_getV0InitData,
  walletClientToAccount,
  wrapParaAccount,
} from '@rhinestone/sdk/utils'
import { toSession } from '@rhinestone/sdk/smart-sessions'

The bundled token registry and its helpers are removed. Obtain supported chain and token metadata from Rhinestone’s chain catalog through the SDK-backed flows, and keep token addresses chain-specific. The Compact action package, Permit2 batch-signing helpers, deployAccountsForOwners, and checkERC20AllowanceDirect are also removed. Replace allowance reads with viem readContract; use the current account deployment methods and orchestrator-provided signing data for the other flows. After migration, verify derived account addresses, session permission IDs, token decimals per chain, and both intent and UserOperation paths in a test environment.

Account setup

Recovery

Signing

Configuration

Integration

SDK reference

Initialize the SDK and account

Replace transaction shortcuts

Migrate session keys

Update account and provider configuration

Update imports and removed helpers

​Initialize the SDK and account

​Replace transaction shortcuts

​Migrate session keys

​Update account and provider configuration

​Update imports and removed helpers

Initialize the SDK and account

Replace transaction shortcuts

Migrate session keys

Update account and provider configuration

Update imports and removed helpers