# Skalor — Full Reference

> Open infrastructure for AI agents transacting on real money. Four primitives — Mandate, Bureau, Pay, Receipts. MIT-licensed. Live on Base Sepolia today; rail-agnostic by design.

## Mission

Make AI agents safe to deploy on real money. Skalor never holds funds. The
operator's treasury remains with Anchorage / Fireblocks / BitGo / any
qualified custodian; Skalor enforces what an AI agent is allowed to do
with that treasury via Solidity invariants and signed compliance receipts.

## The four primitives

### Mandate
Per-agent on-chain spending guard. Solidity 0.8.24, MIT-licensed. Configurable:
- per_tx_limit          — max wei per transaction
- daily_limit           — max wei per 24h window
- daily_spent           — current 24h cumulative
- last_reset_day        — UTC day index of last reset
- paused                — kill switch (true = no spending allowed)
- spend_nonce           — replay protection
- allowedCounterparties — vendor allowlist mapping
- agent                 — agent's signing key
- controller            — principal's admin key

Function signatures:
- spend(address to, uint256 amount, bytes32 intentHash)
- pause(), unpause()
- setPerTxLimit(uint256), setDailyLimit(uint256)
- addCounterparty(address), removeCounterparty(address)

Custom errors:
- PerTxLimitExceeded()
- DailyLimitExceeded()
- MandatePaused()
- CounterpartyNotAllowed()

Deployed (Base Sepolia, chain ID 84532):
- MandateFactory: 0x61FD854454e954a5B2C2844533A1fbB98eD4aA85
- Mandate (demo): 0xB774bD25Ef8EC3D76f1E024712A6Debb95B1baC3

Source: https://github.com/SkalorAI/skalor-protocol

### Bureau
Federated reputation primitive for AI agents. Open spec (RFC v0.1) at
https://skalor.xyz/rfc/kya-bureau-v0.1. Per-agent records carry a tier
(AAA / AA / A / BBB / BB / B / CCC / UNRATED), a composite bureau_score
(0–850, FICO-style), and six normalized score components.

Score components:
- approval_quality          — approved txs / attempted txs
- gate6_history_quality     — fraction without Gate 6 critical-tier hits
- gate0_attestation_quality — fraction with valid Gate 0 attestation
- settlement_quality        — fraction of cleared txs that settled on-chain
- gate6_enforcement_quality — Gate 6 enforcement mode (off / shadow / soft / strict)
- tenure_quality            — time-since-first-tx normalized over 365d

Wire format:
  skalor_bureau_v1.<base64url(canonical_json_payload)>.<base64url(ed25519_sig)>

### Pay
Three-rail settlement engine.
- Tempo (PathUSD)            — primary, A2A agent settlement
- Base L2 (USDC)             — viem ECDSA + x402 compatible
- Canton (InstitutionalToken) — Daml smart contracts, flag-flipped to live

### Receipts
Every transaction produces an Ed25519-signed receipt. Three types:
- skalor_v1.        — transaction attestation v1
- skalor_v2.        — transaction attestation v2 (adds Gate 0)
- skalor_bureau_v1. — bureau score receipt (per-agent KYA tier)

All three share the same JWKS at https://skalor.xyz/.well-known/skalor-key.json.

Verification surfaces:
- In-browser: https://skalor.xyz/verify
- Shareable: https://skalor.xyz/receipt?r=<receipt>
- Programmatic: @skalor/sdk (npm), skalor-sdk (PyPI)

## Seven fiduciary gates

Every POST /authorize-intent runs 7 gates in order. Fail-fast on first failure:

0. Runtime Attestation — SHA-256 of (model + prompt + tool schema) matches registration
1. Kill Switch         — agents.is_active = TRUE
1.5. OFAC Sanctions    — counterparty not on SDN list
2. Vendor Allowlist    — merchant on agent allowlist
3. Per-Tx Limit        — amount_usd <= configured per-tx cap
4. Daily Budget        — today's cumulative <= daily cap
5. HITL                — human-in-the-loop policy satisfied
6. Behavioral Anomaly  — Phase 1 statistical + Phase 2 ML logistic regression

Failed transactions return:
{
  "decision": "denied",
  "denial_reason": "<gate>: <reason>",
  "gates_passed": [<list>],
  "receipt": "skalor_v2.<payload>.<sig>"
}

## API surface

Base: https://augvmbhpuchkqqowxmrk.supabase.co/functions/v1/

POST /authorize-intent   — 7-gate clearance + settle on rail. Auth: Bearer.
POST /skalor-pay         — A2A settlement. Auth: Bearer.
POST /canton-pay         — Canton rail. Auth: Bearer.
GET  /bureau?agent_id=   — Signed bureau receipt by UUID. Public.
GET  /bureau?did=        — Same, by DID. Public.
GET  /bureau-list        — Public registry browse. Public.
GET  /bureau-lookup      — Cross-org pulls (Phase B). Public.
GET  /bureau-crl         — Signed Certificate Revocation List. Public.
POST /gate6-label        — Operator labeling for Phase 2 training. Auth: Bearer.
POST /webhook-dispatch   — Webhook event dispatch. Auth: Bearer.

## SDKs

TypeScript:
  npm install @skalor/sdk

  import { Client } from "@skalor/sdk";
  const skalor = new Client({ apiKey: process.env.SKALOR_API_KEY });
  const result = await skalor.authorizeIntent({
    agent_id: "<uuid>",
    amount_usd: 100,
    merchant: "vendor.example",
    intent: "Pay for monthly API quota",
  });

Python:
  pip install skalor-sdk

  from skalor import Client
  client = Client(api_key=os.environ["SKALOR_API_KEY"])
  result = client.authorize_spend(
      agent_id="<uuid>",
      amount_usd=100,
      merchant="vendor.example",
      intent="Pay for monthly API quota",
  )

MCP server (mcp.skalor.xyz):
  {
    "mcpServers": {
      "skalor": { "url": "https://mcp.skalor.xyz", "transport": "sse" }
    }
  }

  Available MCP tools:
  - authorize_payment
  - check_budget
  - list_vendors
  - get_agent_score
  - verify_receipt

## Three-rail settlement

Rail   | Stablecoin         | Chain ID | Signing
-------|--------------------|----------|------------------
Tempo  | PathUSD            | 42431    | ECDSA secp256k1
Base   | USDC               | 84532    | ECDSA secp256k1
Canton | InstitutionalToken | Daml     | Ledger party

All rails: Ed25519 attestation receipt is signed on top of the chain-native
signature, providing a unified verification path regardless of rail.

## Receipt verification flow

1. Counterparty receives: receipt = "skalor_v2.<payload>.<sig>"
2. Counterparty fetches:  /.well-known/skalor-key.json
3. Counterparty looks up: kid in payload -> matching JWK
4. Counterparty verifies: Ed25519(payload, sig, jwk.x) == OK
5. If OK, counterparty trusts the gate verdicts and settlement metadata.

No Skalor server round-trip required for step 4. Anyone with the JWKS pinned
locally can verify any Skalor receipt offline.

## Architecture decisions

- We never hold funds. Treasuries stay with the operator's custodian.
- We do not issue a token.
- We do not issue a stablecoin.
- We adopt Catena Labs' ACK-ID and ACK-Pay as the identity + payment
  messaging layer where applicable. We do not fork them.
- Open spec (KYA Bureau RFC v0.1), open reference implementation (MIT).
  Anyone can implement an interoperable Bureau.

## License

MIT. All Skalor source: https://github.com/SkalorAI/skalor-protocol.
The KYA Bureau spec is CC-BY-4.0.

## Contact

founders@skalor.xyz