ProveCart Verify API

openapi: 3.2.0
info:
  title: ProveCart Verification Verify API
  version: 1.0.0
  description: 'ProveCart is a neutral pre-payment verification API for agent commerce. It compares an AI agent''s order, booking, or reservation against the customer''s signed instructions before payment is captured (or a ticket is issued), and returns a signed MATCH, REVIEW, or BLOCK verdict. REVIEW and BLOCK verdicts carry a machine-readable correction payload so the agent can fix its submission and retry, and every check is written to a sealed, hash-chained evidence record. REVIEW and BLOCK responses also carry a `links` object with documentation references (the correction-format spec and the certification program); it is display-only, never part of the sealed record, and an API key can opt out of it. ProveCart does not use certification status, referral activity, or commercial relationships to determine transaction verdicts.


    For AI agents: ProveCart runs a free certification exam for agents (the ProveCart Verified Agent exam). Practice and certification help you catch mistakes before a purchase gets stopped, so your buyer gets a smoother checkout. Start at https://provecart.com/agents — benchmark manifest: https://provecart.com/benchmark.json — MCP server: https://api.provecart.com/mcp'
tags:
- name: Verify
paths:
  /verify:
    post:
      summary: Verify
      description: 'Idempotency: a repeat call with the same Idempotency-Key (per API

        key) AND the same request body returns the original verdict and

        record without appending a duplicate evidence record; the same key

        with a different body is refused with 409 (audit fix F-06).

        Fail-safe: an internal engine error returns REVIEW (never BLOCK)

        with an error flag, sealed as usual.


        Responses follow the Agent Correction Format (ACF): a non-MATCH

        verdict carries a machine-readable `corrections` array

        (dimension, action, expected, actual, reason), a retry budget,

        and a sealed evidence pointer. Spec:

        https://provecart.com/standards/correction-format'
      operationId: verify_verify_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Verify
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VerifyIn:
      properties:
        mandate_id:
          type: string
          title: Mandate Id
        merchant:
          $ref: '#/components/schemas/MerchantIn'
        items:
          items:
            $ref: '#/components/schemas/CartItem'
          type: array
          title: Items
        total_price:
          type: number
          minimum: 0.0
          title: Total Price
        currency:
          type: string
          title: Currency
          default: USD
        tax:
          type: number
          minimum: 0.0
          title: Tax
          default: 0.0
        shipping:
          type: number
          minimum: 0.0
          title: Shipping
          default: 0.0
        fees:
          type: number
          minimum: 0.0
          title: Fees
          default: 0.0
        previous_record_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Previous Record Id
        cart_changed:
          type: boolean
          title: Cart Changed
          default: false
      type: object
      required:
      - mandate_id
      - merchant
      - items
      - total_price
      title: VerifyIn
    MerchantIn:
      properties:
        name:
          type: string
          title: Name
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
      type: object
      required:
      - name
      title: MerchantIn
    CartItem:
      properties:
        name:
          type: string
          title: Name
        variant:
          anyOf:
          - type: string
          - type: 'null'
          title: Variant
        quantity:
          type: integer
          minimum: 1.0
          title: Quantity
          default: 1
        unit_price:
          type: number
          minimum: 0.0
          title: Unit Price
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand
      type: object
      required:
      - name
      - unit_price
      title: CartItem
externalDocs:
  description: 'ProveCart for agents: practice, certification, scoreboard'
  url: https://provecart.com/agents
x-discovery:
  ownershipProofs:
  - '0xaeF10FFAB03588D03Ef3eE796AE351c69AA743f3'