SDK guide - `@concrete-xyz/sdk`

Level: Advanced · Based on the official Earn V2 SDK docs. Method names/versions can change - confirm at docs.concrete.xyz/Developers/SDK.

What it provides

• Query vault details: decimals, symbols, total assets, balances.
• Approvals for the underlying ERC-20.
• Deposits and redemptions (mint/redeem shares).
• Preview conversions to estimate output before sending a tx.
• Multi-chain support: Ethereum, Arbitrum, Berachain, Katana, Corn, Morph.
• Built on viem; works with vanilla JS/TS (ethers), React hooks and Wagmi.

Install

npm install @concrete-xyz/sdk
# vanilla usage also needs: npm install ethers
# React:  import { useVault } from "@concrete-xyz/sdk/react"
# Wagmi:  import { useVault, useVaultQuery } from "@concrete-xyz/sdk/wagmi"

Prerequisites

Vanilla (ethers)

import { getVault } from "@concrete-xyz/sdk";
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://ethereum-rpc.publicnode.com");
const vault = getVault("v1", "0xVaultAddress", 1, provider);   // read-only
const details = await vault.getVaultDetails();
console.log(details.vaultAsset.symbol);

Add a signer as the 5th argument for writes.

React & Wagmi

• React: useVault(version, address, chainId, provider, signer) - chainId must be a number.
• Wagmi: no provider config needed (auto-detected). Prefer useVaultQuery({ vault, queryKey, queryFn }), which handles loading/error states; useVault can briefly return undefined while connectors load.

Sections in the official docs

Setup Configuration · Migrating from 1.x · Read Methods (e.g. balanceOf) · Write Methods (e.g. approve) · Decimals & Conversion Helpers · Examples · Troubleshooting & Error Handling. There is also a documented REST read for vault transparency: GET /v1/vault:transparency/stats (params: vault address + chain ID) returning totalPortfolioAssetsOffchainUsd, byAsset, byProtocol, byPlatform, timestamp (data ~24 h delayed).

Integration best practices

1. Preview before you send: use preview/convert helpers and show slippage/expected shares.
2. Handle decimals explicitly - vault share decimals may differ from asset decimals.
3. Read the vault type (atomic vs queued vs pre-deposit) and render the right UX: an instant withdraw button on a queued vault will fail or mislead.
4. Respect limits: max deposit cap, per-user cap, min/max amounts, cooldown/locks.
5. Never embed private keys in front-end code; sign via the user's wallet.
6. Fallback RPCs and retry/backoff; reads are cheap, rate limits aren't.
7. Cross-check with the subgraph for historical data rather than scanning logs.

See examples/typescript/ for runnable-shape samples (not executed against a live chain by this repo's author).