Add Wallet Operations to Your Application

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

pip install requests

# No install — curl ships with macOS, Linux, and Windows 10+.

Step 2 — Initialize the Client

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

const sdk = new WalletSuiteSDK({
  apiKey: process.env.WALLETSUITE_API_KEY!,
  env: "prod",
});

import os
import requests

session = requests.Session()
session.headers.update({
    "x-api-key": os.environ["WALLETSUITE_API_KEY"],
    "content-type": "application/json",
})
BASE_URL = "https://api.walletsuite.io"

export WALLETSUITE_API_KEY="your-key-here"
export WALLETSUITE_BASE_URL="https://api.walletsuite.io"

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", "ethereum", "USD");

console.log(balance.data);
// { chain: "ethereum", symbol: "ETH", amount: "1234.56", fiatValue: "3950000.00", ... }

address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
response = session.get(
    f"{BASE_URL}/api/balance/{address}",
    params={"chain": "ethereum", "fiat": "USD"},
)
print(response.json()["data"])
# { "chain": "ethereum", "symbol": "ETH", "amount": "1234.56", "fiatValue": "3950000.00", ... }

curl "$WALLETSUITE_BASE_URL/api/balance/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum&fiat=USD" \
  -H "x-api-key: $WALLETSUITE_API_KEY"

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", ... }]

address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
response = session.get(
    f"{BASE_URL}/api/balances/{address}",
    params={"chain": "ethereum", "fiat": "USD", "includeNative": "true"},
)
data = response.json()["data"]
print(data["totalFiatValue"])  # "4,120,000.00"
print(data["assets"])          # [{ "symbol": "ETH", ... }, { "symbol": "USDT", ... }]

curl "$WALLETSUITE_BASE_URL/api/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum&fiat=USD&includeNative=true" \
  -H "x-api-key: $WALLETSUITE_API_KEY"

Step 4 — Get a Price

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

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

# By symbol
eth_price = session.get(f"{BASE_URL}/api/price/ETH").json()
print(eth_price["value"])  # "3200.42"

# By contract address
usdt_price = session.get(
    f"{BASE_URL}/api/price/by-contract/0xdAC17F958D2ee523a2206206994597C13D831ec7",
    params={"chain": "ethereum"},
).json()

# By symbol
curl "$WALLETSUITE_BASE_URL/api/price/ETH" \
  -H "x-api-key: $WALLETSUITE_API_KEY"

# By contract address
curl "$WALLETSUITE_BASE_URL/api/price/by-contract/0xdAC17F958D2ee523a2206206994597C13D831ec7?chain=ethereum" \
  -H "x-api-key: $WALLETSUITE_API_KEY"

Step 5 — Estimate Fees

const feeQuote = await sdk.api.quoteTransferFee({
  chain: "ethereum",
  from: "0xabc...",
  to: "0xdef...",
  amountWei: "1500000000000000000", // 1.5 ETH in wei
  fiat: "USD",
});

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

response = session.post(
    f"{BASE_URL}/api/fees/quote",
    json={
        "chain": "ethereum",
        "from": "0xabc...",
        "to": "0xdef...",
        "amountWei": "1500000000000000000",  # 1.5 ETH in wei
    },
)
print(response.json()["data"])
# { "chain": "ethereum", "feeSymbol": "ETH", "feeAmount": "0.002", "fiatValue": "6.40", ... }

curl -X POST "$WALLETSUITE_BASE_URL/api/fees/quote" \
  -H "x-api-key: $WALLETSUITE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chain": "ethereum",
    "from": "0xabc...",
    "to": "0xdef...",
    "amountWei": "1500000000000000000"
  }'

Step 6 — Prepare a Transfer

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

console.log(prepared.data);
// { nonce, gasLimit, maxFeePerGas, value, data, estimatedFee, estimatedFeeInUsd, ... }

response = session.post(
    f"{BASE_URL}/api/txs/prepare-sign",
    json={
        "chain": "ethereum",
        "txType": "TRANSFER_NATIVE",
        "from": "0xabc...",
        "to": "0xdef...",
        "amount": "1.5",  # Human-readable ETH
    },
)
prepared = response.json()
# { nonce, gasLimit, maxFeePerGas, value, data, estimatedFee, estimatedFeeInUsd, ... }

curl -X POST "$WALLETSUITE_BASE_URL/api/txs/prepare-sign" \
  -H "x-api-key: $WALLETSUITE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chain": "ethereum",
    "txType": "TRANSFER_NATIVE",
    "from": "0xabc...",
    "to": "0xdef...",
    "amount": "1.5"
  }'
# { 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 assets = await sdk.api.listAssets("ethereum");
const tokenContract = assets.data?.find((a) => a.symbol === "USDT")?.id;

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

# 1. Resolve the token
asset = session.get(
    f"{BASE_URL}/api/assets",
    params={"chain": "ethereum", "symbol": "USDT"},
).json()
token_contract = asset["data"][0]["id"]

# 2. Prepare the transfer
prepared = session.post(
    f"{BASE_URL}/api/txs/prepare-sign",
    json={
        "chain": "ethereum",
        "txType": "TRANSFER_TOKEN",
        "from": "0xabc...",
        "to": "0xdef...",
        "amount": "100",
        "tokenContract": token_contract,
    },
).json()

# 1. Resolve the token (read .data[0].id from the response)
curl "$WALLETSUITE_BASE_URL/api/assets?chain=ethereum&symbol=USDT" \
  -H "x-api-key: $WALLETSUITE_API_KEY"

# 2. Prepare the transfer with the resolved tokenContract
curl -X POST "$WALLETSUITE_BASE_URL/api/txs/prepare-sign" \
  -H "x-api-key: $WALLETSUITE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chain": "ethereum",
    "txType": "TRANSFER_TOKEN",
    "from": "0xabc...",
    "to": "0xdef...",
    "amount": "100",
    "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
  }'

Error Handling

The SDK throws a typed ApiError carrying the HTTP status; the REST API returns the ApiResponse envelope (ok, code, message) alongside that status. Branch on it:

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

try {
  const balance = await sdk.api.getNativeBalance(address, chain);
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  switch (error.status) {
    case 400:
      // Fix input (bad address, invalid chain)
      break;
    case 401:
    case 403:
      // Check API key, or feature not enabled on your plan
      break;
    case 429:
      // Back off, retry later
      break;
    default:
      if (error.status && error.status >= 500) {
        // Retry with backoff (transient upstream error)
      }
  }
}

response = session.get(f"{BASE_URL}/api/balance/{address}", params={"chain": chain})

if not response.ok:
    code = response.json().get("code")  # error code from the ApiResponse envelope
    if response.status_code == 400:
        ...  # Fix input (bad address, invalid chain)
    elif response.status_code in (401, 403):
        ...  # Check API key, or feature not enabled on your plan (see code)
    elif response.status_code == 429:
        ...  # Back off, retry later
    elif response.status_code >= 500:
        ...  # Retry with backoff (transient upstream error)

# Capture the HTTP status; non-2xx responses carry an error envelope { "ok": false, "code", "message" }.
curl -sS -o response.json -w "%{http_code}" \
  "$WALLETSUITE_BASE_URL/api/balance/$ADDRESS?chain=ethereum" \
  -H "x-api-key: $WALLETSUITE_API_KEY"
# 400 = validation · 401/403 = auth / plan · 429 = rate limit · 5xx = retry

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

End-to-End Token Transfer — complete signing and broadcast flow
Integration Samples — 20+ code examples
SDK Error Handling — detailed error patterns
API Reference — full REST API with interactive playground

Get Started

Use Case Guides

Prerequisites

Add Wallet Operations to Your Application

What Your Application Will Be Able to Do

Prerequisites

Step 1 — Install

Step 2 — Initialize the Client

Step 3 — Query a Balance

Step 4 — Get a Price

Step 5 — Estimate Fees

Step 6 — Prepare a Transfer

Token Transfers

Error Handling

Architecture Recommendation

Next Steps

​What Your Application Will Be Able to Do

​Prerequisites

​Step 1 — Install

​Step 2 — Initialize the Client

​Step 3 — Query a Balance

​Step 4 — Get a Price

​Step 5 — Estimate Fees

​Step 6 — Prepare a Transfer

​Token Transfers

​Error Handling

​Architecture Recommendation

​Next Steps

What Your Application Will Be Able to Do

Prerequisites

Step 1 — Install

Step 2 — Initialize the Client

Step 3 — Query a Balance

Step 4 — Get a Price

Step 5 — Estimate Fees

Step 6 — Prepare a Transfer

Token Transfers

Error Handling

Architecture Recommendation

Next Steps