Frontend SDK

The frontend SDK (@blend-money/fe) handles wallet authentication, deposit/withdrawal quoting, and on-chain execution in the browser.

Quick-start flow

Install @blend-money/fe and viem
Create a BlendSdk instance with your publishable key and paymaster
Sign in with sdk.signIn()
Quote with sdk.quoteDeposit() or sdk.quoteWithdraw()
Execute with sdk.execute(quote, { deriveSigner })

Install

Frontend
Server

pnpm
npm
yarn

pnpm add @blend-money/fe@3.0.1 viem@2.55.8

npm install @blend-money/fe@3.0.1 viem@2.55.8

yarn add @blend-money/fe@3.0.1 viem@2.55.8

pnpm
npm
yarn

pnpm add @blend-money/node@3.0.1

npm install @blend-money/node@3.0.1

yarn add @blend-money/node@3.0.1

Configuration

import {
  BlendSdk,
  getPimlicoPaymasterEndpoints,
} from "@blend-money/fe";

const sdk = new BlendSdk({
  publishableKey: "pk_live_abc123...",
  signMessage: (msg) => walletClient.signMessage({ message: msg }),
  paymaster: getPimlicoPaymasterEndpoints("pimlico_api_key_here"),
});

Field	Type	Required	Description
`publishableKey`	`string`	Yes	Client-safe key (`pk_live_`). Identifies your organization and account type.
`signMessage`	`(message: string) => Promise<string>`	For sign-in	Wallet signing function for SIWE. A restored, unexpired session can run without it.
`paymaster`	`PaymasterRegistry`	Yes	Pimlico or Alchemy bundler/paymaster endpoints keyed by chain ID
`baseUrl`	`string`	No	Blend API base URL. Defaults to production.
`fiatCurrency`	`string`	No	ISO 4217 code (e.g. `"EUR"`). Adds this currency to monetary responses.
`timeoutMs`	`number`	No	Request timeout in milliseconds. Default: `15000`.
`retries`	`number`	No	Max retries for `429` and `5xx`. Default: `3`.

Use an Alchemy Gas Manager policy for Alchemy-backed chains:

import {
  getAlchemyPaymasterEndpoints,
  getPimlicoPaymasterEndpoints,
} from "@blend-money/fe";

const paymaster = {
  ...getPimlicoPaymasterEndpoints("pimlico-key", [8453]),
  ...getAlchemyPaymasterEndpoints(
    "alchemy-key",
    { policyId: "policy-id" },
    [137],
  ),
};

Later entries replace earlier ones for the same chain. Execution throws VALIDATION_ERROR if the registry has no entry for a required chain. SDK 3.0.1 gets gas prices from the configured bundler. It does not call a Blend gas-price method.

Authentication

Signs the user in with SIWE. The first sign-in creates the account record and deterministic Safe address. It does not deploy the Safe on-chain.

const session = await sdk.signIn({
  address: "0x1111111111111111111111111111111111111111",
  chainId: 8453,
});

chainId defaults to 1. It sets the SIWE message chain and does not deploy the Safe. Returns an AuthSession:

Field	Type	Description
`address`	`string`	Authenticated wallet address
`accountId`	`string`	Blend account ID
`safeAddress`	`string`	On-chain Safe address
`chainsDeployed`	`number[]`	Chains where the Safe is live
`expiresAt`	`string`	ISO 8601 expiry (1 hour)

Check chainsDeployed to see where the Safe is live. If you need the Safe on a chain that isn’t listed, request deployment:

await sdk.account.safe.request(137); // Deploy on Polygon

See Safe deployment for the full pattern.

signOut

Revokes the JWT server-side and clears local state.

await sdk.signOut();

isSignedIn

Read-only boolean. true if a session is active.

if (sdk.isSignedIn) {
  // authenticated
}

session

Returns the current AuthSession. Throws SdkError with code AUTH_NOT_SIGNED_IN if not authenticated.

const { accountId, safeAddress } = sdk.session;

exportSession / restoreSession

Persist and restore sessions across page reloads.

// Save before unload
const snapshot = sdk.exportSession();
sessionStorage.setItem("blend", JSON.stringify(snapshot));

// Restore on next load
const saved = JSON.parse(sessionStorage.getItem("blend")!);
sdk.restoreSession(saved);

Use sessionStorage, not localStorage. Clear the session when the wallet disconnects or the address changes.

Quoting

quoteDeposit

Quotes a deposit. Creates a session automatically if one doesn’t exist.

import { parseAmount } from "@blend-money/fe";

const quote = await sdk.quoteDeposit({
  chainId: 8453,
  tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  amount: parseAmount("100", 6),
  externalRef: "order-123",
});

Parameter	Type	Required	Description
`chainId`	`number`	Yes	Origin chain ID
`tokenAddress`	`string`	Yes	Token contract on the origin chain
`amount`	`string`	Yes	Smallest unit, non-negative integer string
`externalRef`	`string`	No	Your reconciliation reference
`forceReset`	`boolean`	No	Cancel existing session first. Default: `false`.

Returns a DepositQuote:

Field	Type	Description
`type`	`"DEPOSIT"`	Quote type
`intentId`	`string`	Session ID
`originChainId`	`number`	Chain the user sends from
`destinationChainId`	`number`	Chain where funds arrive
`input`	`object`	`symbol`, `amount`, `amountUsd` the user sends
`output`	`object`	`symbol`, `amount`, `amountUsd` arriving in the vault
`fees.totalUsd`	`string`	Total fees in USD
`estimatedSeconds`	`number`	Estimated settlement time
`expiresAt`	`string`	When this quote expires

quoteWithdraw

Quotes a withdrawal. Blend picks which chains to pull funds from.

const quote = await sdk.quoteWithdraw({
  destinationChainId: 8453,
  amount: parseAmount("50", 6),
});

For a full exit, set isMaxWithdraw: true and amount: "0":

const quote = await sdk.quoteWithdraw({
  destinationChainId: 8453,
  amount: "0",
  isMaxWithdraw: true,
});

A full withdrawal redeems every source-chain position. For any withdrawal, partial or full, where a source chain differs from destinationChainId, Vault embeds Relay bridge calldata inside the atomic withdrawal transaction. The returned step list may not contain a separate bridge step, but the execution still routes those funds to the requested destination. Returns a WithdrawQuote:

Field	Type	Description
`type`	`"WITHDRAW"`	Quote type
`intentId`	`string`	Session ID
`destinationChainId`	`number`	Chain where funds arrive
`totalAmount`	`string`	Total withdrawal in loan token smallest units
`totalFeesUsd`	`string`	Total fees in USD
`estimatedSeconds`	`number`	Estimated settlement time
`sourceChainCount`	`number`	Number of source chains
`sourceChainIds`	`number[]`	Which chains funds are pulled from
`expiresAt`	`string`	When this quote expires

Execution

execute

Locks the quote, submits transactions through the user’s Safe, and records their hashes. New sessions settle as soon as the API accepts the hashes. Legacy SUBMITTED sessions can still require polling.

const signerAddress = "0x1111111111111111111111111111111111111111";

const result = await sdk.execute(quote, {
  signerAddress,
  deriveSigner: async (chainId) => ({
    signer: getWalletClient({ chainId, account: signerAddress }),
    publicClient: getPublicClient({ chainId }),
  }),
  onStatusChange: (status) => console.log(status),
});

Parameter	Type	Required	Description
`signerAddress`	`string`	Yes	EOA hex address. Must match the `deriveSigner` output.
`deriveSigner`	`(chainId: number) => Promise<DeriveSignerResult>`	Yes	Returns a viem `WalletClient` and `PublicClient` for the target chain
`isContractSigner`	`boolean`	No	Set `true` for smart wallets (e.g. Coinbase). Default: `false`.
`onStatusChange`	`(status: ExecuteStatus) => void`	No	Called on each status transition
`pollIntervalMs`	`number`	No	Polling interval. Default: `3000`.
`pollTimeoutMs`	`number`	No	Max polling time. Default: `300000` (5 min).

deriveSigner is called once per action plan. For deposits, that means once. For withdrawals, once per source chain. Return clients configured for the requested chain. The wallet client must have an attached account whose address matches signerAddress. DeriveSignerResult:

Field	Type	Description
`signer`	`WalletClient`	viem WalletClient for the target chain
`publicClient`	`PublicClient`	viem PublicClient for the target chain

ExecuteResult:

Field	Type	Description
`status`	`"settled" \| "failed" \| "cancelled"`	Terminal status
`txHashes`	`Array<{ hash: string; chainId: number }>`	Submitted transaction hashes
`settledAt`	`string \| null`	ISO 8601 settlement time
`error`	`string \| null`	Error message if failed

Discovery

These methods are available on sdk.discover after sign-in. Every frontend route outside challenge and verify requires the SIWE bearer session.

const chains = await sdk.discover.depositChains();
const tokens = await sdk.discover.depositTokens(8453);
const destinations = await sdk.discover.withdrawDestinations();
const yieldData = await sdk.discover.yield();

See SDK Reference for response shapes.

Account data

These methods are available on sdk.account after sign-in.

const balance = await sdk.account.balance();
const history = await sdk.account.balanceHistory();
const positions = await sdk.account.positions();
const returns = await sdk.account.returns();

See SDK Reference for response shapes.

Cancel in-flight requests

Every async HTTP method accepts RequestOptions as its last argument. Pass an AbortSignal when a user changes an input during live quoting.

const controller = new AbortController();

const quote = await sdk.quoteDeposit(
  {
    chainId: 8453,
    tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    amount: "100000000",
  },
  { signal: controller.signal },
);

Error handling

Every SDK method can throw SdkError. Catch it to get structured error info.

import { SdkError } from "@blend-money/fe";

try {
  const quote = await sdk.quoteDeposit({ /* ... */ });
} catch (error) {
  if (error instanceof SdkError) {
    console.error(error.code);            // "INTENT_EXPIRED"
    console.error(error.status);          // 410
    console.error(error.getUserMessage()); // user-friendly text
    if (error.isRetryable()) { /* retry */ }
  }
}

See SDK Reference for the full error codes table.

What to watch out for

Don’t create a new session to change the amount, token, or chain. Call the same quote method again while the session is OPEN. To switch between a deposit and withdrawal in the high-level frontend SDK, pass forceReset: true; this discards the opposite-type active session and starts a new one. Don’t store sessions in localStorage. Use sessionStorage and clear it when the wallet disconnects. Don’t treat onStatusChange as the final result. SDK 3.0.1 can emit the legacy-compatible "confirming" callback even when the API settles directly. Use the returned ExecuteResult, then use balances and positions to confirm indexed activity. Don’t ignore isContractSigner. If your users connect smart wallets (Coinbase Wallet, Safe), set it to true or signing will fail.

Deposits & Withdrawals

Full deposit and withdrawal flows with cross-chain routing.

SDK Reference

Auth, accounts, balances, error codes, and types.

Getting Started

Portal Guide

SDK

Going Deeper

Frontend SDK

Quick-start flow

Install

Configuration

Authentication

signOut

isSignedIn

session

exportSession / restoreSession

Quoting

quoteDeposit

quoteWithdraw

Execution

execute

Discovery

Account data

Cancel in-flight requests

Error handling

What to watch out for

Deposits & Withdrawals

SDK Reference

​Quick-start flow

​Install

​Configuration

​Authentication

​signIn

​signOut

​isSignedIn

​session

​exportSession / restoreSession

​Quoting

​quoteDeposit

​quoteWithdraw

​Execution

​execute

​Discovery

​Account data

​Cancel in-flight requests

​Error handling

​What to watch out for

Deposits & Withdrawals

SDK Reference

Quick-start flow

Install

Configuration

Authentication

signIn

signOut

isSignedIn

session

exportSession / restoreSession

Quoting

quoteDeposit

quoteWithdraw

Execution

execute

Discovery

Account data

Cancel in-flight requests

Error handling

What to watch out for