SDK Reference

Authentication, account management, balance queries, error handling, and TypeScript type definitions.

Authentication

SIWE flow (frontend)

The frontend SDK uses Sign-In with Ethereum. The user’s wallet signs a challenge message. Blend returns a JWT that binds the wallet to a Blend account. The JWT contains the wallet address, account ID, and account type. Every SDK call after sign-in includes it automatically. You never pass an account ID.

API key auth (server)

The server SDK authenticates with an API key (sk_live_) in the X-API-Key header. No challenge/verify step. The API key replaces both the publishable key and the SIWE session.

import { BlendServerSdk } from "@blend-money/node";

const sdk = new BlendServerSdk({
  apiKey: process.env.BLEND_API_KEY!,
  accountTypeId: "savings-usd",
});

You pass accountId explicitly to every account-scoped call via sdk.forAccount(accountId).

Rate limits

Endpoint	Limit	Scoped by
SIWE challenge (`POST /auth/challenge`)	10 / 60 seconds	IP address
SIWE verify (`POST /auth/verify`)	5 / 60 seconds	IP address
Account-scoped routes (frontend)	100 / 60 seconds	Wallet address
Server routes before authentication	100 / 60 seconds	IP address
Account-scoped routes (server)	100 / 60 seconds	API key

Exceeding limits returns a 429 with error code RATE_LIMITED or RATE_LIMIT.

Session security

Keep JWTs in memory. Use sessionStorage for persistence across reloads. Avoid localStorage.
Clear the session when the wallet disconnects or address changes.
Never share an exported session across users or account types.

Auth error codes

Code	Status	What to do
`AUTH_NOT_SIGNED_IN`	401	Call `sdk.signIn()`.
`AUTH_CHALLENGE_FAILED`	500	Check publishable key and network. Retry.
`AUTH_VERIFICATION_FAILED`	401	User may have cancelled signing or wallet address mismatch.
`AUTH_TOKEN_EXPIRED`	401	JWT expired. The SDK auto-refreshes, but call `signIn()` if it persists.
`AUTH_INVALID_SESSION`	400	Malformed data in `restoreSession()`. Clear and sign in again.

Accounts

Resolution

How Blend maps wallet addresses to accounts differs by SDK. Frontend (automatic): The publishable key identifies your organization and account type. SIWE proves wallet ownership. After sign-in, the account is implicit. Server (manual): The API key identifies your organization. The accountTypeId in the SDK config selects the product. You call sdk.lookupAccount(address) to resolve the account (creates it if new, but does not deploy a Safe). Then call sdk.forAccount(accountId) to scope operations, and safe.request(chainId) to deploy a Safe.

Safe submodule

Check and trigger Safe deployments on specific chains.

// Check if Safe is deployed on a chain
const result = await sdk.account.safe.resolve(8453);

resolve returns a discriminated union:

Status	Meaning
`"validated"`	Safe exists on this chain. SDK 3.0.1 exposes `safeAddress` on this branch.
`"not-deployed"`	Safe hasn’t been deployed on this chain yet.
`"invalid"`	Safe ownership or configuration validation failed. Returns `error`.
`"disconnected"`	Safe is deployed, but its role-modifier module is missing. Returns `safeAddress` and `moduleNeeded`.

The REST response for "validated" also includes accountId, userAddress, and chainId. Those fields are not declared on the SDK 3.0.1 SafeResolution type. Use the authenticated account context when writing TypeScript against this release.

// Request deployment on a new chain
await sdk.account.safe.request(8453);

request is fire-and-forget. Deployment happens in the background.

Balance & positions

balance

Current aggregate balance with per-chain breakdown.

const balance = await sdk.account.balance();

Field	Type	Description
`accountId`	`string`	Blend account ID
`safeAddress`	`string`	On-chain Safe address
`perChain`	`BalancePerChain[]`	Per-chain vault breakdown with fiat values
`total`	`FiatAmount`	Aggregate balance across all chains
`heldAssets`	`HeldAsset[]`	Assets currently held in the Safe

Each perChain entry includes totalUnderlying in the token’s smallest unit and totalUnderlyingDecimals. Use getTotalUnderlyingBalance to normalize those values and sum them without floating-point arithmetic:

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

const balance = await sdk.account.balance();
const underlying = getTotalUnderlyingBalance(balance); // e.g. "501.5"

Server integrations import the same helper from @blend-money/node.

balanceHistory

Time-series balance snapshots. Use startDate and endDate to filter.

const history = await sdk.account.balanceHistory({
  startDate: "2025-01-01",
  endDate: "2025-03-01",
});

positions

All position events (deposits, withdrawals, rebalances) sorted newest first.

const positions = await sdk.account.positions();

positions.events is a discriminated union. Every event includes matching kind and eventType fields.

Event	Shared fields	Event-specific fields
`DEPOSIT`	`safeAddress`, `chainId`, `blockNumber`, `transactionHash`, `logIndex`, `blockTime`	`amount`, `price`, `tokenAddress`, `tokenSymbol`, `tokenDecimals`
`WITHDRAW`	Deposit fields	`vaultAddress`, `intendedRecipient`, `assetAddress`, `fee`, `bridged`
`REBALANCE`	`safeAddress`, `chainId`, `blockNumber`, `transactionHash`, `logIndex`, `blockTime`	`vaultAddress`, `swaps`, `usdValueIn`, `usdValueOut`

Narrow on either discriminator:

for (const event of positions.events) {
  if (event.kind === "REBALANCE") {
    console.log(event.swaps, event.usdValueIn, event.usdValueOut);
  } else {
    console.log(event.amount, event.price, event.tokenSymbol);
  }
}

For deposit and withdrawal events, price is the fiat value of the full event, not a per-token unit price. Rebalance events use usdValueIn and usdValueOut instead of price.

returns

Profit and loss metrics for the account.

const returns = await sdk.account.returns();

Field	Type	Description
`accountId`	`string`	Blend account UUID
`current`	`FiatAmount`	Current balance value
`totalDeposited`	`FiatAmount`	Sum of all deposits
`totalWithdrawn`	`FiatAmount`	Sum of all withdrawals
`netDeposited`	`FiatAmount`	`totalDeposited - totalWithdrawn`
`returns`	`FiatAmount`	`current - netDeposited`
`returnsPct`	`number`	`returns / netDeposited`, expressed as a ratio where `1` is 100%

Yield

Account-type-level yield data. Not per-account.

const yieldData = await sdk.discover.yield();

Field	Type	Description
`accountTypeId`	`string`	The account type
`yieldBreakdown`	`ChainYieldBreakdown[]`	Per-chain APY breakdown with base and boosted rates

Request cancellation

Every async SDK method that makes an HTTP request accepts RequestOptions as its final argument. Pass signal to cancel work when a user changes an input or a request is no longer needed.

const controller = new AbortController();

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

controller.abort();

For server session methods, RequestOptions follows the intent parameters:

await client.sessions.get(intentId, { signal: controller.signal });

Error handling

SdkError

All SDK methods throw SdkError on failure.

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

try {
  await sdk.quoteDeposit({ /* ... */ });
} catch (error) {
  if (error instanceof SdkError) {
    error.status;           // HTTP status code (0 for network)
    error.code;             // machine-readable code string
    error.message;          // human-readable description
    error.response;         // raw API response body
    error.isRetryable();    // true for 429, 5xx, network errors
    error.getUserMessage(); // user-friendly message
  }
}

Server integrations import SdkError from @blend-money/node. Both wrapper packages re-export the shared SDK types and utilities, so applications do not need to import @blend-money/core directly.

Error codes

Session errors:

Code	Status	Meaning
`FLOWPLAN_CONFLICT`	409	Rebalance in progress. Retry after it settles.
`INTENT_NOT_FOUND`	404	Session UUID not found.
`INTENT_EXPIRED`	410	Quote has expired. Re-quote.
`INTENT_WRONG_STATUS`	409	Session cannot be modified in current state.
`INTENT_CONCURRENT_TRANSITION`	409	Session status changed concurrently. Retry.
`SESSION_NOT_QUOTED`	409	Must quote before locking or executing.
`SESSION_LOCKED_BY_OTHER`	409	Locked by a different signer address.
`SETTLEMENT_TIMEOUT`	408	Polling a legacy `SUBMITTED` session exceeded the timeout (default 5 min).

Auth errors:

Code	Status	Meaning
`AUTH_NOT_SIGNED_IN`	401	Not authenticated. Call `signIn()`.
`AUTH_CHALLENGE_FAILED`	500	SIWE challenge request failed. Check publishable key.
`AUTH_VERIFICATION_FAILED`	401	Wallet signature verification failed.
`AUTH_TOKEN_EXPIRED`	401	JWT expired. Auto-refresh will attempt re-auth.
`AUTH_INVALID_SESSION`	400	Malformed session data in `restoreSession()`.

General errors:

Code	Status	Meaning
`NETWORK_ERROR`	0	No response from server.
`VALIDATION_ERROR`	400	Client-side validation failed.
`RATE_LIMITED` / `RATE_LIMIT`	429	Too many requests.
`NOT_FOUND`	404	Resource not found.
`TIMEOUT`	408	Request timed out.
`SERVER_ERROR`	500	Internal server error.
`NOT_IMPLEMENTED`	501	Feature not available.

Amount utilities

Convert between human-readable amounts and smallest-unit strings.

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

parseAmount("100.50", 6);   // "100500000"  (USDC: 6 decimals)
parseAmount("1.5", 18);     // "1500000000000000000"  (18 decimals)

formatAmount("100500000", 6);           // "100.5"
formatAmount("1500000000000000000", 18); // "1.5"

parseAmount rejects fractional digits exceeding the token’s decimal count. Server integrations import these utilities from @blend-money/node.

Key types

SessionStatus

type SessionStatus = "OPEN" | "LOCKED" | "SUBMITTED" | "SETTLED" | "FAILED" | "CANCELLED";

For new submissions, the persisted lifecycle is OPEN to LOCKED to SETTLED. The submit endpoint records accepted transaction hashes and settles the session directly. SETTLED does not mean Blend verified transaction receipts. Use balances and positions as the source of truth for indexed on-chain activity. SUBMITTED and FAILED remain in the type for historical sessions and compatible resume behavior. An executor can poll a legacy SUBMITTED session until it reaches a terminal state. Terminal states are SETTLED, FAILED, and CANCELLED.

DepositQuote

type DepositQuote = {
  readonly type: "DEPOSIT";
  readonly intentId: string;
  readonly originChainId: number;
  readonly destinationChainId: number;
  readonly input: { readonly symbol: string; readonly amount: string; readonly amountUsd: string };
  readonly output: { readonly symbol: string; readonly amount: string; readonly amountUsd: string };
  readonly fees: { readonly totalUsd: string };
  readonly estimatedSeconds: number;
  readonly expiresAt: string;
};

WithdrawQuote

type WithdrawQuote = {
  readonly type: "WITHDRAW";
  readonly intentId: string;
  readonly destinationChainId: number;
  readonly totalAmount: string;
  readonly totalFeesUsd: string;
  readonly estimatedSeconds: number;
  readonly sourceChainCount: number;
  readonly sourceChainIds: readonly number[];
  readonly expiresAt: string;
};

ExecuteResult

type ExecuteResult = {
  status: "settled" | "failed" | "cancelled";
  txHashes: Array<{ hash: string; chainId: number }>;
  settledAt: string | null;
  error: string | null;
};

ActionPlan

type ActionPlan = {
  deployType: "direct" | "multisend";
  requiredApprovals: Txn[];
  requiredTxns: Txn[];
  chainId: number;
};

Deposits produce a single ActionPlan with deployType: "direct". Withdrawals produce an ActionPlan[] with deployType: "multisend".

BalanceResponse

type BalanceResponse = {
  accountId: string;
  safeAddress: string;
  perChain: BalancePerChain[];
  total: FiatAmount;
  heldAssets: HeldAsset[];
};

Frontend SDK

Frontend configuration, auth, and execution.

Server SDK

Server configuration, account management, and sessions.

Getting Started

Portal Guide

SDK

Going Deeper

SDK Reference

Authentication

SIWE flow (frontend)

API key auth (server)

Rate limits

Session security

Auth error codes

Accounts

Resolution

Safe submodule

Balance & positions

balance

balanceHistory

positions

returns

Yield

Request cancellation

Error handling

SdkError

Error codes

Amount utilities

Key types

SessionStatus

DepositQuote

WithdrawQuote

ExecuteResult

ActionPlan

BalanceResponse

Frontend SDK

Server SDK

​Authentication

​SIWE flow (frontend)

​API key auth (server)

​Rate limits

​Session security

​Auth error codes

​Accounts

​Resolution

​Safe submodule

​Balance & positions

​balance

​balanceHistory

​positions

​returns

​Yield

​Request cancellation

​Error handling

​SdkError

​Error codes

​Amount utilities

​Key types

​SessionStatus

​DepositQuote

​WithdrawQuote

​ExecuteResult

​ActionPlan

​BalanceResponse

Frontend SDK

Server SDK

Authentication

SIWE flow (frontend)

API key auth (server)

Rate limits

Session security

Auth error codes

Accounts

Resolution

Safe submodule

Balance & positions

balance

balanceHistory

positions

returns

Yield

Request cancellation

Error handling

SdkError

Error codes

Amount utilities

Key types

SessionStatus

DepositQuote

WithdrawQuote

ExecuteResult

ActionPlan

BalanceResponse