SDK reference

Full surface of @stablechain/sdk. This covers the signing client from createStable, the read-only client from createStableReader, and the shared enums, constants, and error classes. For a walkthrough, see SDK quickstart. For a task-focused earn guide, see Earn yield with the SDK.

Install

npm install @stablechain/sdk viem

added 2 packages, audited 3 packages in 2s

viem >= 2.0.0 is a peer dependency.

createStable(config)

Construct a StableClient. Returns an object with the methods listed under StableClient.

import { createStable, Network } from "@stablechain/sdk";
 
const stable = createStable({ network: Network.Mainnet, account });

StableClient { transfer, quoteBridge, bridge, quoteSwap, swap, earn }

StableConfig

Provide one of account, transport, or walletClient. The earn field is optional: transfer, bridge, and swap work without it. Vault deposits and withdrawals require it, and the SDK throws StableValidationError if you call them without a configured vault.

StableClient

transfer(params)

Send native USDT0 or any ERC-20 on Stable. Switches the wallet to the Stable chain, fetches token decimals on-chain when missing, and waits for the receipt.

const { txHash } = await stable.transfer({
  from: "0xYourAddress",
  to: "0xRecipient",
  amount: 10,
});

{ txHash: "0x8f3a...2d41" }

Returns OperationResult ({ txHash, toAmount? }).

quoteBridge(params)

Preview a bridge. Read-only. No signature, no gas.

const quote = await stable.quoteBridge({
  fromChain: Chain.Ethereum,
  toChain: Chain.Stable,
  fromToken: "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT on Ethereum
  toToken: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", // USDT0 on Stable
  amount: 100,
});

{ toAmount: 99.73 }

Returns BridgeQuote.

bridge(params)

Bridge tokens cross-chain via LI.FI, which picks the bridge route. The SDK handles the ERC-20 approval and switches the wallet to the source chain before sending. Pass a pre-fetched quote to skip the internal quote call.

const { txHash } = await stable.bridge({ ...bridgeParams, quote });

{ txHash: "0xabcd...7890" }

quoteSwap(params)

Fetch a LI.FI swap quote on Stable. Returns a pre-built transaction request and the approval address.

const quote = await stable.quoteSwap({
  fromToken: "0x8a2B28364102Bea189D99A475C494330Ef2bDD0B",
  toToken: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
  amount: 100,
  fromDecimals: 6,
});

{ toAmount: 99.81, fromAmount: 100000000n, fromToken: "0x8a2B...", approvalAddress: "0x...", transactionRequest: { ... } }

swap(params)

Swap tokens on Stable via LI.FI. Handles ERC-20 approval automatically and switches the wallet's chain when needed.

const { txHash, toAmount } = await stable.swap({ ...swapParams, quote });

{ txHash: "0xabcd...", toAmount: 99.81 }

stable.earn

Supply USDT0 into a Morpho V2 vault to earn yield, and claim Merkl incentive rewards. All methods live under the earn namespace and require a signer. The deposit, withdraw, redeem, and prepare-calldata methods also require earn: { vault } in StableConfig.

const stable = createStable({
  network: Network.Mainnet,
  account,
  earn: { vault: "0xb7Df8db22A5DBBFA9ebeb94b3910aec6a4f05c08" },
});

stable.earn { deposit, bulkDeposit, withdraw, bulkWithdraw, redeem, forceWithdraw, forceRedeem, prepareDepositCalldata, prepareWithdrawCalldata, prepareRedeemCalldata, incentiveRewards }

Amounts and share counts are human-readable numbers. Asset and share decimals are fetched on-chain when you omit them. The deposit, withdraw, redeem, and force methods return EarnResult ({ txHash, idempotencyKey? }) and wait for the receipt before resolving. The bulk methods return BulkEarnResult and incentiveRewards.claim() returns MerklClaimResult, described in their sections below.

deposit(params)

Supply assets to the vault. Handles the ERC-20 approval (or a permit signature when the wallet supports it), then the deposit, in one call.

const { txHash } = await stable.earn.deposit({ amount: 100 });

{ txHash: "0x8f3a...2d41" }

withdraw(params)

Withdraw a given amount of underlying assets. When idle vault liquidity is short, the SDK automatically deallocates from the vault's adapters to cover the difference.

const { txHash } = await stable.earn.withdraw({ amount: 50 });

{ txHash: "0xabcd...7890" }

redeem(params)

Redeem a number of vault shares back to underlying assets. Like withdraw, it deallocates from adapters automatically when idle liquidity is short.

const { txHash } = await stable.earn.redeem({ shares: 25 });

{ txHash: "0xabcd...7890" }

bulkDeposit(items, options?) / bulkWithdraw(items, options?)

Run several deposits or withdrawals in sequence. By default the batch attempts every item and returns partial results. Set stopOnError: true to halt on the first failure and throw StableBulkError.

const result = await stable.earn.bulkDeposit([
  { amount: 100 },
  { amount: 250, vault: "0xAnotherVault" },
]);

{ results: [ { status: "fulfilled", txHash: "0x..." }, ... ], succeeded: 2, failed: 0 }

items is an array of EarnDepositParams (or EarnWithdrawParams). options accepts:

Returns BulkEarnResult ({ results, succeeded, failed, idempotencyKey? }). Each entry in results is either { status: "fulfilled", txHash, vault?, idempotencyKey? } or { status: "rejected", error, vault?, idempotencyKey? }.

forceWithdraw(params) / forceRedeem(params)

Withdraw or redeem with explicit control over which adapter positions to deallocate first. Use these when you need to choose the source markets yourself instead of the automatic selection in withdraw / redeem.

const { txHash } = await stable.earn.forceWithdraw({
  amount: 1000,
  deallocations: [{ adapter: "0xAdapter", amount: 1000 }],
});

{ txHash: "0xabcd...7890" }

Both take a deallocations: ForceDeallocation[] array and an optional tokenDecimals (underlying asset decimals, used for the deallocation amounts; fetched on-chain when omitted). forceWithdraw takes amount; forceRedeem takes shares plus optional shareDecimals. Each ForceDeallocation is:

prepareDepositCalldata(params) / prepareWithdrawCalldata(params) / prepareRedeemCalldata(params)

Build the transaction calldata without signing or sending. Use these to route the transaction through a relayer, a gas-waiver flow, or a multisig.

const { steps, chainId } = await stable.earn.prepareDepositCalldata({ amount: 100 });

{ steps: [ { to: "0x...", data: "0x...", value: 0n } ], chainId: 988 }

prepareDepositCalldata returns EarnDepositCalldata ({ steps, chainId }), where steps is an ordered list of { to, data, value } transactions: an optional token approval followed by the deposit. prepareWithdrawCalldata and prepareRedeemCalldata return EarnWithdrawCalldata ({ to, data, value, chainId }), a single transaction. They accept the same params as their signing counterparts.

incentiveRewards

Fetch and claim Merkl reward tokens for the signer. These methods need a signer but not an earn vault config.

const { rewards } = await stable.earn.incentiveRewards.fetch();
const { txHash, tokenCount } = await stable.earn.incentiveRewards.claim();

{ txHash: "0xabcd...7890", tokenCount: 1 }

fetch() returns MerklRewardsResult ({ chainId, rewards: MerklReward[] }) with the net claimable amount per token. claim() claims every reward committed to the current Merkl merkle tree and returns MerklClaimResult ({ txHash, tokenCount }).

createStableReader(config)

Construct a read-only StableReader for vault yield and position data. No signer is needed, only the address you want to read.

import { createStableReader, Network } from "@stablechain/sdk";
 
const reader = createStableReader({
  network: Network.Mainnet,
  address: "0xUserAddress",
  earn: { vault: "0xb7Df8db22A5DBBFA9ebeb94b3910aec6a4f05c08" },
});

StableReader { earn: { getYield, position, preview, withdrawability, incentiveRewards } }

StableReaderConfig

StableReader

getYield()

Return the vault's current net APY and fee breakdown.

const vaultYield = await reader.earn.getYield();

{ apy: 0.058, native: 0.041, rewards: [ { symbol: "MORPHO", address: "0x...", apr: 0.017 } ], performanceFee: 0.1, managementFee: 0 }

Returns VaultYield. apy is the total net APY after fees including reward boosts; native is the underlying market yield excluding rewards. All values are decimals (0.05 = 5%).

position()

Return the configured address's current vault position.

const position = await reader.earn.position();

{ shares: 100000000n, sharesFormatted: 100, shareDecimals: 6, assets: 101.2, tokenDecimals: 6, assetAddress: "0x..." }

Returns VaultPosition with the raw shares balance, its sharesFormatted human value, and the assets value of those shares in underlying units.

preview(params)

Project the yield on an amount over a horizon, using the vault's live net APY.

const preview = await reader.earn.preview({ amount: 1000, horizonDays: 30 });

{ projectedYield: 4.64, apy: 0.058, horizonDays: 30 }

Returns YieldPreview ({ projectedYield, apy, horizonDays }).

withdrawability(params)

Check whether an amount can be withdrawn instantly from the vault's idle liquidity.

const status = await reader.earn.withdrawability({ amount: 5000 });

{ isInstant: true, availableLiquidity: 12500.5, tokenDecimals: 6 }

Returns WithdrawStatus ({ isInstant, availableLiquidity, tokenDecimals }). When isInstant is false, the withdrawal needs an adapter deallocation, which stable.earn.withdraw handles automatically.

incentiveRewards.fetch()

Read pending Merkl rewards for the configured address. Read-only counterpart to stable.earn.incentiveRewards.fetch.

const { rewards } = await reader.earn.incentiveRewards.fetch();

{ chainId: 988, rewards: [ { token: { symbol: "MORPHO", ... }, amount: 1.25, rawAmount: "1250000...", proofs: [...] } ] }

Returns MerklRewardsResult.

Enums

Network

Chain

Used by quoteBridge and bridge. Each entry has a corresponding CHAIN_CONFIGS entry. The two testnet entries are defined for completeness, but LI.FI rejects them: bridging works only between the mainnet chains.

CHAIN_CONFIGS

Partial<Record<Chain, ChainConfig>> keyed by Chain enum. Each entry exposes id, rpc, usdt, and decimals. Use it when you need the canonical USDT address on a supported chain without hard-coding it.

import { CHAIN_CONFIGS, Chain } from "@stablechain/sdk";
 
console.log(CHAIN_CONFIGS[Chain.Stable]);

{ id: 988, rpc: "https://rpc.stable.xyz", usdt: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", decimals: 6 }

Constants

Canonical mainnet addresses, exported so you don't hard-code them.

import { STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS } from "@stablechain/sdk";

STABLE_USDT_ADDRESS  0x779ded0c9e1022225f8e0630b35a9b54be713736
STABLE_VAULT_ADDRESS 0xb7Df8db22A5DBBFA9ebeb94b3910aec6a4f05c08

Errors

All SDK errors extend StableError, which extends viem's BaseError. Errors carry structured metadata so you can branch on error.name or instanceof.

import { StableTransactionError } from "@stablechain/sdk";
 
try {
  await stable.transfer({ from, to, amount: 1 });
} catch (err) {
  if (err instanceof StableTransactionError && err.phase === "switch_chain") {
    // user rejected the chain switch
  }
  throw err;
}

StableTransactionError: transfer: wallet rejected or failed to switch to chain 988
  Phase: switch_chain
  Chain ID: 988

Next recommended

• SDK quickstart: Install the SDK and run your first transfer on testnet.
• Use with viem: Switch between private-key, browser-wallet, and pre-built signers.
• Use with wagmi: Wire the SDK into a React app with hooks.