Install APN (Agent Payment Node)

This page shows how to install Agent Payment Node (APN) with Homebrew on Apple Silicon macOS. It covers the Node 24 PATH note, how to discover the installed commands and how to verify a release.

Updated

What do I need before I install APN?

  • An Apple Silicon Mac (darwin / arm64). This is the only supported platform.
  • Homebrew. The Formula installs apn and the Homebrew node@24 dependency for you.
  • Node.js in the range >=24 <27 as the first node on your PATH.

How do I install APN with Homebrew?

Run one command:

brew install nuanu-ai/tap/apn

The first wallet command creates ~/.apn with mode 0700 and one encrypted wallet envelope per profile with mode 0600. Homebrew does not own ~/.apn, so status and receipts survive reinstall and upgrades.

Why does APN say APN_NODE_UNSUPPORTED?

apn runs on the first node on your PATH. Homebrew keeps node@24 off PATH (keg-only). If that first node is outside >=24 <27, apn and apn mcp serve load nothing else. They print one APN_NODE_UNSUPPORTED line on stderr that names the required range and the running version, write nothing to stdout and exit 1.

The fix is to put the Homebrew Node 24 directory first on PATH:

/opt/homebrew/opt/node@24/bin

Add that directory at the front of PATH in your shell profile, then open a new terminal and run apn --version.

How do I discover APN commands?

Use the built-in help. These commands run before any state, Keychain, wallet, policy, network or signing work, so they are safe to run first.

apn --help
apn wallet --help
apn help pay transfer prepare-asset
apn help --json
  • Help is raw text.
  • apn help --json prints one raw apn.command-manifest.v2 JSON object. It is the machine source of truth, so agents should read it instead of guessing flags.
  • Every operational command prints exactly one apn.cli.v1 JSON envelope with ok, error, operation, receipt and next_actions.
  • next_actions names the next command to run, or the variable or option to fix.

Manifest v2 merged several v1 commands and removed the historical Circle v1 and LI.FI recovery commands, whose operations are all terminal. The manifest's removed_v1_commands lists each removed path with its replacement. Running an old path fails with APN_UNSUPPORTED_COMMAND, and its first next action is the replacement.

How do I check which version I have?

apn --version

A matching version number does not prove that an installed artifact contains a given source change. The README says to check apn --version, the release provenance and apn help --json together.

How do I verify an APN release?

Release artifacts are built twice with Node 24.15.0 and must be byte-identical. The workflow emits the npm tarball, an SPDX 2.3 SBOM and a release manifest. The manifest binds names, sizes and SHA-256 digests to the exact commit. GitHub artifact attestations bind those bytes to the pinned workflow identity.

Verify the attestation first, then run the repository's verifier. Replace <version> with the release version.

gh attestation verify nuanu-ai-apn-<version>.tgz \
  --repo nuanu-ai/agent-payment-node \
  --signer-workflow nuanu-ai/agent-payment-node/.github/workflows/release.yml \
  --source-ref refs/heads/main \
  --deny-self-hosted-runners

node scripts/verify-supply-chain.mjs verify \
  --artifact nuanu-ai-apn-<version>.tgz \
  --sbom nuanu-ai-apn-<version>.spdx.json \
  --manifest nuanu-ai-apn-<version>.release.json \
  --formula Formula/apn.rb
  • The verifier rejects mutable URLs, version drift and any digest not in the manifest.
  • Releases come only from the manually dispatched release workflow on a protected vX.Y.Z tag. Publication and Homebrew updates are separate owner actions.
  • The archive ships npm-shrinkwrap.json, so installation resolves the exact integrity-pinned dependency closure.
  • Artifacts, SHA-256 digests and provenance for every version are listed on the GitHub releases page. This site's releases page tracks them too.

What should I do after installing?

Follow the quickstart to create a profile, write an owner policy and send a small Base USDC transfer. To connect an MCP client, read the MCP page. APN needs no RPC account or API key. Each command takes an explicit --rpc-url or an APN_<CHAIN>_RPC_URL variable, and an error names the one to fix.

If something in the install does not match what you see, check the APN FAQ first.

Questions

How do I install APN?

Run brew install nuanu-ai/tap/apn on an Apple Silicon Mac. The Formula installs apn and the Homebrew node@24 dependency.

Why does apn fail with APN_NODE_UNSUPPORTED?

The first node on your PATH is outside >=24 <27. Put /opt/homebrew/opt/node@24/bin first on PATH.

Can I install APN on Linux or Windows?

No. Both are unsupported. The repository has no package, release target or credential backend for them.

Sources
  1. README: install
  2. README: discover the installed contract
  3. README: verify a release
  4. README: RPC configuration
  5. Platform support matrix
  6. CHANGELOG: releases