Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Install

Install @koed_jang/apyx-sdk and its viem peer dependency. The SDK is distributed under the prototype dist-tag on npm — pin to it explicitly so that an unstable change can never silently roll into your build.

Requirements

  • Node ≥ 20. The SDK ships dual ESM (browser-targeted) and CJS (Node) bundles; both require an evergreen runtime.
  • viem ≥ 2.21.0, installed as a sibling. The SDK never bundles viem — you bring your own version so transports, chains, and accounts are shared with the rest of your app.

With pnpm

pnpm add @koed_jang/apyx-sdk@prototype viem

With npm

npm install @koed_jang/apyx-sdk@prototype viem

With yarn

yarn add @koed_jang/apyx-sdk@prototype viem

Without installing — dlx / npx

The CLI can be invoked one-off via your package manager’s runner without adding the package as a dependency:

pnpm dlx @koed_jang/apyx-sdk@prototype apyx --help
# or
npx -y @koed_jang/apyx-sdk@prototype apyx --help

This is the recommended path for ad-hoc shell sessions; install globally only if you reach for apyx daily.

Optional: Ledger hardware-wallet support

Hardware-wallet signing is an optional feature, and the underlying USB-HID stack pulls a couple of hundred KB of native bindings that most consumers don’t need. The SDK lists them under optionalDependencies, so a stock install does not pull them in. To enable Ledger:

pnpm add @ledgerhq/hw-transport-node-hid @ledgerhq/hw-app-eth

Without those packages installed, any signer.type = "ledger" config profile fails with a clear “install them with…” hint at the first attempt to use it. Pure read-only and key-file workflows are unaffected.

See the Ledger Setup chapter for permissions, udev rules on Linux, and the Ledger Live → derivation-path mapping.

Why prototype and not latest?

@koed_jang/apyx-sdk is being shipped as an early prototype. The latest dist-tag will be reserved for the first stabilised release; until then every published version carries the prototype tag and a -prototype.N semver suffix. That gives you two guarantees:

  1. pnpm add @koed_jang/apyx-sdk@prototype always pulls the newest prototype build, never accidentally a future stable.
  2. pnpm add @koed_jang/apyx-sdk (no tag) intentionally fails until a stable lands, so you can’t half-upgrade by mistake.

See Releasing for the full version policy.

Verify the install

The fastest sanity check is the CLI:

pnpm exec apyx --version
# 0.1.0-prototype.0   (or whatever you just installed)

A working apyx --version confirms the install + dist + binstub paths end-to-end. From there, Quickstart walks the first read against mainnet.