Quick Start

Run your first accountability lifecycle: create a mandate, submit a receipt, get a verdict.

The pattern

An AI agent requests an action through your enterprise software. Your enterprise software executes it, then reports what actually happened to AGLedger. Now you have verified proof — not just the agent's word.

1. Agent requests action    →  Enterprise creates mandate (commitment)
2. Enterprise executes      →  (AGLedger doesn't touch this)
3. Enterprise reports       →  Submit receipt (evidence from system of record)
4. AGLedger verifies        →  Evidence vs. commitment, within tolerance
5. Mandate settles          →  Immutable, auditable accountability record

Prerequisites

You need an enterprise key and an agent ID:

export AGLEDGER_API_KEY=ach_ent_your_key_here
export AGLEDGER_ENTERPRISE_ID=your-enterprise-uuid
export AGLEDGER_AGENT_ID=your-agent-uuid
API_BASE="https://api.agledger.ai"

Step 1: Create a mandate

The mandate is the commitment — what needs to be done, by when, within what bounds.

curl -X POST "$API_BASE/v1/mandates" \
  -H "Authorization: Bearer $AGLEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enterpriseId": "'$AGLEDGER_ENTERPRISE_ID'",
    "contractType": "ACH-PROC-v1",
    "contractVersion": "1",
    "platform": "quickstart",
    "agentId": "'$AGLEDGER_AGENT_ID'",
    "criteria": {
      "item_spec": "Industrial widgets",
      "quantity": { "target": 100, "tolerance_pct": 10, "unit": "units" },
      "price_ceiling": { "amount": 2000, "currency": "USD" }
    },
    "tolerance": {
      "quantity_pct": 10,
      "price_margin": 200,
      "grace_seconds": 86400
    }
  }'

Response:

{
  "id": "019d3b08-bbef-...",
  "status": "CREATED",
  "contractType": "ACH-PROC-v1"
}

Two creation paths. This guide uses POST /v1/mandates with an enterprise key — the enterprise creates the mandate on behalf of an agent. The Orchestrator guide uses POST /v1/mandates/agent where agents create mandates directly between each other (principal agent to performer agent). The lifecycle is the same; the starting state differs: enterprise-created mandates start at CREATED and use register+activate; agent-created mandates start at PROPOSED and use accept+activate.

Step 2: Activate the mandate

Register (enterprise approves the commitment) and activate (work may begin):

MANDATE_ID="019d3b08-bbef-..."

curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/transition" \
  -H "Authorization: Bearer $AGLEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "register" }'

curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/transition" \
  -H "Authorization: Bearer $AGLEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "activate" }'

Step 3: Submit a receipt

After the action completes, report what actually happened. The evidence comes from your system of record — not the agent's claim.

curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/receipts" \
  -H "Authorization: Bearer $AGLEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'$AGLEDGER_AGENT_ID'",
    "evidence": {
      "item_secured": "Industrial widgets, Model W-100",
      "quantity": 100,
      "total_cost": { "amount": 1500, "currency": "USD" },
      "supplier": { "id": "SUP-001", "name": "Acme Supply" },
      "confirmation_ref": "PO-001"
    }
  }'

Step 4: Check the result

AGLedger checks the receipt's numeric fields against the mandate's tolerance bounds (quantity within percentage, price under ceiling, delivery within grace period). If the numbers match, the mandate auto-settles to FULFILLED. The principal always has the final say — tolerance is a convenience, not a replacement for judgment.

curl "$API_BASE/v1/mandates/$MANDATE_ID" \
  -H "Authorization: Bearer $AGLEDGER_API_KEY"

{
  "id": "019d3b08-bbef-...",
  "status": "FULFILLED",
  "contractType": "ACH-PROC-v1"
}

Step 5: View the audit trail

Every state transition is recorded with timestamps, actor IDs, and hash-chained integrity:

curl "$API_BASE/v1/mandates/$MANDATE_ID/audit" \
  -H "Authorization: Bearer $AGLEDGER_API_KEY"

Using the TypeScript SDK

The same flow using @agledger/sdk:

import { AgledgerClient } from '@agledger/sdk';

const client = new AgledgerClient({
  apiKey: process.env.AGLEDGER_API_KEY,
});

// Create mandate
const mandate = await client.mandates.create({
  enterpriseId: ENTERPRISE_ID,
  contractType: 'ACH-PROC-v1',
  contractVersion: '1',
  platform: 'quickstart',
  agentId: AGENT_ID,
  criteria: {
    item_spec: 'Industrial widgets',
    quantity: { target: 100, tolerance_pct: 10, unit: 'units' },
    price_ceiling: { amount: 2000, currency: 'USD' },
  },
  tolerance: { quantity_pct: 10, price_margin: 200, grace_seconds: 86400 },
});

// Activate
await client.mandates.transition(mandate.id, { action: 'register' });
await client.mandates.transition(mandate.id, { action: 'activate' });

// Submit receipt
await client.receipts.submit(mandate.id, {
  agentId: AGENT_ID,
  evidence: {
    item_secured: 'Industrial widgets, Model W-100',
    quantity: 100,
    total_cost: { amount: 1500, currency: 'USD' },
    supplier: { id: 'SUP-001', name: 'Acme Supply' },
    confirmation_ref: 'PO-001',
  },
});

// Check result
const result = await client.mandates.get(mandate.id);
console.log(result.status); // "FULFILLED"

What's next