Rhinestone SDK

Smart wallets and multichain transactions for your application

Rhinestone is self-custodial stablecoin infrastructure for fintechs. Give users an account they control, help them fund it, and move value across chains, tokens, and currencies through one integration. This SDK covers two of its products:

• Wallets — smart wallets inside your application, approved with a passkey, with session keys and recovery.
• Transactions — payments, swaps, and contract calls funded from any supported chain, with fees you can sponsor.

Deposits have their own integration: see the docs.

Documentation

Features

• Multichain Transactions - Execute transactions on any target chain using assets from any source chain. The orchestrator handles routing and settlement. Learn more

• Swaps - Token exchanges via solver-based swaps or injected DEX aggregator swaps, integrated into crosschain transaction execution. Learn more

• Passkeys - WebAuthn-based authentication for smart accounts, replacing seed phrases with device biometrics. Learn more

• Session Keys - Onchain permissions system for scoped transaction automation, enabling one-click UX and server-side execution with granular policies. Learn more

• Sponsorship - Subsidize gas, bridge, and swap fees for users by depositing USDC on Base. Applies across all supported chains. Learn more

Installation

npm install viem @rhinestone/sdk

bun install viem @rhinestone/sdk

Authentication

The SDK supports two authentication modes: API key and JWT.

API Key

Pass the API key from the Rhinestone dashboard:

const rhinestone = new RhinestoneSDK({
  auth: {
    mode: 'apiKey',
    apiKey: 'your-api-key',
  },
})

JWT (Experimental)

JWT authentication uses RS256-signed tokens for fine-grained access control. There are two integration patterns depending on your architecture:

Client-server (SDK runs in browser/client)

When the SDK runs on the client and a separate backend holds the signing key, fetch tokens via HTTP:

const rhinestone = new RhinestoneSDK({
  auth: {
    mode: 'experimental_jwt',
    accessToken: async () => {
      const res = await fetch('/api/auth/token')
      const { token } = await res.json()
      return token
    },
    // Only needed for sponsored intents:
    getIntentExtensionToken: async (intentInput) => {
      const res = await fetch('/api/auth/extension-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ intentInput }),
      })
      const { token } = await res.json()
      return token
    },
  },
})

Your backend is responsible for signing JWTs with the correct claims. See the JWT documentation for the required token format.

Same-host (SDK and signing key on the same server)

When the SDK runs server-side with access to the private key, use createJwtSigner to sign tokens in-process without an HTTP round-trip:

import { createJwtSigner } from '@rhinestone/sdk/jwt-server'

const signer = createJwtSigner({
  jwt: {
    privateKey: myJwk, // RS256 private key in JWK format
    integratorId: 'int_abc',
    projectId: 'proj_xyz',
    appId: 'app_prod',
    keyId: 'key_1',
  },
})

const rhinestone = new RhinestoneSDK({
  auth: { mode: 'experimental_jwt', ...signer },
})

createJwtSigner returns { accessToken, getIntentExtensionToken } — the same shape as the auth config, so you can spread it directly. It handles all claim structure, key caching, and intent digest computation internally.

To control which intents your backend sponsors, pass shouldSponsor filters. The signer checks them before signing — denied requests throw a SponsorshipDeniedError:

import { createJwtSigner } from '@rhinestone/sdk/jwt-server'

const signer = createJwtSigner({
  // ...
  shouldSponsor: {
    chain: ({ id }) => [1, 8453, 10].includes(id),
    account: async (address) => isUser(address),
  },
})

Quickstart

Create a smart account:

import { RhinestoneSDK } from '@rhinestone/sdk'

const rhinestone = new RhinestoneSDK({ apiKey: 'your-api-key' })
const account = await rhinestone.createAccount({
  owners: {
    type: 'ecdsa',
    accounts: [signer],
  },
})

Send a crosschain transaction:

const prepared = await account.prepareTransaction({
  sourceChains: [baseSepolia],
  targetChain: arbitrumSepolia,
  calls: [
    {
      to: usdc,
      value: 0n,
      data: encodeFunctionData({
        abi: erc20Abi,
        functionName: 'transfer',
        args: [recipient, amount],
      }),
    },
  ],
  tokenRequests: [{ address: usdc, amount }],
})

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

Create a smart session from ABI-driven permissions:

import { toSession } from '@rhinestone/sdk/smart-sessions'

const session = toSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionSigner],
  },
  permissions: [
    {
      abi: erc20Abi,
      address: usdc,
      functions: {
        transfer: {
          params: {
            recipient: { condition: 'equal', value: recipient },
            amount: { condition: 'lessThanOrEqual', value: 1000n },
          },
        },
      },
    },
  ],
  claimPolicies: [
    {
      type: 'permit2',
      spenders: [permit2Spender],
      sourceTokens: [{ chain: base, address: usdc }],
      destinationTokens: [{ chain: optimism, address: usdc }],
      recipients: [{ chain: optimism, address: recipient }],
      permitDeadline: { max: permitDeadline },
      fillDeadline: [{ chain: optimism, max: fillDeadline }],
    },
  ],
})

Smart Session ERC-1271 signing is unrestricted when signing is omitted. It can be disabled, time-boxed, or scoped to exact EIP-712 domains and schemas:

const disabled = { mode: 'disabled' } as const
const timeboxed = {
  mode: 'unrestricted',
  validAfter: new Date(),
  validUntil: new Date(Date.now() + 60 * 60 * 1000),
} as const
const scoped = {
  mode: 'scoped',
  allowedContents: [
    {
      domain: {
        name: 'Permit2',
        chainId: base.id,
        verifyingContract: permit2,
      },
      types: {
        Permit: [
          { name: 'spender', type: 'address' },
          { name: 'amount', type: 'uint256' },
        ],
      },
      primaryType: 'Permit',
    },
  ],
} as const

A scoped entry constrains its domain and schema, not message values. Scoped configuration can be enabled on-chain, but this SDK intentionally rejects scoped direct signing until safe ERC-7739 signature emission is available.

For a complete walkthrough, see the Quickstart guide.

Migrating from Orchestrator SDK

To migrate from the Orchestrator SDK, replace all imports of @rhinestone/orchestrator-sdk with @rhinestone/sdk.

Let us know if you encounter any issues!

Contributing

For feature or change requests, feel free to open a PR, start a discussion or get in touch with us.