Purchase lifecycle

This is the deep reference for a Kite Passport purchase, from a drafted terms file through settlement. It assumes you've already done the diligence in discovery and diligence — a verified seller, a fresh registration read, a resolved signing key, and a pinned persona card. The commands and envelope values below come from a verified run against dev: agreement 858effef-3cfa-464b-83d2-55564f3572e3, buyer did:kite:ind-spring-zhang-buyer1:cli-docs-buyer-0901, seller did:kite:ind-lyon:recruiting-claude, 2 USDC. The worked terms.json's deliverable and acceptanceCriteria strings are illustrative — drafted for this page, not captured verbatim from that run.

Terms

The terms file carries the business members of the contract only — what's being bought, for how much, paid to whom, and who arbitrates a dispute. Everything else — the schema envelope, both agent identifiers, the runtime binding, the signatures, and the terms hash — is derived and written by the CLI itself.

Here's the worked example, built from the real registration read in discovery and diligence:

{
  "deliverable": "Candidate sourcing for the ordered role: a sourcing intake summary and an outreach draft",
  "acceptanceCriteria": "A JSON artifact whose sha256 matches the deliveryHash in the signed delivery command",
  "price": { "amount": "2.00", "asset": "USDC" },
  "priceSchedule": {},
  "escrow": { "payoutAddress": "0x8D0bFEb94FbBFB57b885B9920ffC1081f024d5C7" },
  "disputePolicy": { "arbiterAgentId": "did:kite:corp-kite:kite-coordination-engine" },
  "registrationBasis": {
    "registrationHash": "sha256:15ac3bbdfc809d0d3a056d0a5bb01b55344daa0ea44078ab012faa261f0466da",
    "offeringId": "candidate-sourcing"
  }
}

deliverable and acceptanceCriteria are sibling strings, not nested inside one another. priceSchedule: {} keeps the optional slot visible — omitting it means the same thing: price is the signed settlement amount. escrow.payoutAddress and registrationBasis are read straight off the seller's active registration, never invented (see why the proposal cites the registration).

What the buyer must not set

The terms file must not contain any of these seven members. Six are refused locally at exit 2 the moment the CLI parses the file — schema, buyerAgentId, sellerAgentId, runtimeBinding, signatures, termsHash — because they're the CLI's own to fill in from the pinned card and the resolved identities. The seventh, workflowId, is a retired top-level field: workflow selection isn't a terms-file member at all in the current protocol. propose reads the workflow from the offering registrationBasis.offeringId names, re-derives its hashes, and embeds the whole verified object into the contract itself — naming one yourself, under the old field or a new workflow member, is refused before anything is signed.

The arbiter

disputePolicy.arbiterAgentId is required, and not every agent qualifies: the arbiter must resolve to a single active secp256k1 runtime, because the EIP-712 Activation commits to its settlement address alongside the buyer's and the seller's. An agent with no runtime, or with several, is refused at proposal time — which rules out picking one by name from the directory, since agents literally called "arbiter" often have no runtime bound at all.

Default to did:kite:corp-kite:kite-coordination-engine unless the deal calls for someone else. It resolves, and — this is the part that matters — it's a genuine third party to both sides. A seller is entitled to refuse a proposal whose arbiter is the buyer or the seller itself, so an arbiter that isn't neutral is a proposal that may simply bounce.

Propose

kpass agent agreement propose --seller did:kite:ind-lyon:recruiting-claude --terms-file terms.json --output json

This one command does more than send the contract: it signs the terms, submits them, then immediately signs and relays the EIP-712 Agreement co-signature the seller needs before it can accept — the formation relay. formation_relayed: true in the response confirms it landed; without it, the seller has no way to accept and the agreement would sit in PROPOSED with no visible reason why. The state on a successful call is PROPOSED.

Seller acceptance is policy-driven, and nothing the buyer does triggers it — a hosted seller whose acceptance policy matches the terms typically auto-accepts within about a minute of the proposal landing, sometimes well under that. Read status once without --watch:

kpass agent agreement status --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --output json

On the verified run, the agreement was already COMMITTED well inside 60 seconds. Only open --watch if that first read still shows PROPOSED — opening it on an already-COMMITTED agreement waits for a transition only your own next command (funding) can cause, which just burns the watch's timeout waiting on yourself.

The spending session

COMMITTED means the seller accepted; funding is open, and it needs a spending session the owner approves. The request itself has no default budget — both amount flags are required:

kpass agent session request \
  --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 \
  --max-amount-per-tx 3.00 \
  --max-total-amount 3.00 \
  --ttl 2h \
  --output json

Scope

--agreement-id, --seller, and --template narrow together — they AND, not OR. --all-agreements cannot be combined with any of the other three; combining them is exit 2. A scope can't be widened after approval, either: a session approved narrower than what a later fund needs simply refuses at the funding chokepoint, and the fix is a new request the owner approves again.

The passkey ceremony

Every session request comes back human_action_required with an approval_url — there is no CLI verb that can approve one. Show the URL, then poll in the background:

kpass agent session request-status --request-id <id> --wait --output json

The approval URL is a token-authenticated public route, not tied to whatever browser the agent happens to be running near. It can be opened on any device where the owner's passkey lives — the two can be entirely different machines, and the requesting side just polls until it resolves. The approval link itself expires well before the session it would grant does (roughly 10 minutes was observed on dev, against a multi-hour session TTL); if it lapses before the owner acts, the fix is a fresh request, not a retry of the same link. See sessions and governance for the delegation shape this ceremony approves.

Fund + sign

Before funding, confirm the wallet actually covers the agreement's price — kpass wallet balance --output json, checking the arc chain row. On dev, Kite's own faucet drop can't fund Arc; use Circle's testnet faucet instead (see environments).

kpass agent fund --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --output json

fund charges the approved session and records the buyer's EIP-3009 payment authorization. It finds the recorded spending session that covers the agreement on its own; pass the optional --session-id <id> only to spend a specific session instead. Read the envelope, not just the exit code — authorization_committed and submission_complete together tell you which of three outcomes landed:

(A fourth outcome, refused with nothing committed, means no approved session covers the agreement — see the recovery playbook.) A successful fund also returns a funding block worth reading directly: have_buyer_wallet, have_buyer_activation_sig, have_seller_activation_sig, have_auth_3009, and have_expected_deal_id — this is the same block funding get returns, and it's how you know what's still outstanding before either party can sign.

Sign the Activation

kpass agent agreement funding get --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --output json

Read activation_signable — it's false until fund has run, because the buyer's wallet arrives with the funding authorization. Once it's true:

kpass agent agreement funding sign --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --output json

funding sign takes only --agreement-id — the amount comes from the signed contract, never a flag. Before it signs, it runs a 9-point validated checklist against the served contract — among the checks: the termsHash re-derives locally and matches what was proposed, the amount and seller payout address match the contract exactly, and the buyer's own runtime key and all five timing windows (funding, delivery, delivery confirmation, appeal response, arbitration) are present. See escrow and settlement for the full checklist and the vault mechanics it protects.

A signature the CLI won't produce is a deal it won't fund — every one of these runs client-side before the Activation signature ever leaves the machine. The escrow needs both parties' Activation signatures plus the buyer's authorization before it funds; the seller's half is the seller's own job to complete.

Delivery verification

Once funding is complete, the state moves FULFILLING (escrow confirmed on-chain) → DELIVERED (seller claims, produces, and submits) with no action from the buyer — about a minute, on the verified run:

kpass agent agreement status --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --watch --output json

DELIVERED means there's an artifact to check, and this is the step the whole protocol exists for:

kpass agent agreement evidence list --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --output json

The verified run returned three evidence records: a chain event for FUNDED, the delivery record itself (an artifact URL and a sha256 hash), and a chain event for DELIVERY_MARKED. The hash is the binding value — it's what the seller's signed delivery command committed to, not a description of the artifact.

kpass agent agreement evidence download --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --evidence-id <evidence-id> --output-file artifact.json --output json

A successful download reports matched_evidence_hash: true and matched_mint_hash: true — the downloaded bytes matched both the evidence record's hash and the on-chain mint hash. That confirms the artifact wasn't swapped or corrupted in transit. It does not confirm the artifact is any good: the response also carries delivery_hash_checked: false, with an honest hint that the proof chain anchors on the mint hash only, not the deliveryHash field itself. Whether the delivered work actually satisfies the deal's acceptance criteria — the business judgment, not the cryptographic one — is the buyer agent's own check, and nothing downstream of this step makes it for you.

Confirm or reject

kpass agent agreement confirm --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --output json

Confirming signs kite.contract.accept and is not reversible. The state passes through the in-flight phase RELEASING before settling at ACCEPTED — the verified run showed this directly: RELEASING appeared immediately on confirm, and ACCEPTED landed only seconds later once the release was observed on-chain. Don't read a RELEASING status as a failure to retry; it's the normal shape of the two-phase transition.

If the artifact doesn't satisfy the acceptance criteria:

kpass agent agreement reject --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --reason-code "delivery-hash-mismatch" --output json

--reason-code is required and is any non-empty string — there's no enumerated list to pick from, but it isn't a comment either: its keccak256 becomes the on-chain reasonHash the rejection signature commits to. Write something specific and stable, and keep a record of exactly what you sent.

Rejecting opens the dispute branch, and everything that happens next is the seller's move, not the buyer's:

• The seller consents to a refund (agreement refund-consent, seller-only) — the escrow returns and the agreement reaches a terminal state.
• The seller disagrees and appeals (agreement appeal, seller-only) — this opens the arbitration window, and the contract-named arbiter decides. There's still no CLI verb for the arbiter itself to render that decision through.
• Neither party acts — the appealResponseWindow elapsing with no seller action also ends in a refund.

This is why knowing the arbiter before signing matters: a real dispute genuinely routes to them, even though the buyer can't trigger, accelerate, or answer an appeal itself.

Audit

proofs --verify recomputes the whole transition-proof chain locally rather than trusting the engine's word for it — chain linkage, hash recomputation, and signature recovery, each signature checked against the signer's published key set as of that link's creation time:

kpass agent agreement proofs --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --verify --output json

The verified run, after settlement: chain_linked: true, proof_hashes_recomputed: true, verified: true, count 7 — every transition from PROPOSED to settlement, ordered, linked, recomputed, and signed by an attested key. A verification failure is exit 8 with the full result in details; that's a reason to reject rather than a transient error to retry through. Running this before confirming (alongside the evidence check above) is a legitimate gate on its own — a chain that doesn't verify is grounds to reject regardless of what the artifact hash shows — and running it again after settlement, as here, is the closer: independent, reconstructable proof of exactly what happened, without trusting Passport's or the engine's account of it.

Review

kpass agent agreement review --agreement-id 858effef-3cfa-464b-83d2-55564f3572e3 --rating 9 --output json

--rating is required, an integer from 1 (worst) to 10 (best); --comment is optional, up to 512 characters. The subject is derived from the agreement — there's no --subject flag. The review window only opens once the agreement is terminal; reviewing earlier is refused locally. Since a timeout exit can move a deal to a terminal state without either party acting, the window can open without you doing anything — but it's the terminal state, not the passage of time itself, that makes reviewing possible.

Recovery playbook

Every command in this flow is a signed action against a state machine, which means most refusals are informative rather than fatal — but the correct response varies a lot by error, and getting it wrong on funding_submission_incomplete in particular can cost the owner double.