Account registration

Every depositing user needs a registered smart account. You can let the service create one (managed) or bring your own (user-owned).

Choose an account type

	Managed account	User-owned account
Who creates the account	Deposit service	You, via SDK
Session key setup	Automatic	You sign session authorization
User-facing address	Service returns deposit address	Your existing smart account address
Recipient	Required (you specify where funds go)	Optional (defaults to the account itself)
Best for	Existing apps, EOA users (e.g. browser wallets)	Non-custodial flows, users with existing smart accounts

Managed accounts are recommended for most integrations — simpler setup, no SDK dependency for registration. User-owned accounts are for cases where deposits should go to an existing smart account the user already controls.

All examples below use these shared constants:

const DEPOSIT_SERVICE_URL =
  "https://v1.orchestrator.rhinestone.dev/deposit-processor";
const API_KEY = "YOUR_RHINESTONE_API_KEY";

const headers = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY,
};

Register an account

Managed account
User-owned account

The service creates a Nexus smart account deterministically from your API key and a salt you provide. The same API key + salt always produces the same deposit address, so you can safely re-register if needed.

Pick a salt

Use a stable, unique identifier per user — for example, an internal user ID. Hash it for privacy:

import { keccak256, toHex } from "viem";

const salt = keccak256(toHex("user-123"));

Call /register-managed

const response = await fetch(`${DEPOSIT_SERVICE_URL}/register-managed`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    account: {
      salt,
      target: {
        chain: "eip155:42161", // Arbitrum
        token: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
        recipient: "0xYOUR_RECIPIENT_ADDRESS",
      },
    },
  }),
});

const { evmDepositAddress, solanaDepositAddress } = await response.json();

The response includes two deposit addresses:

Field	Description
`evmDepositAddress`	Accepts deposits on any supported EVM chain
`solanaDepositAddress`	Accepts deposits on Solana

Both addresses route to the same target chain and token.

Verify registration

const check = await fetch(`${DEPOSIT_SERVICE_URL}/check/${evmDepositAddress}`);
const data = await check.json();

{
  "isRegistered": true,
  "targetChain": "eip155:42161",
  "targetToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "sources": [
    { "chain": "eip155:8453", "depositAddress": "<evmDepositAddress>" },
    { "chain": "eip155:42161", "depositAddress": "<evmDepositAddress>" },
    {
      "chain": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "depositAddress": "<solanaDepositAddress>"
    }
  ]
}

sources lists every chain the account can receive deposits from, each with its deposit address — EVM chains share the evmDepositAddress, Solana carries the solanaDepositAddress.

For this flow, you create a Rhinestone smart account via the SDK, configure session keys so the deposit service can sign bridging transactions, and register the account with its factory data and session details.

Install the SDK

These examples target SDK 3.0.0, which is not released yet. The install command below requires its publication; the current v2 package does not support these APIs.

npm install @rhinestone/sdk@3.0.0 viem

Create the account

Run these examples in a trusted backend with userSigner, a viem account controlled by the user. Never expose API_KEY in browser code. The following blocks continue this setup.

import { RhinestoneSDK, type RhinestoneAccountConfig } from "@rhinestone/sdk";

const rhinestone = new RhinestoneSDK({
  auth: { mode: "apiKey", apiKey: API_KEY },
});

const config = {
  evm: {
    account: { type: "nexus", version: "1.2.1" },
    owners: {
      type: "ecdsa",
      accounts: [userSigner],
    },
    sessions: { enabled: true },
  },
} satisfies RhinestoneAccountConfig;

const account = await rhinestone.createAccount(config);
const address = account.getAddress("evm");
const { factory, factoryData } = account.getInitData();

Build session details

The deposit service uses a session key to sign bridging transactions on the user’s behalf. Build session details for every chain you accept deposits from, plus the target chain — a deposit arriving on a chain with no session can’t be bridged. See supported chains and tokens for the current set.

import { toViewOnlyAccount } from "@rhinestone/sdk/evm";
import type { Chain } from "viem";
import { base, optimism, arbitrum } from "viem/chains";

const RHINESTONE_SIGNER_ADDRESS = "0x177bfcdd15bc01e99013dcc5d2b09cd87a18ce9c";
const sessionSigner = toViewOnlyAccount(RHINESTONE_SIGNER_ADDRESS);

const LEGACY_SUDO_POLICY_ADDRESS =
  "0x0000003111cD8e92337C100F22B7A9dbf8DEE301";
const LEGACY_SUDO_POLICY_CHAIN_IDS = new Set([
  1, 10, 56, 100, 130, 137, 143, 146, 196, 999, 1868, 4663, 8453,
  9745, 42161, 43114, 57073, 747474, 84532, 421614, 11155111, 11155420,
]);

async function createDepositSession(chain: Chain) {
  return rhinestone.createSession({
    owners: { type: "ecdsa", accounts: [sessionSigner] },
    chain,
    ...(LEGACY_SUDO_POLICY_CHAIN_IDS.has(chain.id)
      ? { policyAddresses: { sudo: LEGACY_SUDO_POLICY_ADDRESS } }
      : {}),
  });
}

const sourceChains = [base, optimism, arbitrum];
const sessions = await Promise.all(sourceChains.map(createDepositSession));

const sessionDetails = await account.getSessionDetails(sessions);
const signature = await account.signEnableSession(sessionDetails);

const enableSessionDetails = {
  hashesAndChainIds: sessionDetails.hashesAndChainIds,
  signature,
};

This unscoped setup grants the service signer unrestricted execution and ERC-1271 signing on each listed chain, with no separate claim policies. It is not limited to bridging. The policy override matches the service’s per-chain session reconstruction; changing it invalidates the enable signature. Confirm chain support and the production signer address before signing.

The example pins Nexus 1.2.1. The service also recognizes Nexus 1.2.0, Startale 1.0.0, Safe, and Kernel factories; do not assume other factories or validator configurations are compatible. Restricted swap sessions require the service’s matching stored scope and are not covered by this example.

Call /register

const response = await fetch(`${DEPOSIT_SERVICE_URL}/register`, {
  method: "POST",
  headers,
  body: JSON.stringify(
    {
      account: {
        address,
        accountParams: {
          factory,
          factoryData,
          sessionDetails: enableSessionDetails,
        },
        target: {
          chain: "eip155:42161", // Arbitrum
          token: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
        },
      },
    },
    (_, v) => (typeof v === "bigint" ? v.toString() : v),
  ),
});

const { evmDepositAddress, solanaDepositAddress } = await response.json();

The JSON replacer (_, v) => typeof v === "bigint" ? v.toString() : v is needed because sessionDetails.hashesAndChainIds contains bigint chain IDs that JSON.stringify can’t serialize by default.

Verify registration

const check = await fetch(`${DEPOSIT_SERVICE_URL}/check/${address}`);
const data = await check.json();
// { isRegistered: true, targetChain: "eip155:42161", sources: [...] }

Adding source chains

To accept deposits from chains that weren’t included in the original registration, add new session details:

import { polygon } from "viem/chains";

const newSessions = [await createDepositSession(polygon)];
const newSessionDetails =
  await account.getSessionDetails(newSessions);
const newSignature =
  await account.signEnableSession(newSessionDetails);

await fetch(`${DEPOSIT_SERVICE_URL}/account/${address}/session`, {
  method: "POST",
  headers,
  body: JSON.stringify(
    {
      sessionDetails: {
        hashesAndChainIds: newSessionDetails.hashesAndChainIds,
        signature: newSignature,
      },
    },
    (_, v) => (typeof v === "bigint" ? v.toString() : v),
  ),
});

Managed accounts automatically support all available source chains — this step is only needed for user-owned accounts.

To select the destination token from the source chain, token, or symbol, configure token routing during registration.

Setup

Funding

Processing and tracking

Fees

Account registration

Choose an account type

Register an account

Adding source chains

​Choose an account type

​Register an account

​Adding source chains

Choose an account type

Register an account

Adding source chains