Skip to content

Getting Started

This section introduces Koinos, the networks and accounts you will use, and the main tools available to users and developers.

Choose a starting point

Read a KOIN balance

This Node.js 20+ example reads a balance from the Koinos mainnet REST API. It does not create a wallet, request a private key, or submit a transaction.

index.js
export function balanceUrl(address) {
  const account = encodeURIComponent(address);
  return (
    `${MAINNET_REST_URL}/v1/account/${account}/balance/` +
    KOIN_CONTRACT_ID
  );
}

export async function readKoinBalance(address, fetchImpl = fetch) {
  const response = await fetchImpl(balanceUrl(address), {
    headers: {
      accept: "application/json",
      "user-agent": "koinos-docs-example/1.0",
    },
  });
  if (!response.ok) {
    throw new Error(`Koinos REST API returned HTTP ${response.status}`);
  }

  const payload = await response.json();
  if (typeof payload.value !== "string") {
    throw new Error("Koinos REST API response has no string balance value");
  }
  return payload.value;
}

async function main() {
  const address = process.argv[2] ?? DEFAULT_PUBLIC_ADDRESS;
  const balance = await readKoinBalance(address);
  console.log(`${address}: ${balance} KOIN`);
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main().catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
  });
}

View complete file · Run example

The hosted example uses a public address by default. When running the complete file locally, you can pass any valid public address:

node index.js YOUR_KOINOS_ADDRESS

Never paste a private key into this example

Reading a balance requires only a public address. A private key or recovery phrase is not needed and must never be shared with a website, tutorial, or support account.

What the example does

  • Node's fetch function calls the Koinos REST API.
  • The URL identifies both the public account and the mainnet KOIN contract.
  • The REST response returns the balance as a decimal string, so the example does not introduce floating-point rounding.

The current mainnet KOIN contract can also be checked through the Koinos REST API.

Core concepts

Concept What it means
KOIN The native token of Koinos
Mana A regenerating resource used instead of a per-transaction fee
Account An on-chain identity identified by a Koinos address
Wallet Software that stores or accesses keys and requests signatures
Mainnet The production network where assets can have real value
Testnet A resettable network for development and testing
Smart contract WebAssembly code executed by the Koinos virtual machine

Official entry points

Next step

If Koinos is new to you, continue with What is Koinos?. If you are ready to configure a development environment, open the Tooling Overview.