Algorand JavaScript SDK

3.5.2 verified Sun Apr 19 auth: no javascript

algosdk is the official JavaScript library for interacting with the Algorand blockchain network. It provides comprehensive functionalities for account management, transaction creation, signing, and submission, as well as querying blockchain data. Designed for both Node.js (requiring v18.0.0 or higher) and modern browsers, the SDK is actively maintained by Algorand, with frequent releases addressing bugfixes, enhancements, and API updates to align with the latest Algorand protocol specifications. The current stable version is 3.5.2. Version 3.x introduced significant breaking changes compared to v2.x, notably requiring explicit named imports for all functions and classes instead of a single default export or namespace object. It also ships with first-class TypeScript support, requiring TypeScript version 4.2 or higher for optimal usage.

Common errors

error TypeError: algosdk.Algodv2 is not a constructor ↓

cause Attempting to instantiate Algodv2 via a namespace or default import/require object after migrating to v3.x.

fix

Change your import statement to import { Algodv2 } from 'algosdk'; and then use new Algodv2(...) directly.

error ReferenceError: require is not defined ↓

cause Using CommonJS `require()` syntax in an ES module context (`type: 'module'` in package.json or `.mjs` file).

fix

Switch to ES module import syntax: import { SomeSymbol } from 'algosdk';. If you must use CommonJS, ensure your environment is configured for CJS (e.g., using .cjs extension or type: 'commonjs').

error Property 'status' does not exist on type 'Algodv2' or similar TypeScript errors related to missing methods/properties. ↓

cause Using an outdated TypeScript version (older than 4.2) that may not correctly process the SDK's bundled type definitions.

fix

Update your TypeScript compiler to version 4.2 or higher. Ensure algosdk is correctly installed and its types are being picked up by your tsconfig.json.

Warnings

breaking Version 3.x introduces significant breaking changes from v2.x. The most notable change is the shift from a default export/namespace object to mandatory named imports for all classes and functions. Code relying on `algosdk.Algodv2` or `const algosdk = require('algosdk');` will break. ↓

fix Consult the `v2_TO_v3_MIGRATION_GUIDE.md` in the GitHub repository. Update all imports to use named imports, e.g., `import { Algodv2 } from 'algosdk';`.

deprecated The v2.x series of algosdk is in maintenance mode and will reach End-of-Life at the end of March 2025. No new features are being added, and after March 2025, no further updates (including security fixes) will be provided. ↓

fix Migrate your application to algosdk v3.x or later immediately to ensure continued support, security updates, and access to new Algorand features. Refer to the migration guide for assistance.

gotcha This package requires Node.js version 18.0.0 or higher. Running it with older Node.js versions may lead to unexpected errors or module resolution issues, especially concerning ESM compatibility. ↓

fix Ensure your development and deployment environments are running Node.js v18.0.0 or a newer compatible version.

gotcha While algosdk ships with TypeScript types, proper usage requires TypeScript version 4.2 or higher. Using an older TypeScript compiler might result in type errors or incorrect type inference. ↓

fix Upgrade your project's TypeScript dependency to version 4.2 or higher.

Install

npm install algosdk

yarn add algosdk

pnpm add algosdk

Imports

Algodv2
wrong
```
import algosdk from 'algosdk';
const client = new algosdk.Algodv2(...);
```
correct
```
import { Algodv2 } from 'algosdk';
```
Since v3, the library requires named imports; a default import or namespace object no longer works for accessing primary classes like Algodv2.

makePaymentTxnWithSuggestedParams

wrong

const algosdk = require('algosdk');
const txn = algosdk.makePaymentTxnWithSuggestedParams(...);

correct

import { makePaymentTxnWithSuggestedParams } from 'algosdk';

All utility functions must be imported by name in v3. CommonJS `require` is also not the recommended import style.

Transaction
wrong
```
import * as algosdk from 'algosdk';
const txn = new algosdk.Transaction(...);
```
correct
```
import { Transaction } from 'algosdk';
```
Classes like Transaction, which are used for building complex objects, are also exclusively available via named imports in v3.

Quickstart

Initializes the Algorand SDK client, fetches node status, retrieves suggested transaction parameters, and optionally fetches account information.

import { Algodv2, modelsv2 } from 'algosdk';

// Configure your Algorand client using environment variables
const token = process.env.ALGORAND_ALGOD_TOKEN ?? ''; // Algod API token
const server = process.env.ALGORAND_ALGOD_SERVER ?? 'http://127.0.0.1'; // Algod server address
const port = process.env.ALGORAND_ALGOD_PORT ? parseInt(process.env.ALGORAND_ALGOD_PORT, 10) : 4001; // Algod port

const client = new Algodv2(token, server, port);

(async () => {
  try {
    console.log("Fetching Algorand node status...");
    // Fetch and log the current Algorand node status
    const status: modelsv2.NodeStatusResponse = await client.status().do();
    console.log("Node last round:", status.lastRound);

    // Fetch and log suggested transaction parameters, essential for building transactions
    const suggestedParams = await client.getTransactionParams().do();
    console.log("Suggested transaction parameters:", suggestedParams);

    // Example: Fetch account information
    // Replace 'YOUR_ALGORAND_ADDRESS_HERE' with a valid Algorand address or set via environment variable
    const testAddress = process.env.ALGORAND_TEST_ACCOUNT_ADDRESS ?? 'YOUR_ALGORAND_ADDRESS_HERE'; 
    if (testAddress !== 'YOUR_ALGORAND_ADDRESS_HERE') {
      console.log(`\nFetching account info for ${testAddress}...`);
      const accountInfo = await client.accountInformation(testAddress).do();
      console.log("Account balance (microAlgos):", accountInfo.amount);
      console.log("Account assets:", accountInfo.assets?.length || 0);
    } else {
      console.warn("\nSkipping account info fetch. Set ALGORAND_TEST_ACCOUNT_ADDRESS to a valid address to enable this.");
    }
  } catch (e) {
    console.error("An error occurred during quickstart execution:", e);
  }
})();