{
  "openapi": "3.1.0",
  "info": {
    "title": "SafeGate CommerceProof Verification API",
    "version": "1.1.0",
    "summary": "Independent verdict on commerce payment evidence. Charged only when the verdict is VERIFIED.",
    "description": "SafeGate returns an independent verdict on evidence of a Base USDC payment. Two inputs are accepted and exactly one must be sent per call.\n\nproof: a full SafeGate CommerceProof. The payment is confirmed on chain through two independent RPC providers, the payee is screened against the sanctions manifest NSGoods publishes and signs, and the signer key is pinned to a published registry.\n\npayment: a Base transaction hash on its own. The USDC transfer is read from two independent RPC providers and reported. No sanctions screening is performed on this input.\n\nWhat SafeGate does NOT assert, on either input: that goods or services were delivered, that the commercial transaction completed, that any party passed sanctions screening beyond what is explicitly reported, or the identity of any party. The field commerce_verified is always false. This deployment does not sign its own responses: signing_capability is NONE_BY_DESIGN and the assurance ceiling is OBSERVED.",
    "x-assurance-ceiling": "OBSERVED",
    "x-signing-capability": "NONE_BY_DESIGN",
    "x-commerce-verified": false,
    "contact": { "name": "Nurexen Labs", "url": "https://safegatelabs.xyz" },
    "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" }
  },
  "servers": [
    { "url": "https://pay.safegatelabs.xyz", "description": "Paid production endpoint" }
  ],
  "tags": [
    { "name": "verification", "description": "Paid verdicts on payment evidence" },
    { "name": "health", "description": "Deployment and configuration status" }
  ],
  "paths": {
    "/api/commerceproof/verify-paid": {
      "post": {
        "operationId": "verifyPaid",
        "tags": ["verification"],
        "summary": "Verify payment evidence and return a verdict",
        "description": "Requires an x402 payment. Send exactly one of proof or payment. Settlement is attempted only when the verdict is VERIFIED; FAILED and INDETERMINATE never reach settlement.",
        "x-x402": {
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "assetName": "USDC",
          "amountBaseUnits": "50000",
          "amountHuman": "0.05 USDC",
          "payTo": "0x367f1b3d8ca90d1e087481a9a40d585bf3451a03",
          "payToRole": "FACILITATOR_TREASURY_NOT_THE_SERVICE_OPERATOR",
          "facilitator": "https://x402-agent-pay.com/facilitator",
          "maxTimeoutSeconds": 300,
          "minRemainingValiditySeconds": 60,
          "paymentHeader": "PAYMENT-SIGNATURE",
          "legacyPaymentHeader": "X-PAYMENT",
          "headerPrecedence": "PAYMENT-SIGNATURE wins; X-PAYMENT is ignored when both are present",
          "settlementPolicy": "SETTLE_ONLY_ON_VERDICT_VERIFIED",
          "failedVerdictPolicy": "NEVER_REACHES_SETTLE",
          "unknownSettlementPolicy": "NO_AUTOMATIC_SECOND_CHARGE_DURABLE_RECOVERY"
        },
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "x402 v2 payment authorization. Without it the endpoint returns 402 with the payment requirements.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VerifyRequest" },
              "examples": {
                "paymentEvidenceOnly": {
                  "summary": "payment: a Base transaction hash on its own",
                  "value": { "payment": { "transaction_hash": "0x7d100bfb0185db0ac7d4f6983048b96fb9b4cd3d9616a6be2e8be4c5610d4b7c" } }
                },
                "fullCommerceProof": {
                  "summary": "proof: a full SafeGate CommerceProof",
                  "value": { "proof": { "schema": "SAFEGATE_COMMERCEPROOF_V1", "request_id": "SG-EVM-REQ-EXAMPLE-000000000001" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A verdict was produced. A 200 does NOT mean VERIFIED: read the verdict field. Charged is true only when verdict is VERIFIED and settlement succeeded.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } }
            }
          },
          "400": {
            "description": "The body did not carry exactly one recognised input.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "examples": {
                  "neither": {
                    "summary": "Neither proof nor payment was sent",
                    "value": { "ok": false, "error": { "code": "PROOF_REQUIRED" }, "accepted_inputs": ["proof", "payment"] }
                  },
                  "both": {
                    "summary": "Both were sent; SafeGate does not guess which was meant",
                    "value": { "ok": false, "error": { "code": "AMBIGUOUS_INPUT" }, "accepted_inputs": ["proof", "payment"] }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required. The body and the PAYMENT-REQUIRED header carry the same x402 v2 payment requirements object, so the price and payee cannot drift between them.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64 of the same JSON body returned with this response.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } }
            }
          },
          "405": { "description": "Method not allowed. Only POST is accepted on this path." },
          "413": { "description": "Request body larger than 1048576 bytes." },
          "429": {
            "description": "Quota exceeded. Four dimensions are enforced and the lowest wins: 60 per wallet-minute, 500 per wallet-day, 500 per IP-day, 1000 global per day. Counted on payment-authorized calls, not only on VERIFIED verdicts.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "503": { "description": "The verification engine is not healthy. See GET /api/health." }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "tags": ["health"],
        "summary": "Deployment and configuration status",
        "description": "Reports the verification engine status and the paid route configuration. config_complete reports configuration only, never that the route is working. This deployment publishes only this path and POST /api/commerceproof/verify-paid.",
        "responses": {
          "200": {
            "description": "Engine healthy.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "503": { "description": "Engine not healthy." }
        }
      }
    },
    "/.well-known/safegate-keys.json": {
      "get": {
        "operationId": "keyRegistry",
        "tags": ["health"],
        "summary": "Published signer key registry",
        "description": "The registry that proof signer keys are pinned against.",
        "responses": {
          "200": {
            "description": "Key registry.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VerifyRequest": {
        "type": "object",
        "description": "Send exactly one of proof or payment. Sending both returns 400 AMBIGUOUS_INPUT; sending neither returns 400 PROOF_REQUIRED.",
        "properties": {
          "proof": {
            "type": "object",
            "description": "A SafeGate CommerceProof. The keys commerceproof and product are accepted as aliases."
          },
          "payment": {
            "type": "object",
            "description": "Payment evidence only. No sanctions screening, no signature, no delivery claim. The key base_payment is accepted as an alias.",
            "properties": {
              "transaction_hash": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{64}$",
                "description": "A Base mainnet transaction hash. Malformed values are rejected without any RPC call being made."
              }
            },
            "required": ["transaction_hash"],
            "additionalProperties": false
          }
        },
        "oneOf": [{ "required": ["proof"] }, { "required": ["payment"] }]
      },
      "VerifyResult": {
        "type": "object",
        "properties": {
          "schema": { "type": "string", "const": "SAFEGATE_COMMERCEPROOF_PAID_VERIFY_V1" },
          "ok": { "type": "boolean", "description": "True only when the verdict is VERIFIED." },
          "verdict": {
            "type": "string",
            "enum": ["VERIFIED", "FAILED", "INDETERMINATE"],
            "description": "VERIFIED: the evidence agreed across two independent RPC providers. FAILED: the evidence is contradicted on chain. INDETERMINATE: SafeGate could not establish the fact, for example when only one RPC provider answered or the providers disagreed. INDETERMINATE is never charged."
          },
          "verdict_reason": { "type": "string" },
          "verdict_scope": { "type": "string", "description": "What the verdict covers. Nothing outside this scope is asserted." },
          "assurance": { "type": "string", "enum": ["CLAIMED", "OBSERVED", "VALIDATED", "THIRD_PARTY_ATTESTED"] },
          "commerce_verified": { "type": "boolean", "const": false, "description": "Always false. SafeGate verifies evidence, never delivery." },
          "signed": { "type": "boolean", "const": false, "description": "This deployment does not sign its responses." },
          "independently_verified": { "type": "boolean", "description": "True only when two or more independent RPC providers agreed field by field." },
          "independent_rpc_count": { "type": "integer" },
          "not_verified": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Named facts this response does NOT establish."
          },
          "sanctions_screening": {
            "type": "string",
            "description": "On the payment input this is NOT_PERFORMED_IN_THIS_EVIDENCE_TYPE."
          },
          "charged": { "type": "boolean" },
          "payment_status": {
            "type": "string",
            "enum": ["CHARGED", "NOT_CHARGED", "UNKNOWN"],
            "description": "UNKNOWN means settlement state could not be established. No automatic second charge is attempted; recovery is durable."
          },
          "settlement": {
            "type": ["object", "null"],
            "properties": {
              "transaction": { "type": "string" },
              "amount": { "type": "string" },
              "network": { "type": "string" },
              "asset": { "type": "string" }
            }
          }
        },
        "required": ["schema", "ok", "verdict", "commerce_verified", "charged", "payment_status"]
      },
      "PaymentRequired": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer", "const": 2 },
          "error": { "type": "string" },
          "resource": { "type": "object" },
          "payTo": { "type": "string" },
          "accepts": { "type": "array", "items": { "type": "object" } },
          "facilitator": { "type": "string" },
          "extensions": { "type": "object" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": {
            "type": "object",
            "properties": { "code": { "type": "string" }, "message": { "type": "string" } }
          },
          "accepted_inputs": { "type": "array", "items": { "type": "string" } },
          "charged": { "type": "boolean" },
          "payment_status": { "type": "string" }
        }
      }
    }
  },
  "x-safegate": {
    "freeRoute": {
      "url": "https://verify.safegatelabs.xyz/api/commerceproof/verify-free",
      "description": "Unpaid verification of a CommerceProof, for trying SafeGate before paying."
    },
    "documentUpdated": "2026-11-20",
    "documentNote": "This document is checked against the live 402 challenge by an automated test, so the price, network, asset, payee, facilitator and accepted inputs declared here cannot drift from the running endpoint."
  }
}
