Algorand JavaScript SDK

Common errors

• 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.

• 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'`).

• 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 npm
• yarn add algosdk yarn
• pnpm add algosdk pnpm

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);
  }
})();