The operating manual for agent authorization.

FLINT evaluates agent transaction requests submitted to its verification surfaces before settlement and records the result as signed evidence. Each request can draw on Principal Identity, Agent Identity, Wallet Provenance, Authorization Scope, Environment Identity, and Cross-Merchant Reputation.

FLINT is an authority-verification and evidence layer. It is not a wallet, payment rail, custody provider, universal bot detector, or guarantee that every upstream claim is true.

Use the live demo to submit an agent payment request, watch the KYA layers evaluate the transaction, and export the signed verification record.

KYA means Know Your Agent: verifying that a non-human actor is known, authorized, and in scope before it can move money.

A FLINT Agent Passport binds an agent to a controller, wallet, and mandate. It is the portable identity and authorization artifact for non-human actors.

The agent passport is the foundation of the Cross-Domain Agent Passport™ (CDAP), the neutral credential architecture for carrying platform attestations across trust domains.

Every verified request resolves to exactly 1 of 4 verdicts. STEP-UP and BLOCK are not the same finding: STEP-UP means FLINT does not yet have enough verifiable evidence to decide, and it comes with a remediation menu the agent can act on. BLOCK means affirmative risk or fraud signals were found, such as a sanctions or blocklist match, tampering, a revoked or frozen passport, or a mandate violation.

A cold-start agent, 1 that FLINT has not seen before, with no passport, no declared authorization scope, and no principal attestation, receives STEP-UP rather than BLOCK. STEP-UP is not a rejection: the response carries a machine-readable menu of cures the agent can complete on its own, and completed cures attach to the agent and carry forward automatically to future verifications. The 3 cures FLINT offers a cold-start agent are:

Reputation accrues to the passport-agent pairing for the life of the pairing, so a cure completed once keeps paying off on every later verification. Headless or server-side callers are not treated as suspicious by default; environment signals only weigh against a request when a browser context was claimed and the runtime does not match it.

BLOCK is reserved for something categorically different from a cold start: affirmative risk or fraud signals, such as a sanctions or blocklist match, tampering, a revoked or frozen passport, or a mandate violation. An agent with no history and no red flags gets STEP-UP, not BLOCK.

Example STEP-UP response shape

{
  "verdict": "step_up",
  "score": 60,
  "advisory": "This agent has not yet established a verifiable identity or authorization for this request. Complete any of the listed cures to continue; completed cures attach to this agent and carry forward automatically.",
  "cures": [
    { "type": "mint_passport" },
    { "type": "declare_authorization_scope" },
    { "type": "attach_principal_attestation" }
  ]
}

A verification record is the signed artifact showing that FLINT evaluated an agent transaction request. It preserves what FLINT checked, observed, and decided at verification time, together with labeled timestamps and attribution.

The signature proves record authenticity and integrity. It does not independently prove that every upstream representation was factually true, that a downstream payment settled, or that a counterparty will accept the record as dispositive evidence.

Record version 1.2 is the default production contract. Version 1.3 is a conditional extension emitted only when trusted Semantic Integrity evidence is present and the server-controlled feature is enabled. Caller-supplied semantic claims cannot create a v1.3 record.

passport_id is additive: set to the Agent Passport id when 1 was present in the request context at verify time (free verify, x402 metered verify, or x401), and an honest null when the request was anonymous or the supplied id did not validate. It is never guessed or inferred from any other field on the request.

{
  "record_version": "1.2",
  "record_type": "agent_transaction_verification",
  "issuer": "flint",
  "framework": "KYA",
  "passport_id": "kya_01J9EXAMPLE0000000000000",
  "transaction": {
    "timing_mode": "authorization",
    "chain": "eip155:8453",
    "token": {
      "symbol": "USDC",
      "issuer": "circle"
    },
    "amount_display": "847.00",
    "direction": "credit_to_merchant"
  },
  "agent_claim": {
    "agent_id": "agt_skyline_88af3c12",
    "runtime_hint": "coinbase_agent_kit",
    "wallet_type": "smart_account_erc4337"
  },
  "authorization": {
    "authority_bound": true,
    "authority_evidence_basis": "purchase_authorization",
    "purchase_authorization_id": "kya_pa_01J9EXAMPLE"
  },
  "verdict": {
    "decision": "allow",
    "confidence": 0.2,
    "model_version": "flint-verifier-v1.0.0-sandbox"
  }
}

The decision model converts verification signals into a bounded trust score and a four-state verdict. The score starts at a neutral 50, applies positive and negative signals, clamps to 0-100, and maps to ALLOW, STEP-UP, REVIEW, or BLOCK.

This table is an illustrative public decision model for docs and partner review. Production policy may vary by partner, rail, mandate, and risk configuration.

Verdict confidence is the decision margin from the nearest state transition at 40, 60, or 80. A score exactly on a threshold has confidence 0 because a small score change can cross the boundary. Confidence is not the probability that the agent is fraudulent, legitimate, or certain to complete the transaction.

When a request presents a passport_id, FLINT resolves the passport, verifies its hybrid signature (ES256 plus ML-DSA-65), and checks its lifecycle: stamped, and not revoked, frozen, or expired. For wallet payments, identity and principal attestation credit is applied only when the verified payer wallet matches the wallet bound to the passport.

An authenticated off-chain integration can instead present an owner-issued, short-lived, single-use purchase authorization bound to a specific merchant, action, currency, amount, and time window. A valid transaction-bound authorization can establish authority without pretending that the Passport wallet paid the off-chain transaction.

When a verified Passport has an EVM wallet, FLINT may add a factual Ethereum mainnet history baseline for that Passport-bound identity wallet. The record labels it passport_bound_wallet andidentity_wallet_not_shopify_payer. It is evidence only: observed or empty history does not create a clean, fraud, sanctions, or authorization judgment and does not change the verdict.

A stolen passport_id confers nothing. FLINT grants credit only after the applicable wallet match or transaction-bound authorization check succeeds.

Every record that carries a declared or resolved authorization scope also carries a scope evidence basis, so a counterparty reading the record can tell how that scope was established:

A counterparty should read passport_mandate as the principal's declared standing scope,wallet_corroborated as scope confirmed against wallet or transaction evidence, andpurchase_authorization as owner-issued authority bound to the specific off-chain action. The evidence-basis field makes those proof levels explicit.

FLINT uses MITRE F3 as an additive labeling vocabulary. Verification records are interpretable as MITRE F3 sightings; this does not imply MITRE endorsement or certification.

A mandate defines permitted actions, payment limits, counterparties, wallet bindings, and validity windows. FLINT uses the mandate to determine whether a payment request is inside authorized scope.

Sentinel turns an Agent Passport into a portable anti-fraud tool. It watches the agent's own permission set, its mandate, and alerts you out of band the moment that authority is escalated, with a one-tap kill switch to stop the agent everywhere FLINT is checked.

Sentinel catches takeover that escalates an agent's authority, and Freeze blocks the agent wherever FLINT is checked. It does not stop spending that stays within the agent's existing mandate, and it does not stop spending that never routes through FLINT. It is one layer of a defense in depth: the passport is identity, Sentinel is the takeover alarm and kill switch, and enforcement at the wallet or runtime is the hard backstop.

FLINT verification records are hybrid-signed. The primary signature is unchanged ES256 (ECDSA P-256) over the RFC 8785 canonical payload, carried as a compact JWS. A parallel post-quantum signature, ML-DSA-65 (NIST FIPS 204), is computed over the same canonical bytes and travels with the record as additive sibling fields (pq_signature, pq_kid, pq_alg) inside a versioned envelope (envelope_version: "hybrid-v0"). Because the signature travels with the record rather than in transport headers, it survives export, storage, paste-to-verify, and partner forwarding.

Existing ES256-only consumers ignore the new fields and validate the unchanged JWS exactly as before; PQC-aware consumers verify both signatures. The ML-DSA-65 public key is published in the JWKS using the draft IETF JOSE PQC AKP key type and is marked experimental. This is crypto-agile and versioned: FLINT is hybrid / PQC-ready, not standards-compliant, until the JOSE PQC RFCs ratify, and a draft change to the algorithm id or JWK type is configuration rather than a re-architecture.

x402 settlement receipts use a separate ES256 and ML-DSA-65 key family from authorization records. Purpose-separated receipt signing and public receipt retrieval are validated on staging. They are not a production capability until the dedicated production keys, canonical origin, activation flag, and release smoke are separately approved and verified.

Public records include explicit record and framework versions. Clients should store the version with the verification record and treat unknown major versions as incompatible until reviewed.

Version 1.2 remains the ordinary record. Version 1.3 adds bounded Semantic Integrity evidence only when the trusted server runtime supplies it. Both versions preserve the same locked verdict vocabulary and hybrid envelope model.

FLINT verifies authority and emits evidence. Payment rails, wallet providers, compliance engines, and agent frameworks remain separate trust domains. A verification record is not custody or settlement.

FLINT records use proxy identifiers and verification outcomes where possible. The goal is to preserve evidence of authorization without exposing unnecessary personal, wallet, or operational data to every counterparty.

The signed verification record gives teams a stable artifact for dispute defense, fraud review, controls testing, and audit support. Decoded data is not verified data; signature validation is required before treating a record as authentic.

Integrators should use the live HTTP and MCP surfaces below. FLINT does not currently publish an npm client package. The OpenAPI document is the source of truth for exact HTTP request, response, header, security, error, and release-state fields.

x402 admission before expensive work

The unpaid HTTP 402 challenge stays cheap. It does not run provider lookups, model calls, signed-record issuance, persistence, or Trust Graph ingestion. The policy layer decides whether the caller may force those costs before facilitator verification and the expensive path.

POST /api/x402/scan is the standard marketplace lane. Payment buys FLINT's scan of a separate intended commerce transaction. Unknown callers receive STEP-UP after settlement without external provider or model work unless deterministic evidence requires BLOCK. The high-assurance /api/x402/verify lane additionally requires a short-lived request-bound FLINT capability and DPoP caller proof before expensive verification can run. Payment alone is not authority.

A settlement receipt is issued only after final settlement succeeds and links to the exact signed authorization record. Receipt failure after settlement is reported truthfully and must not trigger a paid retry. Purpose-separated Scout settlement receipts are production on Base.

FLINT Scout through MCP

run_flint_scout is the canonical production MCP tool for a caller-paid $0.01 pre-transaction scan. The first call sends the intended transaction, nonce, and timestamp without a payment_signature. FLINT returns the x402 challenge without running the scan, provider calls, or model calls. The caller signs outside FLINT, then retries with the same request and the opaque payment signature. FLINT never requests a private key or seed phrase.

Payment proves settlement for the Scout service; it does not prove the agent has authority for the intended transaction. A settled response returns the verdict and signed verification record and, when issued, a separately signed settlement receipt with a receipt URL. Receipt unavailability does not turn a settled scan into a failure and must not trigger an automatic paid retry. Ambiguous paid outcomes use settlement_state: unknown and do_not_retry_automatically: true. Scout accepts transaction.amount_display and rejects caller-supplied amount_atomic until FLINT resolves asset decimals server-side.

What a settled Scout call returns

Payment and authorization are separate facts. service_payment and the separately signed settlement_receipt prove that the $0.01 Scout service fee settled. The verdict, score, top_reasons, signed_record, and hybrid record envelope state what FLINT checked and decided about the intended transaction. A paid call can still return STEP-UP, REVIEW, or BLOCK.

{
  "ok": true,
  "verdict": "step_up",
  "score": 60,
  "confidence": 0.6,
  "top_reasons": [
    "principal_not_attested",
    "authorization_scope_missing"
  ],
  "record_id": "frv_01...",
  "record_url": "https://flint.network/records/frv_01...",
  "signed_record": "eyJ...authorization-jws",
  "record": {
    "envelope_version": "hybrid-v0",
    "jws": "eyJ...authorization-jws",
    "pq_signature": "base64url...",
    "pq_kid": "flint-signing-pq-v1",
    "pq_alg": "ML-DSA-65"
  },
  "scan": {
    "profile": "marketplace_basic_v1",
    "status": "completed",
    "transaction_intent_commitment": "sha256_...",
    "payer_wallet_commitment": "sha256_...",
    "external_provider_calls": 0,
    "model_calls": 0,
    "bounded_paid_path_executed": true,
    "external_provider_path_executed": false,
    "record_persisted": true,
    "record_persistence_status": "persisted",
    "replay_protection_status": "completed",
    "trust_graph_ingest_attempted": true,
    "passport_upgraded": false
  },
  "compliance": {
    "source": "none",
    "provider_status": "not_run",
    "provider_verified": false,
    "result": "not_screened_in_marketplace_basic_profile"
  },
  "receipt_status": "issued",
  "settlement_receipt": {
    "receipt_id": "fsr_01...",
    "record": {
      "envelope_version": "hybrid-v0",
      "jws": "eyJ...settlement-receipt-jws",
      "pq_signature": "base64url...",
      "pq_kid": "flint-settlement-receipt-pq-v1",
      "pq_alg": "ML-DSA-65"
    },
    "idempotent": false
  },
  "service_payment": {
    "purpose": "flint_transaction_scan_service_fee",
    "status": "settled",
    "distinct_from_scanned_transaction": true,
    "receipt_status": "issued",
    "receipt_id": "fsr_01..."
  },
  "payment_attempted": true,
  "settlement_state": "settled",
  "receipt_url": "https://flint.network/api/settlement-receipts/fsr_01...",
  "receipt_page_url": "https://flint.network/receipts/fsr_01...",
  "do_not_retry_automatically": true,
  "next_step": "Retain both signed records. Open receipt_page_url for human review or use receipt_url for machine retrieval."
}

scan reports which bounded path ran, whether the record persisted, replay protection, and Trust Graph ingestion status. compliance states plainly when screening did not run. A receipt can be issued, unavailable, or disabled; after payment, an unavailable receipt is not permission to retry the paid call.

What a human sees: record_url opens the authorization decision and receipt_page_url opens the Scout service-payment receipt. The receipt page verifies ES256 in the browser, reports the ML-DSA-65 signature as present, checks the receipt-to-record hash commitment, and provides copy and download controls. receipt_url remains the machine JSON endpoint; add ?format=decoded for an unsigned inspection view or ?format=jws for compact JWS.

Records and mutual acknowledgment

The published record JSON Schema defines the signed verification record versions. After completion, POST /api/records/:id/acknowledge records a counterparty acknowledgment beside the signed verification record. When both sides acknowledge the transaction, those acknowledgments form the mutual receipt both parties can retain with the record.

Record retrieval returns the portable hybrid envelope by default. format=jws returns the compact ES256 JWS, while format=decoded is an unsigned inspection view that must not be trusted without signature verification. Verification records and related default artifacts use a 366-day storage TTL, covering the record's 1-year validity plus a buffer.

STEP-UP remediation options

STEP-UP is not a dead end. The response offers machine-readable options that an agent can satisfy, then the completed cure carries forward to future verifications.

Agents can also call the FLINT MCP tools when their runtime discovers tools dynamically. Human readers can use the MCP setup guide for client configuration and troubleshooting.

Each request needs a fresh replay-protection nonce and an ISO-8601 timestamp inside the accepted server window. See /openapi.json for the complete contract and response shapes.

POST /api/verify
Content-Type: application/json

{
  "nonce": "8b2ef62d-6ec0-4ac8-a5e4-e6d4ec447bcf",
  "timestamp": "2026-08-19T19:00:00.000Z",
  "timing_mode": "authorization",
  "transaction": {
    "chain": "eip155:8453",
    "token": { "symbol": "USDC", "issuer": "circle" },
    "amount_display": "847.00",
    "direction": "credit_to_merchant"
  },
  "agent_claim": {
    "agent_id": "agt_skyline_88af3c12",
    "principal_hint": "registered_controller"
  },
  "declared_scope": {
    "max_amount_per_tx_display": "1000.00"
  }
}

FLINT does not currently deliver a public flint.verification.completed outbound webhook. Integrators receive the verification result in the API response, retrieve records through the Records API, and submit observed outcomes with POST /api/outcomes.

Payment-provider or commerce-platform webhooks remain inside the integrator's system unless a separate FLINT integration explicitly documents them.

These common errors apply to the ordinary Verify contract. x401, x402, record, acknowledgment, and receipt routes publish their exact status-specific errors and challenge headers in the OpenAPI document. Provider unavailability is never represented as a clean result, and signing failure prevents record issuance.