Skip to content
IceRootDocs

Clients and SDK integration

Start with a small HTTP client for the explorer API. Use the wallet provider separately for signed login.

This example runs in server-side JavaScript:

const origin = 'http://127.0.0.1:3188';
const url = new URL('/api/v1/validators', origin);
url.searchParams.set('status', 'active');
url.searchParams.set('limit', '10');
const response = await fetch(url, {
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) {
throw new Error(`Explorer request failed: ${response.status}`);
}
const result = await response.json();
console.log(result.data, result.meta.mode);

This uses the local API origin for development. Browser clients can connect directly when their origin is listed in the API’s ICEROOT_API_CORS_ORIGINS configuration. The standalone API allows the local docs origins by default; deployment configuration can override them. Try the request in the playground → Public access also needs the reverse-proxy limits described in the explorer API guide.

Before using the result:

  • Validate the response envelope and required fields.
  • Keep decimal amounts as strings or exact integers.
  • Expect meta.mode: "live" and meta.source: "node". Check meta.identity.nethash and freshness. Only label a response as sample data if it explicitly reports mode: "demo".
  • Follow pagination when reading a complete collection.

For signed login, use the browser wallet provider. It exposes an approval flow and public proof; it does not hand private keys to the page.

The Rust SDK, TypeScript SDK and Go SDK are in early development and not yet published to a package registry. Today they support the devnet’s current formats: keys and addresses, transaction builders, signing, and the node API. They do not yet implement the proposed mainnet protocol or its post-quantum signatures. The Go SDK runs the same Rust core, compiled to WebAssembly, in pure Go, and supports the classical devnet only. Each repository’s documentation and release notes list the supported networks and how to install.

Plain message signing refuses text recognized as a website sign-in message, including expired challenges. Use the checked sign-in function: signin::sign in Rust, SignIn.sign in TypeScript or Account.SignSignIn in Go. It checks the requesting page’s origin and the selected account before signing. An integration still using plain message signing must move to that path before adopting this SDK change.

The draft protocol plans one Rust core that implements the encodings, the signing domains, and ML-DSA-65 signing:

LanguageAccess to the core
RustNative
JavaScript and TypeScriptWebAssembly, with a thin TypeScript wrapper
GoA binding that calls the same Rust core

Every supported language therefore runs one implementation of encoding and signing. For other languages, the draft plans published test vectors, so community SDKs can check their results against the same values.

Package names, install commands, and release compatibility must come from the actual SDK release.

Before adapting any SDK, match its transaction bytes, signatures, network configuration, and rejection behavior against the selected Heartwood release. Similar API names are not evidence of wire compatibility.

Read testing and compatibility for the reference-driven approach.