Developer quickstart

Build from source. Run these in the folder where you keep projects, one line at a time:

git clone https://github.com/probarion/probarion
cd probarion
pnpm install
pnpm --filter "{packages/cli}..." build

Then check the CLI:

node packages/cli/dist/bin.js --version

0.1.1

The build also makes packages/core/dist and packages/sdk/dist, because the CLI depends on both. The scripts below live in this probarion folder, run from it, and import ./packages/sdk/dist/index.js and ./packages/core/dist/index.js.

Make the agent key and the ledger key.

node packages/cli/dist/bin.js agent keygen --out ../agent-key.json
node packages/cli/dist/bin.js agent keygen --out ../ledger-key.json

Each run saves the pair and prints only the public key (your path differs):

public_key: ed25519:...
secret_key: saved to /home/you/agent-key.json (mode 0600), not printed

Keep that file server-side only (read PROBARION_AGENT_KEY or PROBARION_LEDGER_KEY from it). Never commit it.
Share only the public key with the vault owner, who adds it with "probarion agent add" or "probarion ledger set-key".

Each file holds { public_key, secret_key } and keygen never overwrites one. On Windows the line has no (mode 0600): the folder's permissions apply, and the CLI prints a warning that says so. The ../ keeps both files outside the clone. For a file inside a git work tree, the CLI warns you to check that git ignores it.

Have the owner set up the vault. Save the purchase order or contract the agent pays against as ../po.txt. Its sha256 becomes the mandate's purpose hash.

• The owner creates a testnet vault and adds test USDC, as in steps 1 to 3 of Owner quickstart: sign in, create the vault, add test USDC. The owner skips its steps 4 and 5: the console's Keys tab makes keys for Payables, the agent Probarion runs for the owner from the console, and your agent brings its own keys and gets its own mandate below. Once the vault is registered, the console opens its "Overview" tab, where the "Your first agent payment" card's next step is "Agent key and ledger key", with a "Go to Keys" link for hosted Payables and a "Connect agent" link for the Agent (MCP) tab. Skip "Go to Keys": your agent brings its own keys. The step ticks once your agent key and ledger key are on the vault. The card goes away after the vault's first payment. On the vault's Top-up tab (/console/<vault>/topup), the "Add test USDC" button mints 25 test USDC into the vault with no wallet. The Probarion team's mint-only key signs it, once a UTC day per vault and for up to 3 vaults per signed-in account a day. If the site has no faucet key, the tab shows this instead: "Need test USDC? Send @probarionhq a direct message on X with your vault's name."
• An owner who makes the vault with vault create instead passes --deposit 3.23352, the figure the console pre-fills. The CLI checks the deposit only against the factory's 0.5 NEAR min_deposit, but today's testnet factory also charges the storage for the vault's own copy of its code, and it refuses a deposit that does not cover both with InsufficientDeposit. Such a vault joins the console through the "Register a vault you already own" card.
• The owner tells you the vault's account, the owner account and the payee: a testnet account the owner controls, such as a second account of theirs. The payee of a mandate never changes, so check every character.

You then print the three transactions that add your keys and the mandate: run these in your clone, in the probarion folder. The console cannot add your keys, because its Keys tab adds only keys that Probarion makes on its server. Long lines end in \ as bash writes them; in PowerShell, put each command on one line.

# Illustrative values: use your vault, the owner's account, the payee the owner named and the public keys keygen printed.
# The agent key: public_key from ../agent-key.json
node packages/cli/dist/bin.js --network testnet agent add --vault acme.vaults.probarion.testnet \
  --pk ed25519:... --sign-as owner.testnet --out-dir probarion-tx
# The ledger key: public_key from ../ledger-key.json
node packages/cli/dist/bin.js --network testnet ledger set-key --vault acme.vaults.probarion.testnet \
  --pk ed25519:... --sign-as owner.testnet --out-dir probarion-tx
# The mandate: the agent key again, the payee, the limits and the purpose file. --expires is any future date.
node packages/cli/dist/bin.js --network testnet mandate create --vault acme.vaults.probarion.testnet \
  --payee near:vendor.testnet --max-per 5 --max-total 20 --uses 5 --expires 2026-12-31 \
  --approval-above 2 --agent-pk ed25519:... --purpose ../po.txt --label "Agent quickstart" \
  --sign-as owner.testnet --out-dir probarion-tx

Each command writes its arguments to a file in probarion-tx/ and prints the near-cli-rs command with the file's sha256, under this line:

OWNER SIGNS: probarion never signs owner or approver transactions. Review the arguments, then sign with your own wallet or near-cli-rs:

Send the owner the three printed commands and the probarion-tx folder. Each command names its arguments file as ./probarion-tx/<file>, so the owner runs it in a folder that holds probarion-tx, in bash, zsh or PowerShell. The command ends in sign-with-keychain send, so the owner needs near-cli-rs with the owner account in its keychain (near account import-account puts it there). With a Ledger, the owner replaces sign-with-keychain send with sign-with-ledger usb send, as the CLI's own hint says.

This mandate pays only its payee, here vendor.testnet, at most 5 test USDC per payment and 20 in total over 5 uses, until the end of its expiry day in UTC. It holds any spend above 2 USDC for an approver. The console's mandate form lists every agent key on the vault, so once your agent key is added the owner can sign the mandate there instead, in their wallet, and you skip the mandate create command. Send the owner the same po.txt for it: the form hashes the file in the browser.

Dry-run a spend. A read-only instance (no keys, model: null) calls the vault's free check_spend view, which runs the same checks as spend and changes nothing. Adapted from the README's evaluation, with the illustrative vault name:

import { readFile } from "node:fs/promises";
import { sha256Hex } from "./packages/core/dist/index.js";
import { Probarion, hashInvoice } from "./packages/sdk/dist/index.js";

// No keys: this instance can read the vault and dry-run a spend. It cannot pay.
const vault = new Probarion({ network: "testnet", vault: "acme.vaults.probarion.testnet", model: null });

const purposeHash = sha256Hex(new Uint8Array(await readFile("../po.txt")));
for (const m of await vault.mandates.list()) {
  console.log(m.id, m.status, m.purpose_hash === purposeHash ? "purpose matches" : "other purpose");
}

const text = "Invoice INV-1: 1.00 USDC for PO-1001";
const invoiceHash = hashInvoice(text);
console.log(await vault.checkSpend({ mandateId: 1, amount: "1000000", invoiceHash, ref: "INV-1" }));

node dry-run.mjs

On a vault whose first mandate is this one:

1 active purpose matches
{ ok: true, code: null, would_hold: false }

code: 'NotAgent' means the agent add transaction has not landed yet. The checks do not read the vault's USDC balance, so an empty vault passes the dry run too. Its payout then fails in the next step, and process() returns failed.

Run one payment. Illustrative, adapted from the SDK README: the imports point at the built files, the keys come from the two key files, and model: null lets the code decide alone.

import { readFile } from "node:fs/promises";
import { sha256Hex } from "./packages/core/dist/index.js";
import { Probarion, hashInvoice } from "./packages/sdk/dist/index.js";

const secretOf = async (file) => JSON.parse(await readFile(file, "utf8")).secret_key;

const probarion = new Probarion({
  network: "testnet",
  vault: "acme.vaults.probarion.testnet",
  agentKey: await secretOf("../agent-key.json"), // can call spend and nothing else
  ledgerKey: await secretOf("../ledger-key.json"), // can call anchor, and signs every ledger entry
  model: null, // the code decides alone
});

const text = "Invoice INV-1: 1.00 USDC for PO-1001";
const outcome = await probarion.process({
  text, // the invoice text; facts.invoice_hash is its hash
  ref: "INV-1", // your reference: the vault accepts each ref once
  facts: {
    invoice_hash: hashInvoice(text),
    amount: "1000000", // USDC has 6 decimals, so this is 1 USDC
    po_ref: "PO-1001", // copied verbatim from the text
    purpose_hash: sha256Hex(new Uint8Array(await readFile("../po.txt"))), // the file the mandate was signed with
    payee_hint: null, // what the invoice claims about the payee; never the destination
  },
});

console.log(outcome.status, outcome.spendId, outcome.code, outcome.ledgerSeq);

node pay-once.mjs

On a new vault with an empty ledger, a clean payment prints the status, the spend id, no code and the ledger position of the payment entry. These are the values the SDK's own test expects against its fake chain:

paid 1 null 1

The decision entry sits at position 0, before anything is sent. The SDK picks the mandate by purpose_hash: the lowest-id mandate with that purpose that this agent key can still use. It writes the ledger to .probarion/ledger.jsonl in this folder unless PROBARION_LEDGER_PATH names another file. outcome.txHash is the spend transaction, and outcome.anchorTxHash is the anchor written after the cycle, or null when the anchor failed or was not needed. model: null keeps this quickstart on the code alone; the optional NEAR AI Cloud model step needs an API key, and its real attested run is Preview (Let an agent pay).

Branch on the outcome. outcome.status is one of the seven statuses process() returns, each described in the table below. Add this illustrative switch at the end of pay-once.mjs, after the console.log line:

switch (outcome.status) {
  case "paid":
  case "burned":
    // Paid. Record outcome.spendId and outcome.txHash.
    break;
  case "held":
    // spendId set: the contract holds it for an approver.
    // spendId null: a code rule held it (outcome.code) and nothing was sent.
    break;
  case "refused_by_code":
  case "refused_by_contract":
    // Not paid. outcome.code names the rule or the vault check that refused it.
    break;
  case "failed":
    // Definitely not paid. outcome.code says why.
    break;
  case "unconfirmed":
    // May have paid. Never send it again: find the spend by its ref first.
    break;
  // "settled" is in SpendOutcomeStatus, but process() never returns it.
}

Run pay-once.mjs a second time and it gives refused_by_code with invoice.duplicate: the vault has paid that invoice and used that ref. Give each new payment its own invoice text and its own ref.

Verify your vault. Run it from the same folder, so the CLI reads the same default ledger:

node packages/cli/dist/bin.js --network testnet verify --vault acme.vaults.probarion.testnet

The report starts with Probarion verify: <vault> (testnet), lists each check, and ends with a count line and RESULT: PASS, RESULT: FAIL or RESULT: UNPROVEN. The exit code says the same:

Verify a vault yourself walks through a run, and Verifier checks explains each check.