Documentation

Discovery is free and needs no account. Point it at a public endpoint:

POST https://api.usepreflight.xyz/api/v1/discover
content-type: application/json

{ "endpoint": "https://api.your-service.com/mcp" }

Discovery returns the observed surface and a proposed manifest with per field provenance. Confirm the manifest, then run the paid check from your agent (below). You receive a private report link.

Release manifest

What you intend to publish: endpoint, interface, payment terms, request and response contracts.

Observed surface

What the live service actually exposes right now.

Criterion

One comparison of declared against observed, with a state and evidence.

Buyer proof

The steps where PreFlight pays and takes delivery as a real customer.

Decision

RELEASE, BLOCK, or UNKNOWN, scoped to a single runtime snapshot.

Criteria are grouped: target, interface, payment, contract, and buyer proof. Each carries a stable code (for example PAY-04), a state, the declared and observed values, provenance, the consequence, and the exact fix.

You can pass an OKX.AI Agent ID or a raw endpoint. When an Agent ID is given, PreFlight resolves the listing to its live endpoint and pre fills the manifest fields it can observe, marking each with its source.

PreFlight confirms the declared endpoint resolves over HTTPS, answers the declared method, and follows only the declared redirect policy. A method or redirect mismatch contradicts the release.

For a paid service, PreFlight reads the HTTP 402 challenge and checks that its mode, network, asset, amount, and payTo match your declaration. It then authorizes a real x402 payment as a buyer.

After authorizing, PreFlight confirms the payment settles on X Layer, rather than trusting a claim. The BUYER_SETTLEMENT criterion carries the settlement evidence.

Once paid, PreFlight takes delivery and checks the returned result against your response contract, and confirms a duplicate payment replay is rejected. The BUYER_DELIVERY criterion carries the delivery evidence.

The paid check. Your agent posts the confirmed manifest and completes the x402 challenge.

POST https://api.usepreflight.xyz/api/v1/verify-release
content-type: application/json

{
  "schema_version": "preflight.verify-release-request.v1",
  "manifest": {
    "schema_version": "preflight.release-manifest.v1",
    "release": { "service_name": "quote-svc", "release_version": "2026.07.1" },
    "target": {
      "endpoint": "https://api.your-service.com/mcp",
      "method": "POST",
      "interface_mode": "X402_HTTP",
      "redirect_policy": "NONE"
    },
    "payment": {
      "mode": "X402",
      "network": "eip155:196",
      "asset": "0x779ded0c9e1022225f8e0630b35a9b54be713736",
      "amount_atomic": "100000",
      "pay_to": "0xYOUR_DECLARED_ADDRESS"
    }
  }
}

The response is the report envelope (see Report schema). The private report URL and its access token are returned in report_access.

A compact machine report is available for CI. The process exit code carries the decision, so a pipeline can gate a release:

$ preflight verify https://api.example.com/mcp
# exit code carries the decision:
#   0  RELEASE
#   1  BLOCK
#   2  UNKNOWN
#   3  infrastructure error (could not run)

Every check issues an Ed25519 signed receipt. It carries the decision, the manifest and snapshot hashes it judged, the policy version, and the signing key ID. Anyone can verify it against PreFlight's published keys, offline of the report.

{
  "receipt_id": "rcpt_…",
  "payload": {
    "type": "preflight.receipt.v1",
    "report_id": "pfr_…",
    "decision": "RELEASE",
    "manifest_hash": "sha256:…",
    "snapshot_hash": "sha256:…",
    "policy_version": "preflight.release-policy.v1",
    "issued_at": "…",
    "key_id": "preflight-v4-production-20260713"
  },
  "signature": "base64…",
  "signature_alg": "Ed25519",
  "key_id": "preflight-v4-production-20260713",
  "verify": {
    "canonicalization": "preflight.canonical-json.v1",
    "payload_hash": "sha256:…",
    "pubkeys_url": "https://api.usepreflight.xyz/api/v1/pubkeys"
  }
}

Verification is four steps, and the report page runs them in your browser:

# 1. canonicalize the payload (sorted keys, no whitespace)
# 2. sha256 the canonical bytes  -> must equal verify.payload_hash
# 3. fetch the matching key from verify.pubkeys_url by key_id
# 4. Ed25519 verify(signature, canonical_bytes, public_key)
preflight verify-receipt rcpt_…   # exit 0 when authentic

Public keys are served at /api/v1/pubkeys, and a receipt envelope by ID at /api/v1/receipts/{id}. A RELEASE also issues an embeddable badge; see the CLI to verify from a terminal.

PreFlight ships an MCP wrapper so an agent can run a release check as a tool. The tool takes an endpoint and returns the decision, the report ID, and the receipt ID.

// PreFlight exposed as an MCP tool
{
  "name": "verify_release",
  "description": "Prove a live agent service is sellable end to end.",
  "input_schema": {
    "type": "object",
    "properties": { "endpoint": { "type": "string" } },
    "required": ["endpoint"]
  }
}
// returns { decision, report_id, receipt_id, badge_url }

The same 0.10 USDT x402 payment applies. The agent's wallet pays, and the signed receipt comes back with the result.

The report envelope, abbreviated:

{
  "schema_version": "preflight.release-report.v1",
  "report_id": "pfr_…",
  "decision": "RELEASE | BLOCK | UNKNOWN",
  "summary": { "matched": 11, "contradictions": 0, "unknown": 0, "not_applicable": 3 },
  "criterion_groups": [
    { "code": "buyer_proof", "label": "Buyer proof", "criteria": [
      { "code": "BUYER_SETTLEMENT", "state": "MATCH", "mandatory": true,
        "expected": true, "observed": { "status": "DELIVERED" },
        "provenance": ["OPERATOR_SUPPLIED","OBSERVED","DERIVED"],
        "comparison_rule": "authorized outbound x402 proof settles to the declared target payTo",
        "evidence_refs": [ { "id": "…", "digest": "sha256:…", "captured_at": "…" } ] }
    ] }
  ],
  "runtime_snapshot": { "snapshot_hash": "sha256:…", "captured_at": "…", "requested_url": "…" },
  "policy_version": "preflight.release-policy.v1",
  "report_expires_at": "…"
}

429 on discovery

Free discovery is rate limited per IP. Wait and retry, or run the full check from your agent.

Report link does not open

Reports expire after 30 days and open only with the full capability link, including the part after the #.

A decision looks wrong

Open the evidence under the criterion. If the observed value does not match your understanding of production, send the report ID, never the token.

Capability tokens

Sent in the URL fragment, never to a server, log, or analytics.

Keys

PreFlight signs its own buyer payments. Your agent signs yours. No key you hold reaches PreFlight.

Scope

Public runtime only, over the declared method. No authentication bypass.

See privacy for retention and storage.