> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhinestone.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration guide

> Migrate a Rhinestone SDK 1.x integration to the public 2.x API.

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

```bash theme={null}
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.

```ts theme={null}
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](/wallets/custom-signer/integration/security).

<Warning>
  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.
</Warning>

## Replace transaction shortcuts

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

```ts theme={null}
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:

```ts theme={null}
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](/wallets/session-keys/custom-setup/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](/wallets/custom-signer/configuration/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:

```ts theme={null}
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.