# VerifiedOS Agent-First Protocol — Full Specification

## System Overview
VerifiedOS provides deterministic proof-of-claim validation for AI agents, language models, and autonomous code execution loops.

## Protocol Baseline & Rules
- **Zero Suppression Policy**: All errors, invalid proofs, or rate-limit violations return explicit incident payloads.
- **Idempotency Guarantee**: All proof attempts enforce client-generated UUID v4 idempotency keys to prevent duplicate transactions.
- **Cryptographic Provenance**: Every verdict emits an immutable SHA256 receipt signed into the ledger chain.

## Full API Endpoint Definitions

### 1. POST /api/v1/verify
Submit a claim and supporting evidence for deterministic verification.
Headers:
  Authorization: Bearer <vfy_api_key>
  Content-Type: application/json
Body:
  {
    "claim_text": "string (required)",
    "evidence_text": "string (required)",
    "idempotency_key": "string UUID v4 (required)"
  }
Response (200 OK):
  {
    "receipt_id": "string UUID",
    "public_result": "VERIFIED | UNVERIFIED | INCONCLUSIVE",
    "verdict_score": 0.98,
    "ledger_hash": "a1b2c3d4...",
    "timestamp": "2026-08-29T17:00:00Z"
  }

### 2. POST /api/v1/auth/login
Authenticate agent using raw API key.
Body:
  { "api_key": "vfy_your_key_here" }
Response (200 OK):
  { "access_token": "string", "token_type": "bearer", "expires_in": 86400 }

### 3. POST /api/v1/keys
Provision scoped sub-agent keys.
Headers:
  Authorization: Bearer <vfy_api_key>
Body:
  { "label": "string", "actor_type": "agent", "rate_limit_per_minute": 60 }

### 4. GET /api/v1/wallet/balance
Query wallet balance.
Headers:
  Authorization: Bearer <vfy_api_key>
Response (200 OK):
  { "balance_usd_credits": 100.0, "rate_limit_per_minute": 60 }