Install & run

Prerequisites

• Node.js 20 or later
• pnpm 10 (corepack enable is sufficient; the repo pins pnpm@10.12.1)

Build, typecheck, and test

pnpm install
pnpm -r build
pnpm -r typecheck
pnpm -r test

This builds every package in the monorepo and runs each package's own test suite against local fixtures — nothing here touches Hedera testnet or requires funded accounts.

Configure environment variables

cp .env.example .env

Every command below reads from this file. See the environment variables reference for what each value is and where it comes from. HEDERA_OPERATOR_ID and HEDERA_OPERATOR_KEY — a funded Hedera testnet account — are required before any of the commands in this section will run.

Provision testnet accounts and the mandate registry

FINITY_TESTNET=1 pnpm testnet:bootstrap

Requires a funded HEDERA_OPERATOR_ID / HEDERA_OPERATOR_KEY. This is the account-creation step: it creates the broker and both provider Hedera accounts (reusing any that are already set in .env), deploys MandateRegistry, creates the Finity Service Registry HCS topic, seals a Broker Bundle into the local Key Ring, and writes every resulting ID, key, and address back into .env.

Run the provider services

Each provider needs its own Hedera account, a public origin, a signing key, and a port — FINITY_PROVIDER_A_* / FINITY_PROVIDER_B_* in .env. testnet:bootstrap fills these in automatically; set them by hand only if you are pointing at accounts it did not create. localhost is accepted over plain HTTP for local development — any other origin must be HTTPS.

pnpm provider:weather

Each process validates its own signing key and public base URL at startup and refuses to bind if either is malformed.

Publish the service registry

FINITY_TESTNET=1 pnpm registry:seed

Signs both provider manifests and publishes them to the Finity Service Registry HCS topic — reusing FINITY_REGISTRY_TOPIC_ID if it's already set, otherwise creating one. Requires the funded HEDERA_OPERATOR_ID / HEDERA_OPERATOR_KEY; the provider HTTP servers do not need to be running for this step, since manifests are built and signed locally.

Run a paid transaction against a live provider

FINITY_TESTNET=1 pnpm testnet:paid

Makes real x402-paid HTTP requests against both provider services, using the broker's FINITY_SPEND_ACCOUNT_ID and FINITY_BROKER_SESSION_KEY. Both provider processes must already be running and reachable at their configured URLs.

registry:seed and testnet:paid both refuse to run unless FINITY_TESTNET=1 is set explicitly on the command — this is a deliberate fail-closed guard, not a default you flip once. Record the resulting HCS topic ID and settlement transaction ID in docs/VERIFIED.md.

Register a Ledger-signed mandate

FINITY_TESTNET=1 pnpm testnet:mandate

The scripted equivalent of /finity mandate new. Requires a broker identity already created by testnet:bootstrap, FINITY_REGISTRY_ADDRESS / FINITY_BROKER_EVM_ADDRESS / FINITY_SPEND_ACCOUNT_ID set in .env, and a physical Ledger connected, unlocked, with the Ethereum app open — the script calls signTypedDataOnDevice and waits for a clear-sign approval. Most users should go through the buyer agent below instead; this script exists for scripted or CI-style verification runs.

Set up the Ledger-governed buyer agent

packages/pi-package is the Pi extension — the finity_* tools, the /finity command family, and the Finity control-center TUI. packages/finity-cli publishes to npm as @therick/finity, the finity wrapper binary end users install.

npm i -g @ledgerhq/wallet-cli @earendil-works/pi-coding-agent
npm i -g @therick/finity
finity

To build from source instead:

pnpm --filter @therick/finity --filter @therick/pi-package --filter @therick/finityd build
node packages/finity-cli/dist/bin/finity.js

For normal use, just ask Pi to buy something. finity_buy validates and reuses an existing sealed broker and an ACTIVE compatible mandate first. If either is missing, the same chat flow creates and Key-Ring-seals a broker key, asks the Ledger account to fund it, resolves the Hedera account ID, asks the Ledger to sign a one-purchase/one-hour mandate, starts finityd, and resumes the original purchase. Returning users see no setup prompts.

See the CLI reference for the full finity, /finity, and finity-verify command set.

Run the web console

The Next.js console powering this site lives in apps/console.

pnpm --filter @therick/console dev

For a production build:

pnpm --filter @therick/console build
pnpm --filter @therick/console start