# Clients and SDK integration

> Query the explorer with JavaScript and understand the proposed SDK model.

Source: https://docs.iceroot.com/developers/sdk/

Start with a small HTTP client for the [explorer API](https://docs.iceroot.com/developers/explorer-api/index.md). Use the wallet provider separately for signed login.

## A small explorer client

This example runs in server-side JavaScript:

```js
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 →](https://docs.iceroot.com/developers/rest-api/index.md) Public access also needs the reverse-proxy limits described in the [explorer API guide](https://docs.iceroot.com/developers/explorer-api/index.md#run-the-api).

## Handle the response

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](https://docs.iceroot.com/developers/wallet-provider/index.md). It exposes an approval flow and public proof; it does not hand private keys to the page.

## Transaction builders

The [Rust SDK](https://github.com/iceroot-network/sdk-rust), [TypeScript SDK](https://github.com/iceroot-network/sdk-typescript) and [Go SDK](https://github.com/iceroot-network/sdk-go) 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.

## Mainnet SDK design

The [draft protocol](https://docs.iceroot.com/core/protocol-design/index.md) 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](https://docs.iceroot.com/core/testing/index.md) for the reference-driven approach.
