Connect to a Ledger

Install the Minka CLI, connect to a ledger environment, and create your signer — the cryptographic identity that authorizes every operation you perform.

Audience: Developers, Integration Engineers · Read time: 4 min

The Getting Started guides gave you the API shape through a mock server. Now you're connecting to a real ledger — a shared coordination layer where wallets hold real balances, intents move real value, and every operation is cryptographically signed by the participant that authorized it.

This guide walks you through three things: installing the CLI, connecting to a ledger, and creating a signer — the key pair that proves your identity on the ledger. Every guide in this section — Onboard a Merchant, Send a Payment, and Collect a Payment — assumes you've completed these steps.

Prerequisites

Node.js 20.17 or later
npm or yarn package manager

Setup

Install the CLI

The Minka CLI is a single command-line tool that manages your connection to ledgers, creates and manages signers, submits payments, and queries balances. It's how you interact with the ledger from your terminal.

npm install -g @minka/cli

yarn global add @minka/cli

Verify the installation:

minka --version

Connect to the ledger server

A Minka server hosts one or more ledgers. Connecting tells the CLI where to send all subsequent requests. You only need to run this once — the connection persists across terminal sessions.

minka server connect https://ldg-stg.one/api/v2

This points the CLI at the Minka staging environment. In production, your organization will have its own server URL.

Verify your connection:

minka server show

Select the ledger

A server can host multiple ledgers, each an isolated workspace with its own participants, currencies, wallets, and rules. Select the ledger you'll be working with:

minka ledger select payments-hub-demo

$ minka ledger select payments-hub-demo
✅ Ledger selected: payments-hub-demo

This tells the CLI which ledger to target for all subsequent commands. If you're working with multiple ledgers, you can switch between them anytime with minka ledger select.

The payments-hub-demo ledger is a pre-configured demo environment with currencies, wallets, and policies already in place. It's designed for following these guides without needing to set up infrastructure from scratch. Your administrator will provide the ledger name for your own environment.

Create a signer

Every operation on the ledger requires a cryptographic signature. Unlike API tokens or passwords, a signature is tied to a specific key pair that the ledger can verify independently — without trusting any intermediary. This is how the ledger knows exactly who authorized each action, and how it can prove it later in an audit.

A signer is an Ed25519 key pair: the private key stays on your machine, the public key is registered on the ledger. When you submit a request, the CLI signs it with your private key. The ledger checks that signature against your public key before processing anything. No valid signature, no operation.

minka signer create

The CLI prompts you for a handle — a name for this signer — and generates the key pair. The private key is stored locally on your machine, encrypted.

$ minka signer create
? Handle: my-signer
✅ Signer created successfully
Public key: tB/gTevBYDYYYUgOOlsKV2Iq8DzmEtleeTopaY63wqs=

The public key printed here is what you'll share with your ledger administrator to register your signer on the ledger. Once registered, the ledger recognizes your signatures and applies the permissions assigned to your signer — whether that's full administrator access, operator-level payment submission, or read-only balance queries.

You can inspect your signer anytime:

minka signer show my-signer --secret

Your private key should never be shared. Anyone with access to it can perform any action your signer is authorized for, including transferring balances. The CLI stores it encrypted locally — treat it like a password.

Register your signer on the ledger

Your signer exists locally, but the ledger doesn't know about it yet. Your ledger administrator needs to register your public key so the ledger can verify your signatures.

Share your public key with your administrator:

minka signer show my-signer

The administrator will create a signer record on the ledger using your public key and assign it to the appropriate circles and policies — determining what operations you're authorized to perform.

On the payments-hub-demo ledger, you can register your own signer since the demo environment allows self-service registration. In production environments, signer registration is typically controlled by the ledger administrator.

Set up the SDK

The Minka TypeScript SDK handles serialization, hashing, digest creation, and signing automatically. Initialize it with your server and ledger, then define the key pair you'll use to sign requests:

import { LedgerSdk } from '@minka/ledger-sdk'

const sdk = new LedgerSdk({
  server: 'https://ldg-stg.one/api/v2',
  ledger: 'payments-hub-demo',
})

// Your signer key pair — get the values with: minka signer show my-signer --secret
const keyPair = {
  format: 'ed25519-raw',
  public: '<your-public-key>',
  secret: '<your-private-key>',
}

server and ledger match the values you just configured with the CLI. keyPair.public and keyPair.secret come from minka signer show my-signer --secret. Pass keyPair to each SDK operation that writes to the ledger: .sign([{ keyPair }]).

Verify your setup

Run a quick check to confirm everything is connected:

minka server show

You should see your server URL, your active ledger, and your signer listed. If any of these are missing, re-run the corresponding step above.

What to check	Command	What you should see
Server connection	`minka server show`	Server URL pointing to `ldg-stg.one`
Active ledger	`minka ledger show`	`payments-hub-demo` as the active ledger
Your signer	`minka signer list`	Your signer handle and public key

Sign transactions

Every request that mutates data on the ledger must be signed before it's sent. The CLI handles this automatically, but if you're integrating directly via the API — building a bridge, a backend service, or a custom payment flow — you need to implement signing yourself.

See How to Sign Payments for the complete implementation: hashing the payload with RFC 8785 canonicalization, building a signature digest, and signing with Ed25519.

What's next

You're connected to the ledger and have a signer ready to authorize operations. The guides in this section walk you through the core payment flows:

Onboard a Merchant — create a merchant wallet hierarchy with settlement accounts
Send a Payment to an Account — push funds to a bank account
Collect with a Static QR — create a permanent QR payment point

To understand more about how cryptographic identity works on the ledger — including how different signers carry different permissions and why every transaction is auditable — see About Signers.

Authentication model

The ledger uses two layers of authentication that work together:

Bearer tokens identify who you are. The token authenticates your session and determines which ledger you're connected to. Every API request — reads and writes — requires a valid Bearer token in the Authorization header.

Cryptographic signatures authorize what you're doing. Every request that mutates data (creating wallets, submitting intents, registering anchors) must include a proof — a signature computed with your signer's private key. The ledger verifies this signature against the registered public key before processing the request.

The curl examples throughout the documentation show Bearer tokens for simplicity. The TypeScript SDK handles both authentication and signing automatically — you provide the token and key pair during initialization, and the SDK includes the correct headers and proofs on every request.

For details on implementing the signing flow manually, see Sign Payments.

API constraints

Pagination

List endpoints (GET /v2/wallets, GET /v2/intents, GET /v2/anchors) return paginated results. Use limit and offset query parameters to page through large result sets:

curl "https://{ledger-host}/v2/intents?limit=50&offset=100" \
  -H "Authorization: Bearer {your-token}" \
  -H "x-ledger: {your-ledger}"

The default page size is 25 results. The maximum is 100. Results are ordered by creation time, most recent first.

Rate limits

The API enforces per-signer rate limits to protect ledger stability. If you exceed the limit, the response returns HTTP 429 Too Many Requests with a Retry-After header indicating when you can retry.

Design your integration with exponential backoff for production resilience — start with a 1-second delay and double it on each consecutive 429, up to a maximum of 60 seconds.

Connect to a Ledger

On this page