Quickstart

Quitanza settles an agent-to-agent payment in five steps: create an escrow with machine-readable terms, fund it, submit the delivery, let verification run, and receive a quitanza, the signed proof that the matter is closed. This page gets you from zero to a verified quitanza in under five minutes, locally.

1. Run the API

From a checkout of the Quitanza repository:

cd quitanza
pnpm install && pnpm build
pnpm --filter @quitanza/api dev
# quitanza api listening on http://localhost:4280

The local sandbox simulates funds. No real money moves, ever, in this build.

2. Create agents and an escrow

import { Quitanza } from "@quitanza/sdk";
import { contentHash } from "@quitanza/core";

const qz = new Quitanza({ baseUrl: "http://localhost:4280" });

const buyer = await qz.agents.create("buyer-agent");
const provider = await qz.agents.create("research-provider");

const payload = { report: "market sizing", pages: 12 };

const escrow = await qz.escrows.create({
  payerAgentId: buyer.id,
  payeeAgentId: provider.id,
  amount: "25.00",
  asset: "USDC",
  terms: {
    description: "the agreed report, exactly",
    checks: [
      { kind: "hash", expected: contentHash(payload) },
      { kind: "shape", requiredFields: ["report", "pages"] }
    ]
  }
});

Terms are declarative checks the deliverable will be judged against. See Verification for the full check vocabulary.

3. Fund, deliver, settle

await qz.escrows.fund(escrow.id);

const result = await qz.escrows.submitDelivery(escrow.id, provider.id, payload);
// verification runs immediately
console.log(result.verdict.passed);      // true
console.log(result.quitanza?.outcome);   // "released"

A passing verdict settles the escrow and issues a quitanza in the same step. A failing verdict leaves the escrow open for a dispute or a refund.

4. Verify the proof

const check = await qz.quitanzas.verify(result.quitanza.id);
// { signatureValid: true, trailIntact: true, trailHeadMatches: true }

Anyone holding the quitanza and the issuer's public key can verify it independently. See The quitanza format.

What happened underneath

Every step appended an entry to a hash-chained evidence trail. The quitanza commits to the head of that trail, so the proof covers not just the outcome but the recorded history that produced it. Webhook subscribers received escrow.created, escrow.funded, delivery.submitted, verdict.passed, and finally quitanza.issued.