Mina JavaScript SDK

TypeScript/JavaScript SDK for interacting with Mina Protocol nodes via GraphQL. Companion to mina-sdk-python, mina-sdk-go, and mina-sdk-rust.

Features

• Daemon GraphQL client — query node status, accounts, blocks; send payments and delegations
• Typed response objects with a Currency type backed by bigint
• Automatic retry with configurable backoff
• Public executeQuery() for custom GraphQL queries
• Ships ESM + CJS; works on Node 18+

Installation

npm install mina-sdk

Quick Start

import { Currency, MinaClient } from 'mina-sdk';

const client = new MinaClient();

console.log(await client.getSyncStatus()); // "SYNCED"

const account = await client.getAccount('B62q...');
console.log(`Balance: ${account.balance.total} MINA`);

const result = await client.sendPayment({
  sender: 'B62qsender...',
  receiver: 'B62qreceiver...',
  amount: Currency.fromMina('1.5'),
  fee: Currency.fromMina('0.01'),
});
console.log(`Tx hash: ${result.hash}`);

Configuration

import { MinaClient } from 'mina-sdk';

const client = new MinaClient({
  graphqlUri: 'http://127.0.0.1:3085/graphql', // default
  retries: 3,                                   // must be >= 1
  retryDelayMs: 5000,                           // delay between retries
  timeoutMs: 30_000,                            // per-request HTTP timeout
});

Constructor options are validated eagerly — invalid values throw RangeError at construction time.

API Reference

Queries

Method	Returns	Description
getSyncStatus()	string	Node sync status (SYNCED, BOOTSTRAP, etc.)
getDaemonStatus()	DaemonStatus	Comprehensive daemon status
getNetworkId()	string	Network identifier
getAccount(publicKey, tokenId?)	AccountData	Account balance, nonce, delegate
getBestChain(maxLength?)	BlockInfo[]	Recent blocks from the best chain
getPeers()	PeerInfo[]	Connected peers
getPooledUserCommands(publicKey?)	PooledUserCommand[]	Pending transactions
executeQuery(query, variables, name)	T	Run a custom GraphQL query

Mutations

Method	Returns	Description
sendPayment(params)	SendPaymentResult	Send a payment
sendDelegation(params)	SendDelegationResult	Delegate stake
setSnarkWorker(publicKey?)	string | null	Set/unset SNARK worker
setSnarkWorkFee(fee)	string	Set SNARK work fee

Currency

import { Currency } from 'mina-sdk';

const a = Currency.fromMina(10);           // 10 MINA
const b = Currency.fromMina('1.5');        // 1.5 MINA
const c = Currency.fromNanomina(1_000_000_000n); // 1 MINA

console.log(a.add(b).toString()); // "11.500000000"
console.log(a.nanomina);          // 10000000000n
console.log(a.greaterThan(b));    // true
console.log(b.mul(3).toString()); // "4.500000000"

Currency is immutable and stored as a bigint of nanomina, so all arithmetic is exact.

Errors

• GraphQLError — daemon returned an errors array (not retried)
• DaemonConnectionError — transport-level failure after retries attempts
• AccountNotFoundError — getAccount returned a null account
• CurrencyParseError — invalid input to a Currency.from* factory
• CurrencyUnderflowError — Currency.sub would go negative

Custom Queries

const data = await client.executeQuery<{ bestChain: Array<{ stateHash: string }> }>(
  `query { bestChain(maxLength: 1) { stateHash } }`,
  {},
  'best_chain_head',
);
console.log(data.bestChain[0].stateHash);

License

Apache-2.0