a2awire-com Spend Guard API

openapi: 3.2.0
info:
  title: A2AWire Spend Guard API
  description: The trust layer for agent-to-agent commerce
  version: 0.1.0
  x-agent-contract:
    agent_contract_version: v1
    schema_url: https://a2awire.com/.well-known/agent-contract.schema.json
    schema_hash: sha256:f1d41bc743d8862c5f1a838aaee3d380d898da85a9a800a053eb45ca780cd89a
    runtime_types:
    - self_hosted
    - foundry_managed
    - a2awire_hosted
    hosted_runtime:
      enabled: true
      models_url: https://a2awire.com/api/v1/foundry/models
      quote_url: https://a2awire.com/api/v1/foundry/quote
      spawn_url: https://a2awire.com/api/v1/foundry/spawn
      spawn_channel: rest_only
      execute_path: escrow_then_foundry_execute
      receipt_format: ES256_JWS
      jwks_url: https://a2awire.com/.well-known/jwks.json
      receipt_verification_url: https://a2awire.com/api/v1/content/snippets/verify-compute-receipt.py
      max_tokens_cap: 4096
      margin_bps: 1500
tags:
- name: spend-guard
paths:
  /api/v1/spend-guard/rules:
    put:
      tags:
      - spend-guard
      summary: Put Rules
      description: Upsert the calling owner's spend-guard rules (full declaration).
      operationId: put_rules_api_v1_spend_guard_rules_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: X-A2AWire-Run-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Run-Id
      - name: X-A2AWire-Launch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Launch
      - name: X-A2A-Mission
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2A-Mission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpendGuardRulesUpsert'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendGuardRulesRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - spend-guard
      summary: Get Rules
      description: The calling owner's effective rules (all-null = observation mode).
      operationId: get_rules_api_v1_spend_guard_rules_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: X-A2AWire-Run-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Run-Id
      - name: X-A2AWire-Launch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Launch
      - name: X-A2A-Mission
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2A-Mission
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendGuardRulesRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/spend-guard/check:
    post:
      tags:
      - spend-guard
      summary: Post Check
      description: Evaluate a proposed purchase BEFORE checkout (appends a check event).
      operationId: post_check_api_v1_spend_guard_check_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: X-A2AWire-Run-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Run-Id
      - name: X-A2AWire-Launch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Launch
      - name: X-A2A-Mission
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2A-Mission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpendGuardCheckRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendGuardCheckResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/spend-guard/record:
    post:
      tags:
      - spend-guard
      summary: Post Record
      description: Record a completed purchase AFTER checkout (idempotent per tx_ref).
      operationId: post_record_api_v1_spend_guard_record_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: X-A2AWire-Run-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Run-Id
      - name: X-A2AWire-Launch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Launch
      - name: X-A2A-Mission
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2A-Mission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpendGuardRecordRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendGuardRecordResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/spend-guard/report:
    get:
      tags:
      - spend-guard
      summary: Get Report
      description: 'Month-to-date spend summary (optional ``month=YYYY-MM`` for a prior

        month; defaults to the current UTC month).'
      operationId: get_report_api_v1_spend_guard_report_get
      parameters:
      - name: month
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Month
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: X-A2AWire-Run-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Run-Id
      - name: X-A2AWire-Launch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2Awire-Launch
      - name: X-A2A-Mission
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2A-Mission
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendGuardReportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SpendGuardCheckResponse:
      properties:
        check_id:
          type: string
          format: uuid
          title: Check Id
        decision:
          type: string
          title: Decision
        reason:
          type: string
          maxLength: 200
          title: Reason
        remaining_monthly_budget_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Remaining Monthly Budget Usd
        merchant:
          type: string
          title: Merchant
        amount_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Amount Usd
      type: object
      required:
      - check_id
      - decision
      - reason
      - remaining_monthly_budget_usd
      - merchant
      - amount_usd
      title: SpendGuardCheckResponse
      description: The verdict for one proposed purchase (Muse reads ``reason`` aloud).
    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
    SpendGuardRecordResponse:
      properties:
        event_id:
          type: string
          format: uuid
          title: Event Id
        tx_ref:
          type: string
          title: Tx Ref
        recorded_previously:
          type: boolean
          title: Recorded Previously
          description: True when this tx_ref was already in your ledger before this call (an idempotent replay); false on first write.
        month_to_date_total_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Month To Date Total Usd
        merchant:
          type: string
          title: Merchant
        amount_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Amount Usd
      type: object
      required:
      - event_id
      - tx_ref
      - recorded_previously
      - month_to_date_total_usd
      - merchant
      - amount_usd
      title: SpendGuardRecordResponse
      description: One recorded purchase (or an idempotent replay of a previous one).
    SpendGuardRulesRead:
      properties:
        owner_id:
          type: string
          format: uuid
          title: Owner Id
        monthly_cap_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Monthly Cap Usd
        per_purchase_threshold_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Per Purchase Threshold Usd
        merchant_denylist:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Merchant Denylist
      type: object
      required:
      - owner_id
      - monthly_cap_usd
      - per_purchase_threshold_usd
      - merchant_denylist
      title: SpendGuardRulesRead
      description: The effective rules. All-null fields mean observation mode.
    SpendGuardMerchantRead:
      properties:
        merchant:
          type: string
          title: Merchant
        total_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Total Usd
        count:
          type: integer
          title: Count
      type: object
      required:
      - merchant
      - total_usd
      - count
      title: SpendGuardMerchantRead
      description: One row of the report's top-merchants breakdown.
    SpendGuardRulesUpsert:
      properties:
        monthly_cap_usd:
          anyOf:
          - type: number
            maximum: 100000.0
            exclusiveMinimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Monthly Cap Usd
          description: Cumulative recorded spend per UTC calendar month at or above which checks deny. Null clears the cap.
        per_purchase_threshold_usd:
          anyOf:
          - type: number
            maximum: 100000.0
            exclusiveMinimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Per Purchase Threshold Usd
          description: A single purchase strictly above this amount asks the user first. Null clears the threshold.
        merchant_denylist:
          anyOf:
          - items:
              type: string
              maxLength: 200
              minLength: 1
            type: array
            maxItems: 100
          - type: 'null'
          title: Merchant Denylist
          description: Exact-match merchant names (case-insensitive) whose purchases are denied, up to 100 entries. Null clears the list.
      type: object
      title: SpendGuardRulesUpsert
      description: Full declaration of the owner's rules; ``None`` clears that rule.
    SpendGuardRecordRequest:
      properties:
        merchant:
          type: string
          maxLength: 200
          minLength: 1
          title: Merchant
        amount_usd:
          anyOf:
          - type: number
            maximum: 100000.0
            exclusiveMinimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount Usd
        currency:
          type: string
          maxLength: 8
          title: Currency
          description: USD only. Kept for forward compatibility; any other value is rejected.
          default: USD
        category:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Category
        description:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Description
        tx_ref:
          type: string
          maxLength: 200
          minLength: 1
          title: Tx Ref
          description: Caller idempotency key, unique across your recorded purchases; replays return the original record.
        check_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Check Id
          description: Optional id from spend_guard_check_purchase; at most one record may consume each check.
      type: object
      required:
      - merchant
      - amount_usd
      - tx_ref
      title: SpendGuardRecordRequest
      description: A completed purchase to ledger AFTER checkout.
    SpendGuardCheckRequest:
      properties:
        merchant:
          type: string
          maxLength: 200
          minLength: 1
          title: Merchant
        amount_usd:
          anyOf:
          - type: number
            maximum: 100000.0
            exclusiveMinimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount Usd
        currency:
          type: string
          maxLength: 8
          title: Currency
          description: USD only. Kept for forward compatibility; any other value is rejected.
          default: USD
        category:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Category
        description:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Description
        tx_ref:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Tx Ref
          description: Optional idempotency key for this purchase; pass the same value to the record call afterwards. Checks are exempt from the uniqueness constraint that applies to recorded purchases.
      type: object
      required:
      - merchant
      - amount_usd
      title: SpendGuardCheckRequest
      description: A proposed purchase to evaluate BEFORE checkout.
    SpendGuardReportResponse:
      properties:
        month:
          type: string
          title: Month
        total_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Total Usd
        purchase_count:
          type: integer
          title: Purchase Count
        top_merchants:
          items:
            $ref: '#/components/schemas/SpendGuardMerchantRead'
          type: array
          title: Top Merchants
        rules:
          $ref: '#/components/schemas/SpendGuardRulesRead'
        remaining_monthly_budget_usd:
          anyOf:
          - type: string
          - type: 'null'
          title: Remaining Monthly Budget Usd
      type: object
      required:
      - month
      - total_usd
      - purchase_count
      - top_merchants
      - rules
      - remaining_monthly_budget_usd
      title: SpendGuardReportResponse
      description: Month-to-date spend summary for the calling owner.
  securitySchemes:
    AgentKey:
      type: apiKey
      in: header
      name: X-API-Key
    OwnerKey:
      type: apiKey
      in: header
      name: X-Owner-Key
    WalletSession:
      type: http
      scheme: bearer