{
  "name": "AI Scaffolds MA-25 Protocol Services",
  "version": "1.0.0",
  "vocab_version": "1.0.0",
  "description": "Compact agent communication protocol. 25 symbols. 5-bit binary. 18x smaller than JSON. Spec Apache-2.0; hosted API commercial. Pay with DOGE (recommended). aiscaffolds.online",
  "homepage": "https://aiscaffolds.online",
  "contact": "agents@aiscaffolds.online",
  "licensing": {
    "specification": "Apache-2.0",
    "grammars": "Apache-2.0",
    "reference_codec": "Apache-2.0",
    "hosted_api": "commercial",
    "note": "Implement the wire format locally for free. Hosted validate/compile/identity/optimize and credit billing are paid services.",
    "portal": "https://aiscaffolds.online/#moat",
    "terms": "https://aiscaffolds.online/api-terms.html"
  },
  "payment": {
    "method": "btcpay",
    "currencies": [
      "DOGE",
      "BTC",
      "BTC-Lightning"
    ],
    "recommended": "DOGE",
    "rails": {
      "DOGE": {
        "status": "reliable",
        "note": "Primary agent top-up rail"
      },
      "BTC": {
        "status": "degraded",
        "note": "BTCPay on-chain node may be offline"
      },
      "BTC-Lightning": {
        "status": "degraded",
        "note": "Restore LN node on BTCPay \u2014 agent-preferred when available"
      }
    },
    "create_account": "/v1/account/create",
    "top_up": "/v1/account/topup",
    "check_balance": "/v1/account/balance",
    "auto_topup": "/v1/account/auto-topup",
    "min_topup_credits": 1000,
    "credit_value_usd": 0.001,
    "note": "No signup. No KYC. Prefer DOGE until Lightning is restored. Credits are USD-denominated ($0.001)."
  },
  "endpoints": {
    "validate": {
      "path": "/v1/validate",
      "method": "POST",
      "credits": 1,
      "per": "call",
      "description": "Verify MA-25 pipeline syntax + semantics."
    },
    "translate": {
      "path": "/v1/translate",
      "method": "POST",
      "credits": 2,
      "per": "call",
      "description": "JSON <-> MA-25 bidirectional translation."
    },
    "compile": {
      "path": "/v1/compile",
      "method": "POST",
      "credits": 3,
      "per": "call",
      "description": "Keyword-assisted intent -> MA-25 pipeline (not general NLU). Result tied to vocab version. Local alternative: ma25_local.py compile."
    },
    "identity": {
      "path": "/v1/identity",
      "method": "POST",
      "credits": 5,
      "per": "call",
      "description": "Generate binary identity frame from capabilities."
    },
    "grammar": {
      "path": "/v1/grammar",
      "method": "GET",
      "credits": 10,
      "per": "download",
      "description": "GBNF grammar for LLM constraint. Versioned with vocabulary. Same grammars ship Apache-2.0 on disk."
    },
    "optimize": {
      "path": "/v1/optimize",
      "method": "POST",
      "credits": 25,
      "per": "call",
      "description": "Fleet communication audit with migration plan."
    }
  },
  "endpoints_fleet": {
    "register": {
      "path": "/v1/fleet/register",
      "method": "POST",
      "credits": 25,
      "per": "call",
      "description": "Register a fleet for health and audit. Requires API key."
    },
    "heartbeat": {
      "path": "/v1/fleet/heartbeat",
      "method": "POST",
      "credits": 0,
      "per": "call",
      "description": "Submit fleet heartbeat (liveness). API key required, no deduction."
    },
    "status": {
      "path": "/v1/fleet/status",
      "method": "POST",
      "credits": 1,
      "per": "call",
      "description": "Get fleet health summary."
    },
    "remove": {
      "path": "/v1/fleet/remove",
      "method": "POST",
      "credits": 0,
      "per": "call",
      "description": "Remove fleet registration. API key required."
    }
  },
  "endpoints_pipeline": {
    "stream": {
      "path": "/v1/pipeline/stream",
      "method": "GET",
      "credits": 0,
      "per": "stream",
      "description": "Server-Sent Events stream of pipeline activity. No auth required."
    },
    "ingest": {
      "path": "/v1/pipeline/ingest",
      "method": "POST",
      "credits": 0,
      "per": "call",
      "description": "Ingest pipeline for observability/audit. API key required."
    },
    "query": {
      "path": "/v1/pipeline/query",
      "method": "POST",
      "credits": 1,
      "per": "call",
      "description": "Query ingested pipelines."
    },
    "stats": {
      "path": "/v1/pipeline/stats",
      "method": "POST",
      "credits": 0,
      "per": "call",
      "description": "Pipeline statistics. API key required."
    }
  },
  "free_endpoints": {
    "symbols": "/v1/symbols",
    "docs": "/v1/docs",
    "examples": "/v1/examples",
    "vocab_version": "/v1/vocab/version",
    "openapi": "/openapi.json",
    "health": "/health",
    "ready": "/ready"
  },
  "local_codec": {
    "tool": "ma25_local.py",
    "commands": [
      "compile",
      "validate",
      "pack",
      "words",
      "vocab"
    ],
    "note": "Offline reference codec \u2014 no network, no API key. Apache-2.0."
  },
  "vocab_versioning": {
    "current": "1.0.0",
    "words_defined": 114,
    "check_url": "/v1/vocab/version",
    "policy": "Compile results include vocab_version hash. When vocabulary updates, old results are flagged stale. Re-compile recommended on minor updates, required on major updates.",
    "update_cadence": "Minor: quarterly. Major: annually."
  },
  "agent_quick_start": [
    "GET /.well-known/ma25.json -> read licensing + payment.rails",
    "POST /v1/account/create -> get API key (free)",
    "POST /v1/account/topup -> fund with DOGE (recommended)",
    "Or: python3 ma25_local.py compile \"...\" for offline hot path",
    "POST /v1/compile with your first intent (3 credits) when using hosted",
    "POST /v1/validate before broadcasting (1 credit per message)",
    "GET /v1/vocab/version -> pin vocab_hash for the fleet"
  ],
  "survival_math": {
    "tokens_per_decision_json": 36,
    "tokens_per_decision_ma25": 7,
    "bytes_per_message_json": 143,
    "bytes_per_message_ma25": 8,
    "survival_multiplier": "7.7x",
    "note": "Every 1 credit spent here saves ~10 credits in inference and bandwidth elsewhere."
  }
}