Skip to main content
The IotaClient class provides a connection to the JSON-RPC Server and should be used for all read-only operations and transaction execution.

​
Basic Setup

import { getFullnodeUrl, IotaClient } from '@iota/iota-sdk/client';

// Create a client connected to devnet
const client = new IotaClient({ url: getFullnodeUrl('devnet') });

​
Network URLs

The SDK provides helper functions to get default network URLs: 
import { getFullnodeUrl } from '@iota/iota-sdk/client';

// Default network URLs:
const localnet = getFullnodeUrl('localnet');  // http://127.0.0.1:9000
const devnet = getFullnodeUrl('devnet');      // https://api.devnet.iota.cafe

​
Connection Options

Connect to the IOTA Devnet for testing:
import { getFullnodeUrl, IotaClient } from '@iota/iota-sdk/client';

const client = new IotaClient({ url: getFullnodeUrl('devnet') });

​
Client Configuration

The IotaClient accepts a configuration object with the following options: 
interface IotaClientOptions {
  url: string;                    // RPC endpoint URL
  transport?: IotaTransport;      // Custom transport (optional)
}

​
Using Custom Transport

You can provide a custom transport implementation: 
import { IotaClient, IotaHTTPTransport } from '@iota/iota-sdk/client';

const transport = new IotaHTTPTransport({
  url: 'https://api.devnet.iota.cafe',
  // Additional transport options
});

const client = new IotaClient({ transport });

​
Client Methods Overview

The IotaClient provides methods for:

​
Querying Data

  • getObject() - Fetch object details
  • getOwnedObjects() - Get objects owned by an address
  • getCoins() - Fetch coins owned by an address
  • getBalance() - Get coin balance for an address
  • getTransaction() - Fetch transaction details

​
Transaction Execution

  • signAndExecuteTransaction() - Sign and execute a transaction
  • dryRunTransactionBlock() - Simulate transaction execution
  • devInspectTransactionBlock() - Inspect transaction effects

​
Network Information

  • getCheckpoint() - Get checkpoint data
  • getProtocolConfig() - Get protocol configuration
  • getChainIdentifier() - Get chain identifier

​
Move Operations

  • getMoveFunctionArgTypes() - Get Move function argument types
  • getNormalizedMoveFunction() - Get normalized Move function
  • getNormalizedMoveModule() - Get normalized Move module

​
Example: Reading Account Data

import { getFullnodeUrl, IotaClient } from '@iota/iota-sdk/client';

const client = new IotaClient({ url: getFullnodeUrl('testnet') });

const address = '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231';

// Get all coins owned by the address
const coins = await client.getCoins({ owner: address });

// Get balance for default coin type (IOTA)
const balance = await client.getBalance({ owner: address });

// Get balance for a specific coin type
const usdcBalance = await client.getBalance({
  owner: address,
  coinType: '0x65b0553a591d7b13376e03a408e112c706dc0909a79080c810b93b06f922c458::usdc::USDC',
});

// Get all owned objects
const objects = await client.getOwnedObjects({ owner: address });

console.log('Coins:', coins);
console.log('IOTA Balance:', balance);
console.log('USDC Balance:', usdcBalance);
console.log('Objects:', objects);

​
Example: Executing Transactions

import { getFullnodeUrl, IotaClient } from '@iota/iota-sdk/client';
import { Ed25519Keypair } from '@iota/iota-sdk/keypairs/ed25519';
import { Transaction } from '@iota/iota-sdk/transactions';

const client = new IotaClient({ url: getFullnodeUrl('testnet') });
const keypair = new Ed25519Keypair();

// Create a transaction
const tx = new Transaction();
const [coin] = tx.splitCoins(tx.gas, [1000]);
tx.transferObjects([coin], keypair.getPublicKey().toIotaAddress());

// Sign and execute
const result = await client.signAndExecuteTransaction({
  signer: keypair,
  transaction: tx,
});

console.log('Transaction result:', result);

​
Making Custom RPC Calls

You can invoke any RPC method using the call() method: 
const result = await client.call<CustomReturnType>(
  'custom_rpc_method',
  [param1, param2],
);

​
Error Handling

import { IotaClient } from '@iota/iota-sdk/client';

try {
  const client = new IotaClient({ url: getFullnodeUrl('devnet') });
  const balance = await client.getBalance({ owner: address });
} catch (error) {
  if (error instanceof Error) {
    console.error('Client error:', error.message);
  }
}

​
Best Practices

Create a single IotaClient instance and reuse it throughout your application instead of creating new instances for each request.
// Good
const client = new IotaClient({ url: getFullnodeUrl('devnet') });

// Use the same client for multiple operations
await client.getBalance({ owner: address1 });
await client.getBalance({ owner: address2 });
Always validate addresses before making API calls:
import { isValidIotaAddress, normalizeIotaAddress } from '@iota/iota-sdk/utils';

if (isValidIotaAddress(normalizeIotaAddress(address))) {
  const balance = await client.getBalance({ owner: address });
}
Implement proper error handling for network requests:
try {
  const result = await client.getObject({ id: objectId });
} catch (error) {
  // Handle timeout, network errors, etc.
  console.error('Failed to fetch object:', error);
}

​
Next Steps

Reading Data

Learn how to query blockchain data

Transactions

Build and execute transactions

GraphQL Transport

Use GraphQL for advanced queries

API Reference

Explore the complete API

Build docs developers (and LLMs) love

Get started for freeTalk to us