ADAMANT JavaScript API

adamant-api is the TypeScript/Node.js SDK for the ADAMANT blockchain. It provides resilient ADM node access, account and transaction primitives, encrypted messaging, WebSocket subscriptions, and deterministic helpers for supported external wallets.

📚 Documentation: js.docs.adamant.im

Features

• Automatic ADM node health checks, retries, failover, and height-aware node selection
• Typed blockchain API requests and response DTOs
• ADM passphrase hashing, keypair and address derivation
• Message encryption and decryption
• Transaction construction, hashing, signing, and ID calculation
• WebSocket subscriptions for incoming transactions
• Optional BTC, ETH, DASH, and DOGE wallet derivation and address validation
• Pinned, reproducible schema metadata from adamant-schema
• Pinned, reproducible coin metadata from adamant-wallets

Requirements

• Node.js 22 or newer
• npm, pnpm, or another package manager supported by your project

Installation

npm install adamant-api

ADM API usage

The package root and adamant-api/adm expose ADM functionality and shared metadata. Importing either entry point does not load coin-specific implementations.

import {AdamantApi} from 'adamant-api';

const api = new AdamantApi({
  nodes: [
    'http://localhost:36666',
    'https://endless.adamant.im',
    'https://clown.adamant.im',
    'https://lake.adamant.im',
  ],
  checkHealthAtStartup: true,
  minVersion: '0.8.0',
});

api.onReady(async () => {
  const response = await api.getBlocks();

  if (response.success) {
    console.log(response.blocks);
  } else {
    console.error(response.errorMessage);
  }
});

minVersion is inclusive. During health checks, nodes below this ADAMANT Node version are reported and excluded from API and WebSocket selection.

CommonJS remains supported:

const {AdamantApi} = require('adamant-api');

Do not place a passphrase, private key, decrypted message, or sensitive token in logs.

Modular imports

Use the narrowest entry point that fits the task:

For example:

import {btc} from 'adamant-api/coins/btc';

const wallet = btc.keys('your twelve-word ADM passphrase');
const valid = btc.isValidAddress(wallet.address ?? '');

The external coin scope is intentionally limited to metadata, deterministic key/address derivation, and address validation. Balance lookup, history, fees, external-chain signing, and broadcasting are not part of this SDK surface.

Wallet metadata

import {coinMetadata, walletMetadataSource} from 'adamant-api/metadata';

console.log(coinMetadata.ADM.decimals); // 8
console.log(walletMetadataSource.revision);

Metadata is generated from a pinned adamant-wallets revision so updates are deterministic and reviewable:

pnpm metadata:check
pnpm metadata:sync

Generated ADAMANT API DTOs follow the same pinned workflow for adamant-schema:

pnpm api-types:check
pnpm api-types:sync

Reliability

AdamantApi checks configured nodes through the node status endpoint and selects a live node at an actual blockchain height. Safe GET failures can be retried against another healthy node. POST requests are retried only when no HTTP response was received; an explicitly rejected POST is never replayed automatically, avoiding pointless retries for validation errors.

Applications should provide several independently operated HTTPS nodes and handle returned errors. Malformed responses, timeouts, and partial network outages must not be treated as successful requests.

Logging can be disabled only with logLevel: 'none'. Supported thresholds are error, warn, info, log, and debug; unknown application-specific names such as trace fall back to log instead of disabling SDK output.

Error handling

Expected validation, node, and transport failures resolve to a single result shape: {success: false, errorMessage: string}. Check response.success before reading response data. Node-specific error and message fields are normalized to errorMessage; application code does not need to check multiple error fields. See the error-handling guide.

Development

corepack enable
pnpm install
pnpm build
pnpm test
pnpm test:package
pnpm lint

pnpm test:package packs the current working tree and installs its tarball into a temporary consumer project. It verifies CommonJS and ESM imports, package subpaths, runtime helpers, and TypeScript declarations without using the published npm version. Edit scripts/package-test/consumer.ts to extend the consumer scenario.

Run the deterministic transaction ID example directly on Node.js 22 or newer:

pnpm build
node --experimental-strip-types examples/getId/index.mts

See CONTRIBUTING.md for repository conventions, testing expectations, generated files, and pull request guidance.

Links

• ADAMANT website
• ADAMANT documentation
• ADAMANT Improvement Proposals
• ADAMANT Node
• ADAMANT API schema
• ADAMANT schema source
• ADAMANT wallet metadata
• ADAMANT blockchain explorer
• Package documentation and examples
• Changelog and releases
• Issues and feature requests

License

GPL-3.0