Skip to main content
Time: 10-15 minutes. Integrate from TypeScript via the SDK, or from any language via the REST API. Either way, run it server-side — keys and signing stay on your infrastructure. WalletSuite returns unsigned transaction payloads you sign with your existing signer (KMS, HSM, custodian, or a local wallet).

​
What Your Application Will Be Able to Do

  • Query any wallet’s balance across multiple chains with fiat valuations
  • Look up token prices in real-time
  • Estimate transaction fees before executing
  • Prepare unsigned transaction payloads for your signing infrastructure
  • Resolve token contract addresses from symbols or names

​
Prerequisites

  • WalletSuite API key — see Credentials & Authentication
  • One of: Node.js 18+ (for the TypeScript SDK), Python 3.9+ with requests, or any HTTP client (curl, Go’s net/http, Ruby’s net/http, etc.)

​
Step 1 — Install

npm install @walletsuite/wallet-sdk

​
Step 2 — Initialize the Client

import { WalletSuiteSDK } from "@walletsuite/wallet-sdk";

const sdk = new WalletSuiteSDK({
  apiKey: process.env.WALLETSUITE_API_KEY!,
  env: "prod",
});
Store your API key in an environment variable or secret manager. Do not hardcode it in source files.

​
Step 3 — Query a Balance

const balance = await sdk.api.getNativeBalance("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", {
  chain: "ethereum",
  fiat: "USD",
});

console.log(balance.data);
// { chain: "ethereum", symbol: "ETH", amount: "1234.56", fiatValue: "3950000.00", ... }
For all token balances on a chain: 
const balances = await sdk.api.getAssetBalances("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", {
  chain: "ethereum",
  fiat: "USD",
  includeNative: true,
});

console.log(balances.data.totalFiatValue); // "4,120,000.00"
console.log(balances.data.assets);         // [{ symbol: "ETH", ... }, { symbol: "USDT", ... }]

​
Step 4 — Get a Price

// By symbol
const ethPrice = await sdk.api.getPrice("ETH");
console.log(ethPrice.data.value); // "3200.42"

// By contract address
const usdtPrice = await sdk.api.getPriceByContract(
  "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  { chain: "ethereum" }
);

​
Step 5 — Estimate Fees

const feeQuote = await sdk.api.getFeeQuote({
  chain: "ethereum",
  fromAddress: "0xabc...",
  toAddress: "0xdef...",
  amountWei: "1500000000000000000", // 1.5 ETH in wei
});

console.log(feeQuote.data);
// { chain: "ethereum", feeSymbol: "ETH", feeAmount: "0.002", fiatValue: "6.40", ... }

​
Step 6 — Prepare a Transfer

const prepared = await sdk.api.prepareSign({
  chain: "ethereum",
  txType: "TRANSFER_NATIVE",
  fromAddress: "0xabc...",
  toAddress: "0xdef...",
  amount: "1.5", // Human-readable ETH
});

console.log(prepared.data);
// { nonce, gasLimit, maxFeePerGas, value, data, estimatedFee, estimatedFeeInUsd, ... }
The response contains everything your signing infrastructure needs: nonce, gas parameters, calldata, and value. Sign this payload with your own key management (HSM, KMS, or any signer) and broadcast via your infrastructure or the WalletSuite API.

​
Token Transfers

For ERC-20 token transfers, resolve the contract first: 
// 1. Resolve the token
const asset = await sdk.api.getAssets({
  chain: "ethereum",
  symbol: "USDT",
});
const tokenContract = asset.data[0].id;

// 2. Prepare the transfer
const prepared = await sdk.api.prepareSign({
  chain: "ethereum",
  txType: "TRANSFER_TOKEN",
  fromAddress: "0xabc...",
  toAddress: "0xdef...",
  amount: "100",
  tokenContract,
});

​
Error Handling

All SDK errors include a category for programmatic handling: 
try {
  const balance = await sdk.api.getNativeBalance(address, { chain });
} catch (error) {
  switch (error.category) {
    case "validation":
      // Fix input (bad address, invalid chain)
      break;
    case "upstream":
      // Retry with backoff (WalletSuite API transient error)
      break;
    case "auth":
      // Check API key configuration
      break;
    case "limit":
      // Back off, retry later
      break;
    case "not_available":
      // Feature not enabled on your plan
      break;
  }
}
See SDK Error Handling for the full error taxonomy and handling patterns.

​
Architecture Recommendation

Run the SDK server-side, not in the browser. The integration shape: 
Browser → Your Server → WalletSuite SDK → unsigned tx payload
                                   │
                                   ▼
                                   Your signer (KMS / HSM / custodian / local wallet)
                                   │
                                   ▼
                                   Signed tx → WalletSuite API or your own RPC → Blockchain
This keeps your API key on the server, keeps signing inside your existing key infrastructure, and lets you add your own auth, rate limiting, and business logic between the user and WalletSuite. The SDK never sees keys or signed payloads — it returns typed unsigned payloads with everything your signer needs (nonce, gas parameters, calldata, value).

​
Next Steps