Clients and SDK integration

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

A small explorer client

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 local docs origins are allowed by default. Try the request in the playground →

Handle the response

Before using the result:

• Validate the response envelope and required fields.
• Keep decimal amounts as strings or exact integers.
• Check meta.mode and label sample data.
• 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.

Transaction builders

Heartwood’s current Rust crypto crate contains builders for its retained baseline transaction types. These application examples do not establish a published general-purpose transaction SDK.

Planned SDKs

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

Language	Access to the core
Rust	Native
JavaScript and TypeScript	WebAssembly, with a thin TypeScript wrapper
Go	A 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.