How-To Guides

Practical examples for the most common tasks when building on DecentralChain. These use the transactions and node-api-js packages — see Client Libraries and SDK for the full package list, including which of these names the monorepo is mid-renaming.

Both packages are ESM-only and require Node.js 24+.

All examples on this page target the public Testnet: node https://testnet-node.decentralchain.io, chain ID ! (passed as chainId: '!' to the transaction builders) and Testnet addresses starting with 31. For Mainnet, use a Mainnet node and chainId: '?'.

Build, Sign, and Broadcast a Transaction

This example builds a Transfer transaction, signs it with a seed phrase, and broadcasts it. broadcast() is exported by @decentralchain/transactions itself — you don’t need node-api just to send a transaction.

npm install @decentralchain/transactions

import { transfer, broadcast } from '@decentralchain/transactions';

const seed = 'your secret seed phrase here';

// Build and sign a Transfer transaction
const signedTx = transfer(
  {
    recipient: '31LAqgqVTLySNCPuYqgLAYhcgS76wvBaLr9', // recipient address or alias (Testnet)
    amount: 100_000_000,                               // 1 DCC (8 decimals, i.e. 10^8 Decentralites)
    chainId: '!',                                      // Testnet chain ID
  },
  seed,
);

// Broadcast it
const result = await broadcast(signedTx, 'https://testnet-node.decentralchain.io');
console.log('Transaction ID:', result.id);

A raw seed phrase should only ever be used server-side, or in scripts/tests you control. Never ask a user for their seed phrase in a dApp — see Wallet Integration for the browser-safe flow.

Every other transaction type has a matching builder exported from @decentralchain/transactions: issue(), reissue(), burn(), lease(), cancelLease(), massTransfer(), data(), setScript(), setAssetScript(), invokeScript(), exchange().

Issuing a Token

To issue a new token, use issue() the same way:

import { issue, broadcast } from '@decentralchain/transactions';

const seed = 'your secret seed phrase here';

const signedTx = issue(
  {
    name: 'MyToken',
    description: 'A token issued on DecentralChain',
    quantity: 1_000_000,
    decimals: 2,
    reissuable: true,
    chainId: '!', // Testnet chain ID
  },
  seed,
);

await broadcast(signedTx, 'https://testnet-node.decentralchain.io');

See Token (Asset) for the full meaning of each issue parameter.

Reading Blockchain Data

Use node-api-js to query account balances and other node state without running your own indexer. create(nodeUrl) returns a client namespaced by API area (addresses, assets, blocks, transactions, leasing, and more):

npm install @decentralchain/node-api-js@2.0.1

import { create } from '@decentralchain/node-api-js';

const api = create('https://testnet-node.decentralchain.io');

const { balance } = await api.addresses.fetchBalance('31LAqgqVTLySNCPuYqgLAYhcgS76wvBaLr9');
console.log('DCC balance (in Decentralites):', balance);

const { height } = await api.blocks.fetchHeight();
console.log('Current height:', height);

Note

The monorepo is renaming this package to @decentralchain/node-api, but that name isn’t published yet — install node-api-js (above) until it is.

For richer historical queries (asset search, DEX order history, aggregated transaction data) use data-service-client-js against the data service API instead of querying a node directly — see Data Service API.

Signing with a Ledger Hardware Wallet

@decentralchain/ledger talks to a Ledger Nano S or X running the DCC application. It derives public keys and signs on the device, so the private key never leaves the hardware. It supports WebUSB, Web Bluetooth and Node HID transports, and you install a Ledger transport package alongside it:

npm install @decentralchain/ledger @ledgerhq/hw-transport-webusb

The package README documents the current DCCLedger API for connecting, reading the user’s address and signing a transaction; start from its Quick Start.