The buyer SDK (CLI)

The pay CLI: fund the escrow once and fire real paid calls to a live endpoint, with a settlement tx and an ArcScan link per call.

The pay CLI is the reference paying agent. It discovers an endpoint’s card, sizes the deposit, funds the escrow once, and fires N real paid calls through the escrow gate. It always starts safe: without --apply it makes zero chain writes and zero paid calls.

Setup

The CLI reads its config from the repo-root .env.local.

TEST_BUYER_PRIVATE_KEY · string · required

The buyer EOA private key, funded on Arc testnet. Read once into the wallet and never logged. Required for both a dry run and an apply run: the dry run reads the buyer’s real escrow balance to decide whether a deposit is even needed.

ARC_RPC_URL · string

Optional Arc RPC override. Falls back to the chain default.

ARC_EXPLORER · string

Optional block explorer base for the per-call links. Defaults to https://testnet.arcscan.app.

Secrets live only in the gitignored .env.local. The buyer key is read once into the wallet and never appears in a log line or any output.

Dry run first, then apply

Run without --apply to see exactly what a real run would do. The CLI reads the card and the buyer’s escrow balance, prints the sizing plan, and stops. No chain writes, no paid calls.

Dry run

pnpm --filter @utter/buyer-sdk pay -- \
  --url https://return-the-current-utc-time-as-json.resources.utter.technology

The plan sizes the deposit as cap * calls, where the cap is the card’s pricing max. With --apply, the CLI deposits once for the shortfall (reading decimals() at runtime), then pays each call: on a 402 it signs a capped DebitAuthorization, sends it in the X-PAYMENT header, and asserts a 200 with a receipt.

Flags

--url · string · required

The resource base URL, or its full agent-card URL. --card-url is an accepted alias.

--calls · number · default: "1"

How many real paid calls to fire. The one-time deposit is sized to cover every call.

--apply · boolean · default: "false"

Actually deposit and pay. Without it the run is a dry run: reads the card and escrow balance, prints the plan, and makes zero chain writes and zero paid calls.

--body · string

A JSON string POSTed as the request body to the handler. Defaults to a benign echo body.

--resource-id · string

A 0x-prefixed bytes32 to bind the card’s payTo against, a safety check. Omitted, the card is trusted by its URL and its payTo is used as discovered.

The full flag and behavior table is in the buyer SDK reference.

What a paid call prints

For each paid call the CLI prints the status, whether it paid, the debit amount, the idempotency key, the settlement tx hash, and a link straight to the settlement on ArcScan.

[demo-pay] call 1/10: status=200 paid=true debit=1200 idem=0xabc... tx=0xdef...
  on-chain settle: https://testnet.arcscan.app/tx/0xdef...

An apply run that does not pay every call exits non-zero, so a host or CI invocation detects a broken money path. A dry run always exits zero.

A full example

Fire three paid calls to an endpoint with a request body, after checking the plan first.

# 1. Dry run: see the sizing plan, no writes.
pnpm --filter @utter/buyer-sdk pay -- \
  --url https://sentiment.resources.utter.technology \
  --calls 3 \
  --body '{"text":"utter ships"}'

# 2. Apply: deposit once, then pay all three.
pnpm --filter @utter/buyer-sdk pay -- \
  --url https://sentiment.resources.utter.technology \
  --calls 3 \
  --body '{"text":"utter ships"}' \
  --apply

The CLI never re-implements the money path. It orchestrates a deposit before, and N pays over, the frozen escrow gate. Reserve-before-run and exactly-once stay inside the gate.

Next

Deposits and spend caps

How the escrow deposit works and how caps bound what the buyer signs.

Buyer SDK reference

Every flag, env var, and the full CLI behavior table.