{
  "openapi": "3.0.3",
  "info": {
    "title": "SafeGate x402 Commerce Evidence API",
    "version": "1.1.0",
    "description": "Paid x402 entry surface for SafeGate post-payment commerce evidence."
  },
  "servers": [
    {
      "url": "https://safegate-nsgoods-paid-pilot.vercel.app"
    }
  ],
  "paths": {
    "/api/x402-commerce-evidence-session": {
      "post": {
        "operationId": "verifyCommerceAndIssueSafeGateProof",
        "summary": "Verify Base commerce and receive signed SafeGate evidence",
        "description": "Preflight a historical Base USDC transfer; pay 0.07 USDC with x402 v2 exact EIP-3009; receive a stored signed evidence result. Persist a random 32-byte X-SafeGate-Recovery-Key before payment. Recover with the original body, PAYMENT-SIGNATURE and recovery key; do not create a new payment authorization on timeout. Optional signed NSGoods evidence is attributed, not compliance clearance.",
        "tags": [
          "commerce-verification",
          "x402"
        ],
        "x-price": "$0.07",
        "x-payment-info": {
          "network": "eip155:8453",
          "currency": "USDC",
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.07"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commerce_tx_hash",
                  "payment_sender",
                  "merchant_receiver",
                  "amount_base_units"
                ],
                "additionalProperties": false,
                "properties": {
                  "request_id": {
                    "type": "string",
                    "description": "Optional SafeGate request id. If omitted SafeGate derives one deterministically."
                  },
                  "commerce_tx_hash": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{64}$"
                  },
                  "payment_sender": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{40}$"
                  },
                  "merchant_receiver": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{40}$"
                  },
                  "amount_base_units": {
                    "type": "string",
                    "pattern": "^[1-9][0-9]*$",
                    "description": "Exact USDC amount in 6-decimal base units."
                  },
                  "nsgoods_verdict_base64": {
                    "type": "string",
                    "description": "Exact raw signed NSGoods screen-multi JSON. Signature, current signer scope, Base chain, subject, request and historical chronology checked. NSGoods fee payment and current compliance clearance are not independently verified."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SafeGate service payment settled; signed commerce evidence delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "schema",
                    "capability",
                    "status",
                    "request_id",
                    "safegate_fee",
                    "commerce_payment",
                    "assurance",
                    "commerce_proof",
                    "proof_verification"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "schema": {
                      "type": "string"
                    },
                    "capability": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "safegate_fee": {
                      "type": "object"
                    },
                    "commerce_payment": {
                      "type": "object"
                    },
                    "third_party_evidence": {
                      "nullable": true,
                      "type": "object"
                    },
                    "assurance": {
                      "type": "object"
                    },
                    "commerce_proof": {
                      "type": "object"
                    },
                    "proof_verification": {
                      "type": "object"
                    },
                    "evidence_request": {
                      "type": "object",
                      "description": "Preimage for signed request hash."
                    },
                    "evidence_result": {
                      "type": "object",
                      "description": "Preimage for signed response hash. Required for offline verification of fee and NSGoods references."
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Payment or execution needs reconciliation. paid=null means UNKNOWN, not unpaid. Never create another authorization."
          },
          "402": {
            "description": "x402 payment required after commerce preflight succeeds."
          },
          "409": {
            "description": "An order/request/authorization is already bound, or original recovery credentials do not match. No new settlement."
          },
          "422": {
            "description": "Commerce payment or optional third-party evidence failed preflight; buyer is not charged."
          },
          "503": {
            "description": "Unavailable or integrity failure. No auto-retry payment. Recover only with the original credentials."
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "PAYMENT-SIGNATURE",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 24000
            },
            "description": "x402 v2 Base USDC EIP-3009 payment. Persist the exact value for recovery."
          },
          {
            "in": "header",
            "name": "X-SafeGate-Recovery-Key",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "description": "REQUIRED when PAYMENT-SIGNATURE is present. Generate 32 random bytes before payment; persist privately. Not an on-chain secret and never placed in authorization calldata."
          }
        ],
        "x-agent-discovery": {
          "protocol": "x402",
          "facilitator": "https://facilitator.payai.network",
          "bazaarCatalog": "https://facilitator.payai.network/discovery/resources",
          "type": "http",
          "machineBuyable": true,
          "network": "eip155:8453",
          "price": "0.07 USDC",
          "payTo": "0xbe9f8cde6ed2794be1dd79627aa8407b95050061"
        }
      }
    }
  }
}