{
  "integration": {
    "product": "starail",
    "version": "3.7.3",
    "positioning": "Independent Control Plane — evaluate rails before signing. Pay/Payout/Points are optional extensions.",
    "thesis": "Starail controls whether money may move. Your existing stack decides how it moves.",
    "safetyPolicy": {
      "noPrivateKeyCustody": true,
      "signingDisabledByDefault": true,
      "liveExecutionRequiresExplicitEnable": true,
      "kytFailClosed": true
    },
    "auth": {
      "header": "x-starail-api-key",
      "demoKey": "starail_demo_key (development only)",
      "docs": "https://starail-production.up.railway.app/v1/auth/status"
    },
    "modules": [
      {
        "id": "control",
        "name": "Starail Control (Core)",
        "status": "available",
        "layer": "core",
        "entrypoint": "POST /v1/evaluations"
      },
      {
        "id": "sdk",
        "name": "@starail/sdk guard()",
        "status": "available",
        "layer": "core",
        "entrypoint": "guard({ authorization }) before your signer"
      },
      {
        "id": "pay",
        "name": "Starail Pay",
        "status": "available",
        "layer": "extension",
        "entrypoint": "POST /v1/payment_intents"
      },
      {
        "id": "payout",
        "name": "Starail Payout",
        "status": "available",
        "layer": "extension",
        "entrypoint": "POST /v1/payout_intents"
      },
      {
        "id": "points",
        "name": "Starail Points",
        "status": "available",
        "layer": "extension",
        "entrypoint": "POST /v1/point_programs"
      },
      {
        "id": "treasury",
        "name": "Starail Treasury",
        "status": "available",
        "layer": "extension",
        "entrypoint": "GET /v1/balances/treasury"
      },
      {
        "id": "security",
        "name": "Starail Security",
        "status": "available",
        "layer": "ops",
        "entrypoint": "GET /v1/rbac/matrix"
      }
    ],
    "partnerSecurity": {
      "rbac": "GET https://starail-production.up.railway.app/v1/rbac/matrix",
      "apiKeys": "GET|POST https://starail-production.up.railway.app/v1/workspace/api-keys",
      "apiKeyRotate": "POST https://starail-production.up.railway.app/v1/workspace/api-keys/{id}/rotate",
      "slos": "GET https://starail-production.up.railway.app/v1/ops/slos",
      "kytSmoke": "GET https://starail-production.up.railway.app/v1/kyt/smoke",
      "vaultKms": "GET https://starail-production.up.railway.app/v1/vault/kms-readiness",
      "haRunbook": "docs/ha-runbook.md",
      "productionReadiness": "GET https://starail-production.up.railway.app/v1/ops/production-readiness"
    },
    "kytProduction": {
      "status": "GET https://starail-production.up.railway.app/v1/kyt/status",
      "smoke": "GET https://starail-production.up.railway.app/v1/kyt/smoke",
      "env": [
        "STARAIL_KYT_LIVE=true",
        "STARAIL_KYT_ENDPOINT_URL=<vendor-url>",
        "STARAIL_KYT_API_KEY=<vendor-key>",
        "STARAIL_KYT_FAIL_CLOSED_BLOCK=true (optional hard block)"
      ]
    },
    "merchant": [
      "GET https://starail-production.up.railway.app/v1/merchants/{merchantId}/settlement-profile",
      "POST https://starail-production.up.railway.app/v1/merchants/{merchantId}/settlement-profile — upsert settlement methods"
    ],
    "quickstart": {
      "control": [
        "GET https://starail-production.up.railway.app/v1/rails — Rail Registry",
        "POST https://starail-production.up.railway.app/v1/evaluations — Intent → AllowedRailSet + Decision (Idempotency-Key supported)",
        "POST https://starail-production.up.railway.app/v1/decisions/{id}/approvals — attach approval when REQUIRES_APPROVAL",
        "POST https://starail-production.up.railway.app/v1/decisions/{id}/revalidate — pre-sign check + ExecutionAuthorization (audience/executorRef optional)",
        "GET https://starail-production.up.railway.app/v1/decisions/{id}/explain — human-readable reason codes + rule trace",
        "GET https://starail-production.up.railway.app/v1/decisions/{id}/evidence — ControlEvidenceBundle (pre-execution)",
        "GET https://starail-production.up.railway.app/v1/attestations/{decisionId} — portable attestation",
        "POST https://starail-production.up.railway.app/v1/control/loop — one-shot evaluate→approve→revalidate→attest",
        "POST https://starail-production.up.railway.app/v1/reference/protocol/normalize — x402/MPP → ControlIntent fields (not a rail)",
        "GET https://starail-production.up.railway.app/v1/control/errors — reason codes, error types, next actions",
        "GET https://starail-production.up.railway.app/v1/modules/control-bindings — Pay/Payout/Points must ask Control whether",
        "SDK: import { guard, createStarailClient } from \"@starail/sdk\" — verify before your signer"
      ],
      "pay": [
        "POST https://starail-production.up.railway.app/v1/payment_intents — create PaymentIntent (extension)",
        "POST https://starail-production.up.railway.app/v1/payment_intents/{id}/analyze — legacy firewall path",
        "POST https://starail-production.up.railway.app/v1/payment_intents/{id}/confirm — confirm receipt",
        "GET https://starail-production.up.railway.app/checkout/pay/{id} — hosted checkout"
      ],
      "payout": [
        "POST https://starail-production.up.railway.app/v1/payout_intents — create PayoutIntent (extension)",
        "POST https://starail-production.up.railway.app/v1/payout_batches — batch create (up to 50)",
        "POST https://starail-production.up.railway.app/v1/payout_intents/{id}/approve — approval gate",
        "POST https://starail-production.up.railway.app/v1/payout_intents/{id}/reserve — treasury reservation"
      ],
      "points": [
        "POST https://starail-production.up.railway.app/v1/point_programs — create program (extension)",
        "POST https://starail-production.up.railway.app/v1/point_programs/{id}/credit — credit user balance",
        "POST https://starail-production.up.railway.app/v1/point_spend_intents — reserve + spend",
        "POST https://starail-production.up.railway.app/v1/points/shadow/reconcile — shadow vs Starail diff"
      ],
      "webhooks": [
        "POST https://starail-production.up.railway.app/v1/webhooks/endpoints — register receiver",
        "GET https://starail-production.up.railway.app/v1/webhooks/status — delivery monitoring",
        "GET https://starail-production.up.railway.app/v1/ops/worker — unmannedOps readiness",
        "Control events: control.decision.evaluated, control.decision.approved, control.decision.denied, control.decision.attested, control.loop.completed",
        "Product events: payment_intent.created, payment_intent.confirmed, payment_intent.refunded, payment_intent.ledger_posted, payout_intent.created, payout_intent.approved, payout_intent.reserved, point_spend_intent.created, point_spend_intent.captured, point_spend_intent.settled, point_shadow.mismatch"
      ],
      "reference": [
        "POST https://starail-production.up.railway.app/v1/reference/softrouter/optimize-route — optional SoftRouter demo",
        "POST https://starail-production.up.railway.app/v1/reference/nexport/signer-guard — optional NEXPORT demo",
        "POST https://starail-production.up.railway.app/v1/reference/softledger/ingest — optional SoftLedger demo"
      ]
    },
    "surfaces": {
      "console": "https://starail-production.up.railway.app/console",
      "productHub": "https://starail-production.up.railway.app/product-hub (extension demos)",
      "hostedCheckout": "https://starail-production.up.railway.app/checkout/pay/{paymentIntentId}",
      "openapi": "docs/openapi.json (npm run openapi:generate)",
      "verify": "npm run verify:integration",
      "pilotGate": "npm run verify:pilot-readiness"
    },
    "eventCollaboration": {
      "docs": "docs/webhook-partner-setup.md",
      "controlEventTypes": [
        "control.decision.evaluated",
        "control.decision.approved",
        "control.decision.denied",
        "control.decision.attested",
        "control.loop.completed"
      ],
      "productEventTypes": [
        "payment_intent.created",
        "payment_intent.confirmed",
        "payment_intent.refunded",
        "payment_intent.ledger_posted",
        "payout_intent.created",
        "payout_intent.approved",
        "payout_intent.reserved",
        "point_spend_intent.created",
        "point_spend_intent.captured",
        "point_spend_intent.settled",
        "point_shadow.mismatch"
      ],
      "registerEndpoint": "POST https://starail-production.up.railway.app/v1/webhooks/endpoints",
      "onboardingScript": "npm run webhooks:onboard-partner -- --url https://partner.example.com/hook",
      "deliveryStatus": "GET https://starail-production.up.railway.app/v1/webhooks/status",
      "deadLetters": "GET https://starail-production.up.railway.app/v1/webhooks/dead-letters",
      "replayDeadLetters": "POST https://starail-production.up.railway.app/v1/webhooks/dead-letters/replay",
      "replayScript": "npm run webhooks:replay-dead-letters -- --replay",
      "loopbackSink": "GET https://starail-production.up.railway.app/v1/webhooks/sink",
      "opsAlerts": "GET https://starail-production.up.railway.app/v1/ops/alerts",
      "requirements": [
        "HTTPS receiver URL (not ephemeral demo URLs)",
        "webhook_signing secret in vault",
        "STARAIL_WEBHOOK_DELIVERY=true",
        "Dedicated worker with direct pg drain (STARAIL_PG_DRIVER=native)"
      ]
    },
    "unmannedOps": {
      "docs": "docs/unmanned-ops.md",
      "workerStatus": "GET https://starail-production.up.railway.app/v1/ops/worker",
      "workerHealth": "GET <STARAIL_WORKER_URL>/health",
      "apiInlineDrainOff": "STARAIL_INLINE_WEBHOOK_DRAIN=false",
      "apiInlineSchedulerOff": "STARAIL_INLINE_SCHEDULER_SWEEP=false",
      "workerEnv": [
        "STARAIL_RUNTIME=worker",
        "STARAIL_WORKER_INTERVAL_MS=120000",
        "STARAIL_WORKER_MAX_WEBHOOK_EVENTS=50"
      ],
      "documentStore": "native pg pool (STARAIL_PG_DOCUMENT_DRIVER=psql to roll back)",
      "runbooks": [
        "npm run webhooks:onboard-partner -- --url <partner-url>",
        "npm run webhooks:replay-dead-letters -- --replay"
      ]
    },
    "embed": {
      "discovery": "GET https://starail-production.up.railway.app/v1/product/embed",
      "stack": "GET https://starail-production.up.railway.app/v1/product/stack",
      "canonicalUnits": "GET https://starail-production.up.railway.app/v1/money/canonical-units"
    }
  }
}