Nimb SDK

A comprehensive TypeScript/JavaScript SDK for interacting with the Nimb wallet API. Supports wallet creation, balance queries, transactions, smart contract compilation, deployment, and gasless transactions via relayer.

✨ Features

• ✅ Universal Compatibility - Works in both browser and Node.js environments
• ✅ TypeScript & JavaScript - Full TypeScript support with type definitions
• ✅ Framework Support - React hooks and Angular service included
• ✅ All API Endpoints - Complete coverage of all Nimb API endpoints
• ✅ Error Handling - Comprehensive error handling
• ✅ Type Safe - Full TypeScript type definitions

Installation

npm install nimb-sdk

For Node.js (Server-side)

If you're using the SDK in Node.js and need to compile Solidity files, you'll also need:

npm install form-data

Note: form-data is an optional dependency. It's only needed for the compileSolCode method in Node.js environments. In browsers, the native FormData API is used automatically.

Environment Support

✅ Browser (Client-side)

• Works in all modern browsers
• Uses native FormData API for file uploads
• Perfect for React, Angular, Vue, or vanilla JS projects
• No additional dependencies needed

✅ Node.js (Server-side)

• Works in Node.js 14+ environments
• Uses form-data package for file uploads (optional dependency)
• Perfect for backend services, scripts, and serverless functions

✅ Both JavaScript and TypeScript

• Full TypeScript support with complete type definitions
• Works with plain JavaScript (ES6+)
• Type-safe API calls with IntelliSense support

Quick Start

JavaScript/TypeScript

import { NimbSDK } from "nimb-sdk";

// Initialize the SDK with API key and base URL
// baseUrl can be different for sandbox or production environments
const sdk = new NimbSDK({
  apiKey: "your-api-key-here", // Required: Your API key
  baseUrl: "https://api.nimb.com", // Required: API base URL (sandbox or production)
});

// Create a wallet
const wallet = await sdk.createWallet({
  walletType: "CUSTODIAL",
  chainId: 11155111,
  userId: "304b32a9-2b76-4b30-bf01-1c6e25a2dda3",
});

console.log("Wallet Address:", wallet.result.address);

Environment Configuration

The SDK requires both apiKey and baseUrl to be configured during initialization. This allows you to easily switch between sandbox and production environments:

// Production Environment
const productionSDK = new NimbSDK({
  apiKey: "your-production-api-key",
  baseUrl: "https://api.nimb.com", // Production URL
});

// Sandbox Environment
const sandboxSDK = new NimbSDK({
  apiKey: "your-sandbox-api-key",
  baseUrl: "https://sandbox-api.nimb.com", // Sandbox URL
});

// Local Development
const localSDK = new NimbSDK({
  apiKey: "your-local-api-key",
  baseUrl: "http://localhost:3000", // Local development URL
});

Note: Both apiKey and baseUrl are required. The baseUrl defaults to http://localhost:3000 if not provided, but it's recommended to always specify it explicitly for clarity.

API Reference

Create Wallet

Create a new custodial or non-custodial wallet.

const wallet = await sdk.createWallet({
  walletType: "CUSTODIAL", // or 'NON_CUSTODIAL'
  chainId: 11155111,
  userId: "your-user-id",
});

// Response:
// {
//   status: 200,
//   message: "success",
//   result: {
//     address: "0x...",
//     balance: "0.0",
//     publicKey: "0x..."
//   }
// }

Get Balance

Get native token balance or ERC20 token balance.

Native Token Balance

const balance = await sdk.getBalance({
  chainId: 11155111,
  address: "0x0aA6eB8B6f8f2922c8193e594812B511FC230717",
});

// Response: "0.0" (string)

ERC20 Token Balance

const balance = await sdk.getBalance({
  chainId: 11155111,
  address: "0x0aA6eB8B6f8f2922c8193e594812B511FC230717",
  smartContractAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
});

// Response:
// {
//   native: "0.01",
//   token: {
//     balance: "0.0",
//     symbol: "UNKNOWN",
//     name: null,
//     contractAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
//     decimals: 18
//   }
// }

Send Transaction

Send native token or ERC20 token transaction.

Send Native Token

const tx = await sdk.sendTransaction({
  chainId: 11155111,
  to: "0xe3240ff264bef46e9e87e056f4c8098a4aec5927",
  amount: 0.01,
  address: "0x113bddc9D755246851a0E1791B7fb3865b0B502C",
});

console.log("Transaction Hash:", tx.result.hash);

Send ERC20 Token

const tx = await sdk.sendTransaction({
  chainId: 11155111,
  to: "0xe3240ff264bef46e9e87e056f4c8098a4aec5927",
  amount: 0.01,
  address: "0x113bddc9D755246851a0E1791B7fb3865b0B502C",
  smartContractAddress: "0x113bddc9D755246851a0E1791B7fb3865b0B502C",
});

Check Transaction Status

Check the status of a transaction.

const status = await sdk.checkTransactionStatus({
  transactionHash:
    "0x573a115584fdf63397a9e91a8d06f28dfb69477fb345c8d2c78c6735dee4a191",
  chainId: 11155111,
});

console.log("Status:", status.result.status); // "SUCCESS"
console.log("Block Number:", status.result.blockNumber);

Compile Solidity Code

Compile a Solidity file. Works in both browser and Node.js environments.

Node.js (Server-side)

// Using file path
const compiled = await sdk.compileSolCode("/path/to/contract.sol");

// Or using Buffer
const fs = require("fs");
const fileBuffer = fs.readFileSync("/path/to/contract.sol");
const compiled = await sdk.compileSolCode(fileBuffer, "contract.sol");

console.log("ABI:", compiled.result.abi);
console.log("Bytecode:", compiled.result.bytecode);
console.log("Contract Name:", compiled.result.contractName);

Browser (Client-side)

// Using File input from HTML
const fileInput = document.querySelector(
  'input[type="file"]'
) as HTMLInputElement;
const file = fileInput.files?.[0];
if (file) {
  const compiled = await sdk.compileSolCode(file);
  console.log("ABI:", compiled.result.abi);
}

// Or using File/Blob object
const blob = new Blob([solidityCode], { type: "text/plain" });
const compiled = await sdk.compileSolCode(blob, "contract.sol");

Deploy Contract

Deploy a smart contract.

const deployment = await sdk.deployContract({
  address: '0x113bddc9D755246851a0E1791B7fb3865b0B502C',
  chainId: 11155111,
  abi: [...], // Contract ABI array
  bytecode: '0x608060405234801561000f575f5ffd5b...',
  contractName: 'MintableToken',
  constructorArgs: ['x', 'SYM', 18, '1000000000000000000000', '10000000000000000000000'], // Optional
});

console.log('Contract Address:', deployment.result.contractAddress);
console.log('Transaction Hash:', deployment.result.transactionHash);

Write Transaction (Gasless)

Execute a write transaction on a smart contract (gasless).

const result = await sdk.writeTransaction({
  contractAddress: '0xd80E071f5d58Cb5Cc20a1502AD707F1C3DEA935C',
  functionName: 'increment',
  params: [],
  abi: [...], // Contract ABI array
  fromAddress: '0x113bddc9D755246851a0E1791B7fb3865b0B502C',
  chainId: 11155111,
});

console.log('Transaction Hash:', result.result.txHash);
console.log('Is Gasless:', result.result.isGasless); // true

Relayer Send Transaction (Gasless)

Send a transaction via relayer (gasless).

// Send native token (gasless)
const result = await sdk.relayerSendTransaction({
  fromAddress: "0x113bddc9D755246851a0E1791B7fb3865b0B502C",
  to: "0xc1cca3d4225cff920a22ca937230cec06f28f9bf",
  amount: 1,
  chainId: 11155111,
});

// Send ERC20 token (gasless)
const result = await sdk.relayerSendTransaction({
  fromAddress: "0x113bddc9D755246851a0E1791B7fb3865b0B502C",
  to: "0xc1cca3d4225cff920a22ca937230cec06f28f9bf",
  amount: 1,
  chainId: 11155111,
  tokenAddress: "0xcb4139F276e80Ec5Dd9D1E19c316829A4b243bD2",
});

console.log("Transaction Hash:", result.result.txHash);
console.log("Explorer URL:", result.result.explorerUrl);

Usage Examples

Browser (Client-side) Example

// In a browser environment (React, Angular, Vue, or vanilla JS)
import { NimbSDK } from "nimb-sdk";

// Initialize with API key and base URL
const sdk = new NimbSDK({
  apiKey: "your-api-key", // Your API key
  baseUrl: "https://api.nimb.com", // Production or sandbox URL
});

// All methods work in browser
const wallet = await sdk.createWallet({
  walletType: "CUSTODIAL",
  chainId: 11155111,
  userId: "user-123",
});

Node.js (Server-side) Example

// In a Node.js environment
import { NimbSDK } from "nimb-sdk";

// Initialize with API key and base URL
const sdk = new NimbSDK({
  apiKey: "your-api-key", // Your API key
  baseUrl: "https://api.nimb.com", // Production or sandbox URL
});

// All methods work in Node.js
const wallet = await sdk.createWallet({
  walletType: "CUSTODIAL",
  chainId: 11155111,
  userId: "user-123",
});

Environment-based Configuration

You can easily switch between environments using environment variables:

import { NimbSDK } from "nimb-sdk";

const sdk = new NimbSDK({
  apiKey: process.env.NIMB_API_KEY || "your-api-key",
  baseUrl: process.env.NIMB_API_URL || "https://api.nimb.com",
});

Or create environment-specific instances:

// config.ts
export const getSDK = (environment: "sandbox" | "production") => {
  const configs = {
    sandbox: {
      apiKey: "sandbox-api-key",
      baseUrl: "https://sandbox-api.nimb.com",
    },
    production: {
      apiKey: "production-api-key",
      baseUrl: "https://api.nimb.com",
    },
  };

  return new NimbSDK(configs[environment]);
};

// Usage
const sdk = getSDK(
  process.env.NODE_ENV === "production" ? "production" : "sandbox"
);

React Integration

For React projects, use the provided hook:

import { useNimbSDK } from "nimb-sdk/react";
import { useState } from "react";

function WalletComponent() {
  const { createWallet, getBalance, loading, error } = useNimbSDK({
    apiKey: "your-api-key", // Your API key
    baseUrl: "https://api.nimb.com", // Production or sandbox URL
  });

  const handleCreateWallet = async () => {
    try {
      const wallet = await createWallet({
        walletType: "CUSTODIAL",
        chainId: 11155111,
        userId: "user-123",
      });
      console.log("Wallet created:", wallet.result.address);
    } catch (err) {
      console.error("Error:", err);
    }
  };

  return (
    <div>
      <button onClick={handleCreateWallet} disabled={loading}>
        {loading ? "Creating..." : "Create Wallet"}
      </button>
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

Angular Integration

For Angular projects, use the provided service:

import { Component, OnInit } from "@angular/core";
import { NimbSDKService } from "nimb-sdk/angular";

@Component({
  selector: "app-wallet",
  templateUrl: "./wallet.component.html",
})
export class WalletComponent implements OnInit {
  private nimbService: NimbSDKService;

  constructor() {
    this.nimbService = new NimbSDKService({
      apiKey: "your-api-key", // Your API key
      baseUrl: "https://api.nimb.com", // Production or sandbox URL
    });
  }

  ngOnInit() {
    this.createWallet();
  }

  createWallet() {
    this.nimbService
      .createWallet({
        walletType: "CUSTODIAL",
        chainId: 11155111,
        userId: "user-123",
      })
      .subscribe({
        next: (wallet) => {
          console.log("Wallet created:", wallet.result.address);
        },
        error: (err) => {
          console.error("Error:", err);
        },
      });
  }
}

Error Handling

All methods throw errors that can be caught:

try {
  const wallet = await sdk.createWallet({
    walletType: "CUSTODIAL",
    chainId: 11155111,
    userId: "user-123",
  });
} catch (error) {
  if (error instanceof Error) {
    console.error("API Error:", error.message);
  }
}

TypeScript Support

The SDK is fully typed. Import types as needed:

import {
  CreateWalletRequest,
  CreateWalletResponse,
  GetBalanceRequest,
  SendTransactionRequest,
  // ... other types
} from "nimb-sdk";

License

MIT

Support

For issues and questions, please open an issue on the repository.