{ "openapi": "3.1.0", "info": { "title": "FLINT Agent Transaction Control API", "version": "1.0.0", "description": "FLINT verifies agent authority before autonomous economic activity, issues signed verification records, accepts outcome feedback, and returns partner-safe Trust Graph reputation.", "license": { "name": "Proprietary", "identifier": "LicenseRef-FLINT-Proprietary" } }, "servers": [ { "url": "https://flint.network", "description": "Production" } ], "security": [], "tags": [ { "name": "Verification Records", "description": "Issue and verify signed verification records." }, { "name": "Outcome Feedback", "description": "Submit transaction outcomes that seed Trust Graph reputation." }, { "name": "Trust Graph", "description": "Read partner-safe aggregate agent reputation and graph health." }, { "name": "Agent Passport", "description": "Issue, resolve, and update Agent Passports: hybrid-signed agent identity credentials with a separate mutable mandate." } ], "paths": { "/api/passport": { "post": { "x-flint-release-state": "production", "tags": ["Agent Passport"], "operationId": "issueAgentPassport", "summary": "Issue an Agent Passport", "description": "Issues a hybrid-signed (ES256 + ML-DSA-65) Agent Passport that binds an agent to its controller and wallet. The passport signs identity only; the mandate is a separate, unsigned, mutable config. Persists the passport, seeds the Trust Graph, and returns a public resolvable id. Free and per-IP rate limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportIssueRequest" } } } }, "responses": { "200": { "description": "Passport issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/passport/{passport_id}": { "get": { "x-flint-release-state": "production", "tags": ["Agent Passport"], "operationId": "resolveAgentPassport", "summary": "Resolve a public Agent Passport", "description": "Returns the signed passport envelope, decoded identity, current mandate, and a verification summary (signature valid, status, not expired).", "parameters": [ { "name": "passport_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^kya_" }, "description": "Passport id (kya_ prefix + ULID)." } ], "responses": { "200": { "description": "Passport resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportResponse" } } } }, "404": { "description": "Passport not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "x-flint-release-state": "production", "security": [ {}, { "WorkOSOwnerSession": [] } ], "tags": ["Agent Passport"], "operationId": "updateAgentMandate", "summary": "Update a mandate or authorize a Shopify purchase", "description": "Updates the mutable mandate, or lets the authenticated Passport owner issue a short-lived, signed Shopify purchase authorization.", "parameters": [ { "name": "passport_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^kya_" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MandateUpdateRequest" }, { "$ref": "#/components/schemas/PurchaseAuthorizationRequest" } ] } } } }, "responses": { "200": { "description": "Mandate updated; passport signature unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateUpdateResponse" } } } }, "201": { "description": "Purchase authorization issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseAuthorizationResponse" } } } }, "404": { "description": "Passport not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/verify": { "post": { "x-flint-release-state": "production", "tags": ["Verification Records"], "operationId": "issueAuthorizationRecord", "summary": "Issue a signed verification record", "description": "Use before an AI agent initiates a payment, paid API call, checkout action, stablecoin transfer, x402 request, or delegated commercial transaction. Returns a compact JWS signed verification record.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "examples": { "agentPayment": { "summary": "Agent payment authorization", "value": { "nonce": "8b2ef62d-6ec0-4ac8-a5e4-e6d4ec447bcf", "timestamp": "2026-05-20T16:00:00.000Z", "partner_id": "sandbox_public", "merchant_reference": "invoice_123", "transaction": { "amount_display": "42.00", "asset": "USDC", "chain": "eip155:8453", "counterparty_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "declared_scope": { "max_amount_per_tx_display": "250.00", "allowed_counterparties": ["invoice_123"], "time_window_end": "2026-05-20T17:00:00.000Z" }, "agent_claim": { "agent_id": "agent_checkout_worker", "principal_hint": "skyfire", "agent_runtime_hint": "browser" } } } } } } }, "responses": { "200": { "description": "Compact JWS signed verification record", "headers": { "X-FLINT-Verdict": { "schema": { "$ref": "#/components/schemas/VerdictDecision" } }, "X-FLINT-Score": { "schema": { "type": "string" } } }, "content": { "application/jwt": { "schema": { "type": "string", "description": "Compact JWS containing the signed verification record." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/x402/scan": { "post": { "x-flint-release-state": "staging", "security": [ {}, { "X402Payment": [] } ], "tags": ["Verification Records"], "operationId": "purchasePreTransactionScan", "summary": "Pay for and execute a bounded pre-transaction scan", "description": "x402 resource for autonomous buyers. The x402 payment purchases FLINT's scan service; the request body describes a separate intended commerce transaction that has not executed. Unknown callers receive bounded deterministic evaluation without external provider or model calls. A verified FLINT Agent Passport bound to the x402 payer wallet can upgrade authority evidence.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ScanRequest" }, "examples": { "agentTransaction": { "value": { "nonce": "scan-01K3J6M2F7H8Q9R0S1T2V3W4X5", "timestamp": "2026-08-25T22:00:00.000Z", "transaction": { "action": "stablecoin_transfer", "reference": "invoice_123", "chain": "eip155:8453", "token": { "symbol": "USDC", "issuer": "circle" }, "amount_display": "24.50", "counterparty_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "agent_claim": { "agent_id": "procurement-agent-7", "agent_runtime_hint": "x402_buyer", "wallet_type": "eoa" } } } } } } }, "responses": { "200": { "description": "The service payment settled and FLINT returned a signed pre-transaction decision record.", "headers": { "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" }, "X-FLINT-Score": { "$ref": "#/components/headers/FlintScore" }, "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ScanResponse" } } } }, "402": { "$ref": "#/components/responses/X402PaymentRequired" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "The verified payment did not provide a bindable payer wallet, or a presented Passport is terminally ineligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "431": { "$ref": "#/components/responses/BadRequest" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/x402/verify": { "post": { "x-flint-release-state": "production", "security": [ {}, { "X402Payment": [], "FlintCapability": [], "DPoP": [] } ], "tags": ["Verification Records"], "operationId": "purchaseAgentAuthorityVerification", "summary": "Pay for metered agent-authority verification", "description": "High-assurance x402 lane. The unpaid challenge is bounded. A paid retry must present a request-bound FLINT capability and DPoP proof before facilitator, provider, model, or record work becomes eligible.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Canonical x402 v2 payment proof on the paid retry." }, { "name": "FLINT-CAPABILITY", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Short-lived Passport-owner-issued capability bound to the exact paid request. Required when payment is presented." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Fresh caller proof bound to the capability, request, and x402 payment proof. Required when payment is presented." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402VerifyRequest" } } } }, "responses": { "200": { "description": "Payment settled and FLINT issued a signed verification record. Receipt state is reported separately and truthfully.", "headers": { "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" }, "X-FLINT-Score": { "$ref": "#/components/headers/FlintScore" }, "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402VerifyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/X402PaymentRequired" }, "403": { "description": "The paid retry failed capability, DPoP, replay, or caller-admission policy before expensive work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/x402/readiness": { "get": { "x-flint-release-state": "production", "tags": ["Verification Records"], "operationId": "getX402Readiness", "summary": "Get non-secret x402 readiness", "description": "Returns configuration state and booleans for the high-assurance Verify lane and separately pinned marketplace scan lane. This route performs no provider call and returns no credential-derived value.", "responses": { "200": { "description": "Bounded non-secret readiness state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ReadinessResponse" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/api/x401/verify": { "post": { "x-flint-release-state": "production", "security": [ {}, { "X401Proof": [] } ], "tags": ["Verification Records"], "operationId": "verifyX401PrincipalPresentation", "summary": "Verify an x401 principal-identity presentation", "description": "Without PROOF-RESPONSE, returns a signed OpenID4VP proof challenge. With a valid presentation, verifies the principal, issues a signed verification record, and returns proof-result metadata.", "parameters": [ { "name": "PROOF-RESPONSE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64url-encoded x401 proof response. Omit to request a challenge." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "200": { "description": "Principal presentation verified and signed record issued.", "headers": { "PROOF-RESULT": { "$ref": "#/components/headers/X401ProofResult" }, "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" }, "X-FLINT-Score": { "$ref": "#/components/headers/FlintScore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401VerifyResponse" } } } }, "400": { "description": "Invalid request or presentation.", "headers": { "PROOF-RESULT": { "$ref": "#/components/headers/X401ProofResult" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401ProofResult" } } } }, "401": { "description": "Proof challenge required.", "headers": { "PROOF-REQUEST": { "$ref": "#/components/headers/X401ProofRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401ChallengeResponse" } } } }, "409": { "description": "The x401 verifier nonce was already used.", "headers": { "PROOF-RESULT": { "$ref": "#/components/headers/X401ProofResult" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X401ProofResult" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/records/{record_id}": { "get": { "x-flint-release-state": "production", "tags": ["Verification Records"], "operationId": "getVerificationRecord", "summary": "Retrieve a signed verification record", "description": "Returns the portable hybrid envelope by default, a bare ES256 compact JWS for format=jws, or a decoded inspection view for format=decoded. The decoded view is not itself signed.", "parameters": [ { "$ref": "#/components/parameters/RecordId" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["decoded", "jws"] }, "description": "Omit for the portable hybrid envelope." } ], "responses": { "200": { "description": "Stored record in the requested representation.", "headers": { "X-FLINT-Verdict": { "$ref": "#/components/headers/FlintVerdict" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/HybridEnvelopeWithAcknowledgments" }, { "$ref": "#/components/schemas/DecodedRecordResponse" } ] } }, "application/jwt": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/records/{record_id}/acknowledge": { "post": { "x-flint-release-state": "production", "tags": ["Verification Records"], "operationId": "acknowledgeVerificationRecord", "summary": "Attach a counterparty acknowledgment", "description": "Stores bounded counterparty acknowledgment evidence beside the immutable record. Unsupported or invalid signatures are retained as unverified claims and are never represented as cryptographically verified.", "parameters": [{ "$ref": "#/components/parameters/RecordId" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordAcknowledgmentRequest" } } } }, "responses": { "201": { "description": "Acknowledgment stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordAcknowledgmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Acknowledgment submission rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/records/schema": { "get": { "x-flint-release-state": "production", "tags": ["Verification Records"], "operationId": "getVerificationRecordSchema", "summary": "Get the verification-record JSON Schema", "description": "Returns the canonical JSON Schema for the payload carried by a FLINT hybrid signing envelope.", "responses": { "200": { "description": "JSON Schema draft 2020-12 document.", "content": { "application/schema+json": { "schema": { "type": "object" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/api/settlement-receipts/{receipt_id}": { "get": { "x-flint-release-state": "staging", "tags": ["Verification Records"], "operationId": "getSettlementReceipt", "summary": "Retrieve a linked x402 settlement receipt", "description": "Returns the portable purpose-separated hybrid receipt envelope by default, a bare ES256 compact JWS for format=jws, or a decoded inspection view for format=decoded.", "parameters": [ { "$ref": "#/components/parameters/SettlementReceiptId" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["decoded", "jws"] }, "description": "Omit for the portable hybrid envelope." } ], "responses": { "200": { "description": "Stored settlement receipt in the requested representation.", "headers": { "X-FLINT-Artifact-Type": { "description": "Always x402_settlement_receipt for a successful response.", "schema": { "type": "string", "const": "x402_settlement_receipt" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/HybridEnvelope" }, { "$ref": "#/components/schemas/DecodedSettlementReceiptResponse" } ] } }, "application/jwt": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/outcomes": { "post": { "x-flint-release-state": "production", "tags": ["Outcome Feedback"], "operationId": "submitTransactionOutcome", "summary": "Submit transaction outcome feedback", "description": "Use after a transaction completes, is disputed, or is flagged. Outcome feedback updates durable storage and Trust Graph reputation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeRequest" } } } }, "responses": { "201": { "description": "Outcome accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/graph/agent/{flint_agent_id}": { "get": { "x-flint-release-state": "production", "tags": ["Trust Graph"], "operationId": "lookupAgentReputation", "summary": "Lookup partner-safe aggregate agent reputation", "description": "Returns partner-facing aggregate reputation for a partner-scoped FLINT agent ID. Raw runtime provider identifiers and internal signal fields are not returned.", "parameters": [ { "name": "flint_agent_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^faid_[a-f0-9]{24}$" }, "description": "Partner-scoped FLINT agent identifier." } ], "responses": { "200": { "description": "Agent reputation summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReputationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/graph/health": { "get": { "x-flint-release-state": "production", "tags": ["Trust Graph"], "operationId": "getTrustGraphHealth", "summary": "Check Trust Graph health", "description": "Operational endpoint that checks Trust Graph configuration and connectivity.", "responses": { "200": { "description": "Trust Graph is reachable or intentionally unconfigured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphHealthResponse" } } } }, "502": { "$ref": "#/components/responses/BadGateway" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/.well-known/jwks.json": { "get": { "x-flint-release-state": "production", "tags": ["Verification Records"], "operationId": "getJwks", "summary": "Get FLINT public signing keys", "description": "Returns the public JWKS used to verify compact JWS signed verification records.", "responses": { "200": { "description": "JSON Web Key Set", "content": { "application/json": { "schema": { "type": "object", "required": ["keys"], "properties": { "keys": { "type": "array", "items": { "type": "object" } } } } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } }, "/.well-known/flint.json": { "get": { "x-flint-release-state": "production", "tags": ["Trust Graph"], "operationId": "getFlintTrustManifest", "summary": "Get FLINT Trust Manifest", "description": "Returns this domain's Trust Manifest for agent commerce authorization semantics.", "responses": { "200": { "description": "FLINT Trust Manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustManifest" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } } }, "components": { "schemas": { "VerifyRequest": { "type": "object", "required": ["nonce", "timestamp", "transaction"], "properties": { "nonce": { "type": "string", "minLength": 8, "description": "Unique replay-protection nonce. UUID v4 is recommended." }, "timestamp": { "type": "string", "format": "date-time", "description": "Request timestamp. Must be within the server replay-protection window." }, "partner_id": { "type": "string", "default": "sandbox_public", "description": "Merchant or platform identifier used for partner-scoped public IDs." }, "merchant_reference": { "type": "string", "description": "Merchant transaction, invoice, or API access reference." }, "transaction": { "$ref": "#/components/schemas/TransactionIntent" }, "declared_scope": { "$ref": "#/components/schemas/AuthorizationScope" }, "agent_claim": { "$ref": "#/components/schemas/AgentClaim" } } }, "X402ScanRequest": { "type": "object", "additionalProperties": false, "required": ["nonce", "timestamp", "transaction"], "properties": { "nonce": { "type": "string", "minLength": 8, "maxLength": 128 }, "timestamp": { "type": "string", "format": "date-time" }, "passport_id": { "type": "string", "description": "Optional FLINT Agent Passport. Authority credit requires server verification and a match to the verified x402 payer wallet." }, "merchant_reference": { "type": "string" }, "transaction": { "type": "object", "additionalProperties": false, "required": ["action", "chain", "amount_display", "counterparty_address"], "properties": { "action": { "type": "string", "maxLength": 128 }, "reference": { "type": "string" }, "chain": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_A-Za-z0-9]{1,32}$" }, "token": { "type": "object", "additionalProperties": false, "properties": { "symbol": { "type": "string" }, "issuer": { "type": "string" }, "contract": { "type": "string" } } }, "amount_display": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,18})?$" }, "counterparty_address": { "type": "string" }, "direction": { "type": "string" } } }, "agent_claim": { "$ref": "#/components/schemas/X402ScanAgentClaim" } } }, "X402ScanAgentClaim": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string", "maxLength": 256 }, "agent_runtime_hint": { "type": "string", "maxLength": 256 }, "wallet_type": { "type": "string", "maxLength": 256 } } }, "X402ScanResponse": { "type": "object", "required": ["ok", "verdict", "score", "record_id", "signed_record", "scan", "service_payment"], "properties": { "ok": { "const": true }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "top_reasons": { "type": "array", "items": { "type": "string" } }, "record_id": { "type": "string", "pattern": "^frv_" }, "signed_record": { "type": "string" }, "record": { "type": "object" }, "scan": { "type": "object", "required": ["profile", "status", "transaction_intent_commitment", "payer_wallet_commitment", "external_provider_calls", "model_calls", "bounded_paid_path_executed", "external_provider_path_executed", "record_persisted", "record_persistence_status", "replay_protection_status", "trust_graph_ingest_attempted", "passport_upgraded"], "properties": { "profile": { "const": "marketplace_basic_v1" }, "status": { "const": "completed" }, "transaction_intent_commitment": { "type": "string", "pattern": "^sha256_[a-f0-9]{64}$" }, "payer_wallet_commitment": { "type": "string", "pattern": "^sha256_[a-f0-9]{64}$" }, "external_provider_calls": { "const": 0 }, "model_calls": { "const": 0 }, "bounded_paid_path_executed": { "const": true }, "external_provider_path_executed": { "const": false }, "record_persisted": { "type": "boolean" }, "record_persistence_status": { "enum": ["persisted", "unavailable"] }, "replay_protection_status": { "enum": ["completed", "unavailable"] }, "trust_graph_ingest_attempted": { "type": "boolean" }, "passport_upgraded": { "type": "boolean" } } }, "service_payment": { "type": "object", "required": ["purpose", "status", "distinct_from_scanned_transaction", "receipt_status", "receipt_id"], "properties": { "purpose": { "const": "flint_transaction_scan_service_fee" }, "status": { "const": "settled" }, "distinct_from_scanned_transaction": { "const": true }, "receipt_status": { "enum": ["issued", "unavailable", "disabled"] }, "receipt_id": { "type": ["string", "null"] } } }, "settlement_receipt": { "type": ["object", "null"] }, "compliance": { "type": "object" } } }, "X402VerifyRequest": { "allOf": [ { "$ref": "#/components/schemas/VerifyRequest" }, { "type": "object", "required": ["agent_claim"], "properties": { "passport_id": { "type": "string", "pattern": "^kya_", "description": "Optional verified Agent Passport used by the owner-issued preflight capability." }, "agent_claim": { "$ref": "#/components/schemas/AgentClaim" } } } ] }, "X402VerifyResponse": { "type": "object", "required": ["ok", "verdict", "score", "record_id", "signed_record", "record", "receipt_status", "settlement_receipt"], "properties": { "ok": { "const": true }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "top_reasons": { "type": "array", "items": { "type": "string" } }, "record_id": { "type": "string", "pattern": "^frv_" }, "signed_record": { "type": "string", "description": "ES256 compact JWS for the authorization record." }, "record": { "$ref": "#/components/schemas/HybridEnvelope" }, "step_up": { "type": "object" }, "compliance": { "type": "object" }, "receipt_status": { "type": "string", "enum": ["issued", "unavailable", "disabled", "not_issued"] }, "settlement_receipt": { "oneOf": [ { "type": "object", "required": ["receipt_id", "record", "idempotent"], "properties": { "receipt_id": { "type": "string", "pattern": "^fsr_" }, "record": { "$ref": "#/components/schemas/HybridEnvelope" }, "idempotent": { "type": "boolean" } } }, { "type": "null" } ] } } }, "HybridEnvelope": { "type": "object", "required": ["jws"], "properties": { "envelope_version": { "type": ["string", "null"], "example": "hybrid-v0" }, "jws": { "type": "string", "description": "ES256 compact JWS." }, "pq_signature": { "type": ["string", "null"], "description": "Parallel ML-DSA-65 signature when configured." }, "pq_kid": { "type": ["string", "null"] }, "pq_alg": { "type": ["string", "null"] } } }, "RecordAcknowledgment": { "type": "object", "required": ["received_at", "acknowledger", "signature_status", "method"], "properties": { "received_at": { "type": "string", "format": "date-time" }, "acknowledger": { "type": "object", "required": ["agent_id", "passport_id", "wallet_address"], "properties": { "agent_id": { "type": "string", "maxLength": 256 }, "passport_id": { "type": ["string", "null"], "maxLength": 256 }, "wallet_address": { "type": ["string", "null"], "maxLength": 256 } } }, "signature_status": { "type": "string", "enum": ["verified", "unverified_claim"] }, "method": { "type": "string", "enum": ["none", "es256_jws", "eip191_wallet", "unsupported"] } } }, "HybridEnvelopeWithAcknowledgments": { "allOf": [ { "$ref": "#/components/schemas/HybridEnvelope" }, { "type": "object", "required": ["acknowledgments"], "properties": { "acknowledgments": { "type": "array", "items": { "$ref": "#/components/schemas/RecordAcknowledgment" } } } } ] }, "DecodedRecordResponse": { "type": "object", "required": ["header", "envelope_version", "pq_signature", "record", "acknowledgments", "settlement_receipt"], "properties": { "header": { "type": "object" }, "envelope_version": { "type": ["string", "null"] }, "pq_signature": { "type": "object", "required": ["present"], "properties": { "present": { "type": "boolean" }, "alg": { "type": ["string", "null"] }, "kid": { "type": ["string", "null"] } } }, "record": { "type": "object", "description": "Decoded record payload. This view is not itself signed." }, "acknowledgments": { "type": "array", "items": { "$ref": "#/components/schemas/RecordAcknowledgment" } }, "settlement_receipt": { "oneOf": [ { "type": "object", "required": ["receipt_id", "href"], "properties": { "receipt_id": { "type": "string", "pattern": "^fsr_" }, "href": { "type": "string" } } }, { "type": "null" } ] } } }, "RecordAcknowledgmentRequest": { "type": "object", "additionalProperties": false, "required": ["acknowledger", "payload_hash"], "properties": { "acknowledger": { "type": "object", "additionalProperties": false, "required": ["agent_id"], "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "passport_id": { "type": "string", "maxLength": 256 }, "wallet_address": { "type": "string", "maxLength": 256 } } }, "payload_hash": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "signature": { "type": "object", "required": ["alg", "value"], "properties": { "alg": { "type": "string", "description": "ES256 or EIP-191 are verifiable; other values are retained as unsupported claims." }, "value": { "type": "string", "maxLength": 8192 }, "jwk": { "type": "object", "description": "Only a public JWK can produce verified status. A JWK containing private members is retained as an unverified claim." } } } } }, "RecordAcknowledgmentResponse": { "type": "object", "required": ["ok", "record_id", "signature_status", "received_at", "acknowledgment"], "properties": { "ok": { "const": true }, "record_id": { "type": "string", "pattern": "^frv_" }, "signature_status": { "type": "string", "enum": ["verified", "unverified_claim"] }, "received_at": { "type": "string", "format": "date-time" }, "acknowledgment": { "$ref": "#/components/schemas/RecordAcknowledgment" } } }, "DecodedSettlementReceiptResponse": { "type": "object", "required": ["header", "envelope_version", "pq_signature", "settlement_receipt"], "properties": { "header": { "type": "object" }, "envelope_version": { "type": ["string", "null"] }, "pq_signature": { "type": "object", "required": ["present"], "properties": { "present": { "type": "boolean" }, "alg": { "type": ["string", "null"] }, "kid": { "type": ["string", "null"] } } }, "settlement_receipt": { "type": "object", "description": "Decoded receipt payload. This view is not itself signed." } } }, "CircleReadiness": { "type": "object", "required": ["provider", "status", "configured", "integration_ready", "operationally_verified", "provider_call_performed"], "properties": { "provider": { "const": "circle_compliance_engine" }, "status": { "type": "string", "enum": ["configured_unverified", "unavailable"] }, "configured": { "type": "boolean" }, "integration_ready": { "const": false }, "operationally_verified": { "const": false }, "provider_call_performed": { "const": false } } }, "SettlementReceiptReadiness": { "type": "object", "required": ["network", "production", "activation_enabled", "activation_mode", "signing_configuration_state", "signing_configuration_valid", "signing_configuration_error", "public_base_url_configured", "public_base_url_valid", "production_canonical_origin", "preflight_ready", "operationally_verified"], "properties": { "network": { "type": "string" }, "production": { "type": "boolean" }, "activation_enabled": { "type": "boolean" }, "activation_mode": { "type": "string", "enum": ["testnet_default", "explicit_opt_in", "disabled"] }, "signing_configuration_state": { "type": "string", "enum": ["absent", "incomplete", "complete"] }, "signing_configuration_valid": { "type": "boolean" }, "signing_configuration_error": { "type": ["string", "null"] }, "public_base_url_configured": { "type": "boolean" }, "public_base_url_valid": { "type": "boolean" }, "production_canonical_origin": { "type": "boolean" }, "preflight_ready": { "type": "boolean" }, "operationally_verified": { "const": false } } }, "X402ReadinessResponse": { "type": "object", "required": ["ok", "route", "circle", "settlement_receipt", "marketplace_scan", "detail"], "properties": { "ok": { "const": true }, "route": { "const": "x402_verify" }, "circle": { "$ref": "#/components/schemas/CircleReadiness" }, "settlement_receipt": { "$ref": "#/components/schemas/SettlementReceiptReadiness" }, "marketplace_scan": { "type": "object", "required": ["route", "settlement_receipt"], "properties": { "route": { "const": "/api/x402/scan" }, "settlement_receipt": { "$ref": "#/components/schemas/SettlementReceiptReadiness" } } }, "detail": { "type": "string" } } }, "X401ProofResult": { "type": "object", "required": ["scheme", "version", "request_id"], "properties": { "scheme": { "const": "x401" }, "version": { "const": "0.2.0" }, "request_id": { "const": "flint-principal-identity-v1" }, "result": { "type": "string" }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number" }, "record_id": { "type": "string", "pattern": "^frv_" }, "error": { "type": "string" }, "error_description": { "type": "string" } } }, "X401ChallengeResponse": { "type": "object", "required": ["error", "scheme", "version", "proof_request"], "properties": { "error": { "const": "proof_required" }, "scheme": { "const": "x401" }, "version": { "const": "0.2.0" }, "proof_request": { "type": "object" } } }, "X401VerifyResponse": { "type": "object", "required": ["ok", "protocol", "route", "verdict", "score", "record_id", "signed_record", "record", "x401"], "properties": { "ok": { "const": true }, "protocol": { "const": "x401" }, "route": { "const": "/api/x401/verify" }, "verdict": { "$ref": "#/components/schemas/VerdictDecision" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "top_reasons": { "type": "array", "items": { "type": "string" } }, "record_id": { "type": "string", "pattern": "^frv_" }, "signed_record": { "type": "string" }, "record": { "$ref": "#/components/schemas/HybridEnvelope" }, "x401": { "type": "object", "required": ["request_id", "principal_attestation_source", "principal"], "properties": { "request_id": { "const": "flint-principal-identity-v1" }, "principal_attestation_source": { "const": "x401" }, "principal": { "type": "object" } } } } }, "TransactionIntent": { "type": "object", "required": ["amount_display"], "properties": { "amount_display": { "type": "string", "description": "Human-readable transaction amount." }, "amount_atomic": { "type": ["string", "null"], "description": "Atomic token amount when available." }, "asset": { "type": "string", "description": "Asset symbol, such as USDC." }, "chain": { "type": "string", "description": "CAIP-2 chain identifier." }, "counterparty_address": { "type": ["string", "null"], "description": "Wallet or counterparty address." }, "merchant_reference": { "type": ["string", "null"], "description": "Merchant reference for the intended action." }, "tx_intent_hash": { "type": ["string", "null"], "description": "Optional hash of the transaction intent." } } }, "AuthorizationScope": { "type": "object", "properties": { "max_amount_per_tx_display": { "type": "string", "description": "Maximum amount authorized per transaction." }, "allowed_counterparties": { "type": "array", "items": { "type": "string" }, "description": "Allowed merchant references or counterparties." }, "time_window_end": { "type": "string", "format": "date-time", "description": "Expiration time for the declared scope." } } }, "AgentClaim": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Agent-provided stable identifier or handle." }, "principal_hint": { "type": "string", "description": "Principal or authority hint supplied by the agent." }, "agent_runtime_hint": { "type": "string", "description": "Agent runtime category, such as browser, api_client, or api_meter." }, "wallet_type": { "type": "string", "description": "Wallet or account type claimed by the agent." } } }, "VerdictDecision": { "type": "string", "enum": ["allow", "step_up", "review", "block"] }, "OutcomeRequest": { "type": "object", "required": ["record_id", "outcome"], "properties": { "record_id": { "type": "string", "pattern": "^frv_", "description": "Signed verification record ID." }, "outcome": { "type": "string", "enum": ["completed", "disputed", "flagged"] }, "merchant_note": { "type": ["string", "null"] }, "partner_id": { "type": "string", "default": "sandbox_public" } } }, "OutcomeResponse": { "type": "object", "required": ["ok", "outcome_id", "record_id", "outcome", "stored_at"], "properties": { "ok": { "type": "boolean" }, "outcome_id": { "type": "string" }, "record_id": { "type": "string" }, "outcome": { "type": "string", "enum": ["completed", "disputed", "flagged"] }, "stored_at": { "type": "string", "format": "date-time" } } }, "AgentReputationResponse": { "type": "object", "required": ["ok", "agent_reputation"], "properties": { "ok": { "type": "boolean" }, "agent_reputation": { "$ref": "#/components/schemas/AgentReputation" } } }, "AgentReputation": { "type": "object", "required": ["flint_agent_id", "global_stats", "runtime_diversity", "principal_consistency", "recent_outcomes"], "properties": { "flint_agent_id": { "type": "string" }, "global_stats": { "type": "object", "required": ["first_seen", "total_transactions", "dispute_rate"], "properties": { "first_seen": { "type": ["string", "null"], "format": "date-time" }, "total_transactions": { "type": "integer", "minimum": 0 }, "dispute_rate": { "type": "number", "minimum": 0 } } }, "runtime_diversity": { "type": "integer", "minimum": 0 }, "principal_consistency": { "type": "integer", "minimum": 0 }, "recent_outcomes": { "type": "array", "items": { "type": "string", "enum": ["completed", "disputed", "flagged"] } } } }, "GraphHealthResponse": { "type": "object", "required": ["ok", "status"], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": ["ok", "configured", "unconfigured"] }, "latency_ms": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } }, "TrustManifest": { "type": "object", "required": ["version", "requires_flint_authorization", "partner_id"], "properties": { "version": { "type": "string" }, "issuer": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "requires_flint_authorization": { "type": "boolean" }, "partner_id": { "type": "string" }, "authorization_record": { "type": "object" }, "agent_commerce": { "type": "object" }, "trust_graph": { "type": "object" }, "outcome_feedback": { "type": "object" }, "docs": { "type": "object" }, "privacy": { "type": "object" }, "contact": { "type": "object" } } }, "ErrorResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" }, "detail": { "type": "string" } } }, "PassportIssueRequest": { "type": "object", "required": ["agent"], "properties": { "agent": { "type": "object", "description": "Agent identity. Signed into the passport.", "properties": { "agent_id": { "type": "string" }, "agent_name": { "type": "string" }, "controller_id": { "type": "string" }, "controller_type": { "type": "string", "enum": ["user", "organization"] }, "wallet_address": { "type": "string" }, "attestations": { "type": "array", "items": { "type": "object" } } } }, "mandate": { "type": "object", "description": "Mutable spend authority captured at issue. NOT part of the passport signature.", "properties": { "allowed_actions": { "type": "array", "items": { "type": "string" } }, "max_transaction_amount": { "type": "number" }, "notes": { "type": "string" } } } } }, "Mandate": { "type": "object", "description": "Unsigned, mutable mandate config read at decision time.", "properties": { "passport_id": { "type": "string" }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "max_transaction_amount": { "type": "number" }, "notes": { "type": ["string", "null"] }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PassportResponse": { "type": "object", "properties": { "passport_id": { "type": "string", "description": "kya_ prefix + ULID." }, "flint_agent_id": { "type": "string", "description": "Trust Graph node key (faid_ prefix)." }, "passport": { "type": "object", "description": "Hybrid-v0 signature envelope.", "properties": { "envelope_version": { "type": "string", "example": "hybrid-v0" }, "jws": { "type": "string", "description": "ES256 compact JWS over the identity-only payload." }, "pq_signature": { "type": ["string", "null"], "description": "ML-DSA-65 signature (base64url)." }, "pq_kid": { "type": ["string", "null"] }, "pq_alg": { "type": ["string", "null"] } } }, "mandate": { "$ref": "#/components/schemas/Mandate" }, "verification": { "type": "object", "properties": { "signature_valid": { "type": "boolean" }, "status": { "type": "string" }, "not_expired": { "type": "boolean" }, "valid": { "type": "boolean" } } } } }, "MandateUpdateRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": ["update_mandate"] }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "max_transaction_amount": { "type": "number" }, "notes": { "type": "string" } } }, "MandateUpdateResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "passport_id": { "type": "string" }, "mandate": { "$ref": "#/components/schemas/Mandate" }, "passport_signature_unchanged": { "type": "boolean", "description": "Always true: a mandate update never re-signs the passport." } } }, "PurchaseAuthorizationRequest": { "type": "object", "required": ["action", "shop", "currency", "max_amount"], "properties": { "action": { "type": "string", "enum": ["issue_purchase_authorization"] }, "shop": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "max_amount": { "type": "number", "exclusiveMinimum": 0 } } }, "PurchaseAuthorizationEnvelope": { "type": "object", "required": ["envelope_version", "jws"], "properties": { "envelope_version": { "type": "string", "example": "hybrid-v0" }, "jws": { "type": "string", "description": "ES256 compact JWS over the purchase authorization." }, "pq_signature": { "type": ["string", "null"], "description": "Parallel ML-DSA-65 signature when configured." }, "pq_kid": { "type": ["string", "null"] }, "pq_alg": { "type": ["string", "null"] } } }, "PurchaseAuthorizationResponse": { "type": "object", "required": ["ok", "authorization", "purchase_authorization"], "properties": { "ok": { "type": "boolean" }, "authorization": { "type": "object", "description": "Decoded owner authorization claims, including Passport, shop, action, amount, currency, mandate version, and expiry." }, "purchase_authorization": { "$ref": "#/components/schemas/PurchaseAuthorizationEnvelope" }, "usage": { "type": "string" } } } }, "securitySchemes": { "WorkOSOwnerSession": { "type": "apiKey", "in": "cookie", "name": "flint_session", "description": "Sealed WorkOS session required for claimed-Passport owner actions. Unclaimed mandate updates remain open by design." }, "X402Payment": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "Canonical x402 v2 payment proof on a paid retry. Initial unpaid challenge requests require no payment proof." }, "FlintCapability": { "type": "apiKey", "in": "header", "name": "FLINT-CAPABILITY", "description": "Short-lived Passport-owner-issued capability bound to the exact x402 Verify request." }, "DPoP": { "type": "apiKey", "in": "header", "name": "DPoP", "description": "Fresh caller proof bound to the capability, request, and x402 payment proof." }, "X401Proof": { "type": "apiKey", "in": "header", "name": "PROOF-RESPONSE", "description": "Base64url-encoded x401 principal-identity presentation. Omit to request a proof challenge." } }, "parameters": { "RecordId": { "name": "record_id", "in": "path", "required": true, "description": "FLINT verification record identifier.", "schema": { "type": "string", "pattern": "^frv_[0-9A-HJKMNP-TV-Z]{26}$" } }, "SettlementReceiptId": { "name": "receipt_id", "in": "path", "required": true, "description": "FLINT x402 settlement receipt identifier.", "schema": { "type": "string", "pattern": "^fsr_[0-9A-HJKMNP-TV-Z]{26}$" } } }, "headers": { "FlintVerdict": { "description": "FLINT's 4-state transaction-time decision.", "schema": { "$ref": "#/components/schemas/VerdictDecision" } }, "FlintScore": { "description": "FLINT score from 0 through 100.", "schema": { "type": "string", "pattern": "^(?:100|[1-9]?[0-9])$" } }, "PaymentRequired": { "description": "Base64url-encoded canonical x402 v2 payment challenge.", "schema": { "type": "string" } }, "PaymentResponse": { "description": "Base64url-encoded canonical x402 v2 settlement response.", "schema": { "type": "string" } }, "X401ProofRequest": { "description": "Base64url-encoded x401 proof request.", "schema": { "type": "string" } }, "X401ProofResult": { "description": "Base64url-encoded x401 verification result.", "schema": { "type": "string" } } }, "responses": { "MethodNotAllowed": { "description": "HTTP method not allowed for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "X402PaymentRequired": { "description": "Canonical x402 v2 payment challenge. No protected or expensive work has executed.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Conflict or idempotency collision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "The cheap caller-admission quota for paid attempts was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadGateway": { "description": "Upstream graph or service failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unavailable": { "description": "Service unavailable or not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServerError": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }