# INTMAX Client SDK

## **Overview**

The INTMAX Client SDK provides a secure, high-performance interface for interacting with the INTMAX network. 

Built with WebAssembly for optimized cryptographic processing, the SDK abstracts complex blockchain operations into a developer-friendly API that handles the complete transaction lifecycle—from creation and signing to broadcasting. 

This documentation covers the SDK's core functionality, available functions, and interface specifications to help developers build secure blockchain wallet integrations with confidence.

### **Latest Version**: `1.5.2`

**Check out the INTMAX Client SDK on GitHub**

<a href="https://github.com/InternetMaximalism/intmax2-client-sdk" class="button secondary" data-icon="square-github">View GitHub</a>

***

**INTMAX Client SDK Examples**

<a href="https://github.com/InternetMaximalism/intmax2-client-sdk/tree/main/examples" class="button secondary" data-icon="square-github">View Examples on GitHub</a> <a href="https://github.com/InternetMaximalism/intmax2-e2e" class="button secondary" data-icon="square-github">View E2E Examples on Github</a>

***

**INTMAX Client SDK Integration Guide**

{% content-ref url="/pages/ZpB4KMveGxW3mfOjT588" %}
[Integration Guide](/intmax-developers-hub/intmax-network-tools/intmax-client-sdk/integration-guide.md)
{% endcontent-ref %}

***

## Architecture <a href="#architecture" id="architecture"></a>

This section outlines the core workflows supported by the INTMAX network: **Deposit**, **Transfer**, and **Withdrawal**. Each workflow is carefully designed to ensure security, scalability, and seamless interaction between Ethereum mainnet and INTMAX network.

#### Deposit Workflow <a href="#deposit-workflow" id="deposit-workflow"></a>

Transfers assets from the Ethereum mainnet to INTMAX network. A Predicate contract blocks deposits originating from sanctioned addresses, preventing illicit funds from entering INTMAX network. Deposit data is then relayed to the Scroll network via the Scroll Messenger, preserving maximum security throughout the process.

```
Ethereum Mainnet
    │
    ▼
[Deposit Contract (Predicate AML)]
    │
    ▼
[Deposit Analyzer]
    │
    ▼
[L1 Scroll Messenger]
    │
    ▼
[Rollup Contract]
    │   └─ A new deposit block is submitted and verified by the block builder
    ▼
INTMAX Network
```

#### Transfer Workflow <a href="#transfer-workflow" id="transfer-workflow"></a>

A user-signed transaction is packaged as a single transfer and submitted to the Rollup Contract by the Block Builder.

Enables instant, low-cost value transfers within the INTMAX network.

```
INTMAX Network
    │
    ▼
[Transfer]
    │
    ▼
[Block Builder]
    │
    ▼
[Rollup Contract]
    │   └─ A new transfer block is submitted and verified by the block builder
    ▼
INTMAX Network
```

#### Withdrawal Workflow <a href="#withdrawal-workflow" id="withdrawal-workflow"></a>

Returns assets from INTMAX network to Ethereum mainnet without compromising security. Withdrawal requests are batched by the Withdrawal Aggregator and proven on L2. The proof is sent through the L2 Scroll Messenger; the Withdrawal Messenger Relayer then submits it on Ethereum. For ERC-20 and other non-ETH tokens, the Liquidity Contract executes an additional claim step before releasing funds, ensuring smooth cross-chain exits with minimal gas overhead.

```
INTMAX Network
    │
    ▼
[Withdrawal]
    │
    ▼
[Withdrawal Aggregator]
    │
    ▼
[L2 Scroll Messenger]
    │
    ▼
[Withdrawal Messenger Relayer]
    │
    ▼
[Liquidity Contract]
    │   └─ For non-ETH tokens, an additional claim process is required
    ▼
Ethereum Mainnet
```

## Basic Concepts <a href="#basic-concepts" id="basic-concepts"></a>

#### Account System <a href="#account-system" id="account-system"></a>

INTMAX uses a unique address format that differs from Ethereum.

* **Address derivation**

  An INTMAX address is deterministically derived from a given Ethereum address, but the resulting value differs because INTMAX uses its own encoding scheme.
* **Parameter usage**

  | **Operation**                         | **Address to supply** |
  | ------------------------------------- | --------------------- |
  | Deposit                               | INTMAX address        |
  | On-chain transaction (INTMAX network) | INTMAX address        |
  | Withdraw                              | Ethereum address      |
* **Environment scope**

  The derivation is environment-specific: the INTMAX address produced on Mainnet is different from the one produced on the network, even when starting from the same Ethereum address. Always double-check which network you are targeting before submitting transactions.

  **Mainnet**: A 95-character string starting with **i** (lowercase)

  * Example: `i9bX5qzARYR7geR35g4K9972DB8fcWqPjNNgQnoGFViZaTLaSiKUTEd7geR35g4K9972DB8fcWqPjNNgQnoGFViZPctJYmE`

  **Testnet**: A 95-character string starting with **T** (uppercase)

  * Example: `T6ubiG36LmNce6uzcJU3h5JR5FWa72jBBLUGmEPx5VXcFtvXnBB3bqice6uzcJU3h5JR5FWa72jBBLUGmEPx5VXcB3prnCZ`

  ️️ **⚠️ Important:** Be careful not to mix them up. Always verify which type of address is required for the operation you're performing, and ensure you are using the correct environment (Mainnet or Testnet) when deriving and using your INTMAX address.

#### Environment <a href="#environment" id="environment"></a>

INTMAX operates on two separate environments: **Mainnet** and **Testnet**. Even if derived from the same Ethereum address, an INTMAX address will be different between environments. Specify the environment explicitly when initializing the SDK.

```
IntMaxClient.init({ environment: "mainnet" });
IntMaxClient.init({ environment: "testnet" });
```

#### Privacy Model <a href="#privacy-model" id="privacy-model"></a>

The INTMAX privacy model ensures that **only the wallet owner with the private key can view their balance and transaction history**.

* Unlike public blockchains, third parties cannot directly check an address's balance or history.
* Transfer data uses `salt` and `nullifier` values to hide recipient addresses and prevent linking transactions to each other.

#### Batch Size Limits <a href="#batch-size-limits" id="batch-size-limits"></a>

The SDK enforces batch size limits for optimal performance:

* **Transaction broadcasting**: Maximum 63 transactions per `broadcastTransaction` call
* **Data fetching**: Maximum 64 items per internal API request. The SDK automatically handles pagination for high-level APIs like `fetchDeposits()`, `fetchTransfers()`, and `fetchTransactions()`.

For more details, see the;

{% content-ref url="/pages/Uv28sMnOKjhXw8vNigEB" %}
[Batch Size Limits - incomplete](/intmax-developers-hub/intmax-network-tools/intmax-client-sdk/api-reference/batch-size-limits-incomplete.md)
{% endcontent-ref %}

***

## Tips <a href="#tips" id="tips"></a>

#### How to Run a Local Balance Prover <a href="#how-to-run-a-local-balance-prover" id="how-to-run-a-local-balance-prover"></a>

You can set up a local Balance Prover instance and send requests to it.

**1. Clone the Repository**

Clone the `intmax2` repository (branch `main`) from GitHub to your local environment.

```
git clone git@github.com:InternetMaximalism/intmax2.git -b main
```

**2. Navigate to the Balance Prover Directory**

Move into the `balance-prover` directory within the cloned repository.

```
cd intmax2/balance-prover
```

**3. Prepare Environment Configuration**

Create an environment configuration file `.env` based on the provided `.example.env` template.

```
cp -n .example.env .env
```

**4. Start the Balance Prover**

Run the Balance Prover in release mode (`-r`) using Cargo.

```
cargo run -r
```

**5. Change the SDK Config**

Here's how to update the configuration for Browser and NodeJS, respectively.

**5-a. Browser**

To use the private ZKP server hosted at `http://localhost:9001`, you can use the following code:

```
import { IntMaxClient } from "intmax2-client-sdk";

const intMaxClient = IntMaxClient.init({
  environment: "mainnet",
  urls: {
    balance_prover_url: "http://localhost:9001",
    use_private_zkp_server: false,
  },
});
```

Set `use_private_zkp_server` to `false` when running the balance prover locally.

**5-b. NodeJS**

To use the private ZKP server hosted at `http://localhost:9001`, you can use the following code:

```
const intMaxClient = new IntMaxNodeClient({
  environment: "mainnet",
  eth_private_key: process.env.ETH_PRIVATE_KEY,
  l1_rpc_url: process.env.L1_RPC_URL,
  urls: {
    balance_prover_url: "http://localhost:9001",
    use_private_zkp_server: false,
  },
});
```

Set `use_private_zkp_server` to `false` when running the balance prover locally.

## Want to contribute or report an issue? <a href="#want-to-contribute-or-report-an-issue" id="want-to-contribute-or-report-an-issue"></a>

We welcome contributions and feedback!

Please feel free to open an <a href="https://github.com/InternetMaximalism/intmax2-client-sdk/issues" class="button secondary" data-icon="square-github">Issue</a> or submit a<a href="https://github.com/InternetMaximalism/intmax2-client-sdk/pulls" class="button secondary" data-icon="square-github">Pull request</a>on GitHub.

Your support helps improve the INTMAX ecosystem.

***

## References <a href="#references" id="references"></a>

You’ll find links to the Rust code and contract documentation below—please use them as reference material.

#### Smart Contracts <a href="#smart-contracts" id="smart-contracts"></a>

*Documentation for deployed contracts and how to interact with them.*

{% content-ref url="/pages/VOWk0Gxn4Omn8o4ebL84" %}
[Smart Contracts](/intmax-developers-hub/intmax-network/intmax-nodes/smart-contracts.md)
{% endcontent-ref %}

***

#### Rust CLI <a href="#rust-cli" id="rust-cli"></a>

*Command-line interface for interacting with the INTMAX network using Rust.*

<a href="https://github.com/InternetMaximalism/intmax2/tree/main/cli" class="button secondary" data-icon="square-github">View INTMAX CLI on GitHub</a>

***

#### Rust SDK <a href="#rust-sdk" id="rust-sdk"></a>

*The official Rust SDK for interacting with the INTMAX network externally.*

<a href="https://github.com/InternetMaximalism/intmax2/tree/main/client-sdk" class="button secondary" data-icon="square-github">View INTMAX Client SDK on GitHub</a>

***

{% hint style="info" %}
This SDK enables seamless external interaction with the INTMAX network using Rust.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://intmax-general.gitbook.io/intmax-developers-hub/intmax-network-tools/intmax-client-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.