sdk

README

Mintlayer Go SDK

A Go SDK for the Mintlayer blockchain.

go get github.com/mintlayer/go-sdk

Requires Go 1.21+. No CGO. The WASM cryptography runtime is embedded in the binary.

---

Documentation

Guide	Description
docs/indexer.md	Full indexer client reference: chain, blocks, transactions, addresses, pools, tokens, orders, statistics
docs/node.md	Full node client reference: chainstate, mempool, P2P, block submission
docs/wallet.md	Full wallet client reference: lifecycle, accounts, balances, transactions
docs/wasm.md	Full WASM client reference: keys, addresses, inputs, outputs, signing, fees
docs/transactions.md	Step-by-step guide to building and signing transactions without the wallet daemon
docs/staking.md	Staking pools and delegations: creation, funding, withdrawal, and read queries
docs/tokens.md	Fungible token and NFT lifecycle: issuance, minting, freezing, authority, manual encoding

---

Overview

The SDK is organised as four independent sub-clients plus a top-level Client that wires them together.

Package	Purpose	Default port
github.com/mintlayer/go-sdk/node	JSON-RPC 2.0 client for the node daemon	3030 (mainnet)
github.com/mintlayer/go-sdk/indexer	REST client for the indexer (api-web-server)	3000
github.com/mintlayer/go-sdk/wallet	JSON-RPC 2.0 client for the wallet daemon	3034 (mainnet)
github.com/mintlayer/go-sdk/wasm	Cryptography & transaction-building via WASM	—

Use the top-level client when you need multiple sub-clients, or import sub-packages directly when you only need one.

---

Quick start

package main

import (
    "context"
    "fmt"
    "log"

    sdk "github.com/mintlayer/go-sdk"
)

func main() {
    client := sdk.New(sdk.Config{
        NodeURL:    "http://127.0.0.1:3030",
        IndexerURL: "http://127.0.0.1:3000",
        WalletURL:  "http://127.0.0.1:3034",
    })

    ctx := context.Background()

    // Query the chain tip from the indexer.
    tip, err := client.Indexer.GetTip(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("chain tip: height=%d id=%s\n", tip.BlockHeight, tip.BlockID)

    // Optionally initialise the embedded WASM cryptography runtime (~400 ms).
    if err := client.InitWASM(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    privKey, err := client.WASM.MakePrivateKey()
    if err != nil {
        log.Fatal(err)
    }
    pubKey, err := client.WASM.PublicKeyFromPrivateKey(privKey)
    if err != nil {
        log.Fatal(err)
    }
    addr, err := client.WASM.PubkeyToPubkeyHashAddress(pubKey, sdk.Mainnet)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("address:", addr)
}

---

Node client (node/)

JSON-RPC 2.0 client for the Mintlayer node daemon. Supports Basic Auth for nodes with authentication enabled.

import "github.com/mintlayer/go-sdk/node"

c := node.New("http://127.0.0.1:3030",
    node.WithBasicAuth("user", "pass"), // optional
    node.WithTimeout(10*time.Second),   // optional
)

ctx := context.Background()

// Chain state
info, err := c.ChainstateInfo(ctx)
height, err := c.BestBlockHeight(ctx)
blockID, err := c.BestBlockID(ctx)

// Look up a block
blockHex, err := c.GetBlock(ctx, blockID)
blockJSON, err := c.GetBlockJSON(ctx, blockID)

// Token / order info
tokenInfo, err := c.TokenInfo(ctx, "ttml1...")
orderInfo, err := c.OrderInfo(ctx, "order1...")

// Mempool
err = c.SubmitTransaction(ctx, signedTxHex, node.TrustPolicyUntrusted)
feeRate, err := c.GetFeeRate(ctx, 1)

// P2P
peerCount, err := c.GetPeerCount(ctx)
peers, err := c.GetConnectedPeers(ctx)

Errors from the daemon are returned as *node.RPCError with a numeric Code and Message.

---

Indexer client (indexer/)

REST client for api-web-server. All paths are relative to /api/v2/.

import "github.com/mintlayer/go-sdk/indexer"

c := indexer.New("http://127.0.0.1:3000",
    indexer.WithTimeout(15*time.Second), // optional
)

ctx := context.Background()

// Chain
tip, err := c.GetTip(ctx)
blockIDAtHeight, err := c.GetBlockIDAtHeight(ctx, 100_000)

// Block
block, err := c.GetBlock(ctx, "00000000...")
txIDs, err := c.GetBlockTransactionIDs(ctx, "00000000...")

// Transaction
tx, err := c.GetTransaction(ctx, "aabbcc...")
txID, err := c.SubmitTransaction(ctx, signedTxHex) // requires --enable-post-routes

// Address
utxos, err := c.GetSpendableUTXOs(ctx, "mxtc1...")
info, err := c.GetAddressInfo(ctx, "mxtc1...")

// Pool / staking
pools, err := c.ListPools(ctx, indexer.PoolListOpts{Sort: "by_pledge"})
pool, err := c.GetPool(ctx, "pool1...")

// Tokens
token, err := c.GetToken(ctx, "ttml1...")
tokens, err := c.FindTokensByTicker(ctx, "MYTOKEN", indexer.PageOpts{Items: 10})

// Orders
orders, err := c.ListOrders(ctx, indexer.PageOpts{Offset: 0, Items: 20})
order, err := c.GetOrder(ctx, "order1...")

// Statistics
stats, err := c.GetCoinStatistics(ctx)

Non-2xx responses are returned as *indexer.HTTPError with a StatusCode field.

---

Wallet client (wallet/)

JSON-RPC 2.0 client for wallet-rpc-daemon. The wallet daemon manages key storage, signing, and broadcasting.

import "github.com/mintlayer/go-sdk/wallet"

c := wallet.New("http://127.0.0.1:3034",
    wallet.WithBasicAuth("user", "pass"), // optional
)

ctx := context.Background()

// Wallet lifecycle
err = c.OpenWallet(ctx, "/path/to/wallet.dat", "")
defer c.CloseWallet(ctx)
err = c.SyncWallet(ctx)

// Accounts and addresses
info, err := c.GetWalletInfo(ctx)
addr, err := c.NewAddress(ctx, 0 /*account*/)
balance, err := c.GetBalance(ctx, 0)

// Send coins (account 0, auto fee)
result, err := c.AddressSend(ctx, wallet.SendParams{
    Account:         0,
    Address:         "mxtc1...",
    Amount:          wallet.Amount{Atoms: "100000000000"}, // 1 ML
    SelectedUtxos:   nil,
    ChangeAddress:   nil,
    Options:         nil,
})
fmt.Println("tx id:", result.TxID)

// Token operations
issueResult, err := c.IssueToken(ctx, wallet.IssueTokenParams{
    Account:            0,
    Ticker:             "MYTOKEN",
    NumberOfDecimals:   2,
    MetadataUri:        "https://example.com/token",
    DestinationAddress: addr,
    TotalSupply:        wallet.TokenTotalSupplyParams{Type: "Lockable"},
    IsFreezable:        "No",
    Options:            nil,
})
mintResult, err := c.MintTokens(ctx, wallet.MintParams{
    Account: 0,
    TokenID: issueResult.TokenID,
    Address: addr,
    Amount:  wallet.Amount{Atoms: "1000"},
    Options: nil,
})

// Staking
err = c.StartStaking(ctx, 0)
pools, err := c.ListOwnedPools(ctx, 0)

// Compose and sign a raw transaction (cold wallet flow)
composed, err := c.ComposeTransaction(ctx, wallet.ComposeParams{...})
signed, err := c.SignRawTransaction(ctx, 0, composed.Hex)
submitResult, err := c.SubmitTransaction(ctx, signed.Hex, false)

---

WASM client (wasm/)

Cryptographic primitives and binary transaction encoding via an embedded WebAssembly module. Initialisation takes ~400 ms; use sync.Once or Client.InitWASM to call it once per process.

import (
    "context"
    mintlayer "github.com/mintlayer/go-sdk/wasm"
)

ctx := context.Background()
c, err := mintlayer.New(ctx)
if err != nil {
    log.Fatal(err)
}
defer c.Close()

// Key derivation (BIP-44 path 44'/mintlayer_coin_type'/0')
mnemonic := "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
accountKey, err := c.MakeDefaultAccountPrivkey(mnemonic, mintlayer.Mainnet)
recvKey, err := c.MakeReceivingAddress(accountKey, 0)
pubKey, err := c.PublicKeyFromPrivateKey(recvKey)
addr, err := c.PubkeyToPubkeyHashAddress(pubKey, mintlayer.Mainnet)

// Transaction building
srcID, err := c.EncodeOutpointSourceId(txIDBytes, mintlayer.SourceTransaction)
input, err := c.EncodeInputForUtxo(srcID, outputIndex)

output, err := c.EncodeOutputTransfer(
    mintlayer.NewAmount("100000000000"), // 1 ML
    destAddr,
    mintlayer.Mainnet,
)

tx, err := c.EncodeTransaction(input, output, 0 /*flags*/)
txID, err := c.GetTransactionID(tx, true)

// Signing
witness, err := c.EncodeWitness(
    mintlayer.SigHashAll,
    recvKey,
    addr,
    tx,
    utxoBytes, // see examples/send-coins for encoding details
    0,         // input index
    mintlayer.TxAdditionalInfo{},
    blockHeight,
    mintlayer.Mainnet,
)
signedTx, err := c.EncodeSignedTransaction(tx, witness)

See examples/send-coins/ for a complete end-to-end transaction flow.

---

Top-level client

sdk.New constructs only the sub-clients whose URL is non-empty.

// Node + WASM only — no wallet or indexer client is created.
client := sdk.New(sdk.Config{
    NodeURL:  "http://127.0.0.1:3030",
    Username: "user",
    Password: "pass",
})

// Call InitWASM before using client.WASM.
if err := client.InitWASM(ctx); err != nil {
    log.Fatal(err)
}
defer client.Close()

Convenience type aliases (sdk.Amount, sdk.Network, sdk.Mainnet, …) are re-exported so callers that only import the top-level package do not need to also import github.com/mintlayer/go-sdk/wasm.

---

Examples

Example	Description
examples/send-coins/	Derive key → fetch UTXOs → build, sign, and submit a transaction
examples/issue-token/	Issue a fungible token and mint an initial supply via the wallet daemon

---

Amounts

All coin and token amounts use the Amount type, which stores the value as a decimal string of atoms — the smallest indivisible unit. 1 ML = 100,000,000,000 atoms (11 decimal places).

one := mintlayer.NewAmount("100000000000") // 1 ML
zero := mintlayer.NewAmountZero()
fmt.Println(one.Atoms()) // "100000000000"

The indexer and wallet clients use their own Amount struct with both Atoms and Decimal fields populated by the server.

---

Networks

Constant	Value	Use
Mainnet	0	Production network
Testnet	1	Public test network
Regtest	2	Local regression testing
Signet	3	Signet

Pass the network constant to any function that derives addresses or encodes transactions.

---

Error handling

• node.RPCError — JSON-RPC error from the node daemon (Code, Message)
• wallet.RPCError — JSON-RPC error from the wallet daemon
• indexer.HTTPError — non-2xx HTTP response from the indexer (StatusCode, Body)
• WASM errors are plain error values with a descriptive message prefixed by mintlayer:.

Documentation

Index

• Constants
• Variables
• type Amount
• type Client
  • func New(cfg Config) *Client
  • func (c *Client) Close() error
  • func (c *Client) InitWASM(ctx context.Context) error
• type Config
• type FreezableToken
• type Network
• type OrderInfo
• type PoolInfo
• type SignatureHashType
• type SourceId
• type TokenUnfreezable
• type TotalSupply
• type TxAdditionalInfo

Constants

const (
	Mainnet = mintlayer.Mainnet
	Testnet = mintlayer.Testnet
	Regtest = mintlayer.Regtest
	Signet  = mintlayer.Signet
)

Network constants.

Variables

var (
	NewAmount     = mintlayer.NewAmount
	NewAmountZero = mintlayer.NewAmountZero
)

Amount constructors.

Types

type Amount

type Amount = mintlayer.Amount

type Client

type Client struct {
	Node    *node.Client
	Indexer *indexer.Client
	Wallet  *wallet.Client
	WASM    *mintlayer.Client // nil until InitWASM
	// contains filtered or unexported fields
}

Client is the top-level Mintlayer SDK client.

Each sub-client field is nil when its corresponding URL was not set in Config. WASM is nil until Client.InitWASM is called.

func New

func New(cfg Config) *Client

New creates a Client, constructing only the sub-clients whose URL is set in cfg.

func (*Client) Close

func (c *Client) Close() error

Close releases WASM resources if Client.InitWASM was called. HTTP sub-clients (Node, Indexer, Wallet) require no teardown.

func (*Client) InitWASM

func (c *Client) InitWASM(ctx context.Context) error

InitWASM initialises the embedded WASM cryptography runtime (~400ms). Subsequent calls are no-ops. Safe for concurrent use.

type Config

type Config struct {
	// NodeURL is the base URL of the Mintlayer node daemon
	// (e.g. "http://127.0.0.1:3030"). Leave empty to skip.
	NodeURL string

	// IndexerURL is the base URL of the indexer (api-web-server)
	// (e.g. "http://127.0.0.1:3000"). Leave empty to skip.
	IndexerURL string

	// WalletURL is the base URL of the wallet RPC daemon
	// (e.g. "http://127.0.0.1:3034"). Leave empty to skip.
	WalletURL string

	// Username and Password are used for HTTP Basic Auth on Node and Wallet.
	Username string
	Password string
}

Config holds the top-level SDK configuration. Only sub-clients whose URL field is non-empty are constructed.

type FreezableToken

type FreezableToken = mintlayer.FreezableToken

type Network

type Network = mintlayer.Network

type OrderInfo

type OrderInfo = mintlayer.OrderInfo

type PoolInfo

type PoolInfo = mintlayer.PoolInfo

type SignatureHashType

type SignatureHashType = mintlayer.SignatureHashType

type SourceId

type SourceId = mintlayer.SourceId

type TokenUnfreezable

type TokenUnfreezable = mintlayer.TokenUnfreezable

type TotalSupply

type TotalSupply = mintlayer.TotalSupply

type TxAdditionalInfo

type TxAdditionalInfo = mintlayer.TxAdditionalInfo