mahastrategies-com x402 Conformance API

openapi: 3.2.0
info:
  title: Maha Strategies MPS x402 Conformance API
  version: '0.1'
  description: 'The Maha Provenance Standard (MPS) API runs claim-level provenance audits over prose. Every factual claim in a passage is excerpted, tagged (VERIFIED, SOURCED, BOUNDARY, ILLUSTRATIVE, UNVERIFIED), and returned with a rationale and a recommended action — so agents and editors can verify before they publish.


    ## Local bridge (CLI)


    Install the open-source local bridge and point Claude Code, Cursor, or any MCP client at it:


    ```sh

    npm install -g @mahastrategies/maha-mcp-bridge

    maha login # verify and store your credential

    maha serve # start the stdio MCP server

    ```


    Raw rows and credentials stay local; only locally-redacted context reaches the agent''s cloud model.


    ## Authentication


    Commercial endpoints use bearer credentials:


    ```

    Authorization: Bearer mhaic_your_credential_here

    ```


    Credentials are shown **exactly once** at purchase. Store them in a secret manager; never commit them, log them, or place them in URLs. Each credential is scoped to the MPS audit capability only — it cannot touch any other service. Lost credentials cannot be recovered, only replaced.


    The free preflight endpoint (`POST /api/audit`) needs no credential and is limited per visitor per day.


    ## The credit system


    Paid audits are prepaid. Each successful audit consumes one `mps_audit_invocation` credit; failed audits are refunded automatically in the same ledger.


    When a credential runs out of credits, the API responds with **`402 Payment Required`**:


    ```json

    {

    "error": { "code": "payment_required", "message": "This prepaid credential has no audit credits remaining." },

    "purchase": { "href": "/mps/audit-access", "checkoutEndpoint": "/api/mps-credits/checkout", "unit": "mps_audit_invocation" }

    }

    ```


    Treat `402` as a routine signal, not an error: follow `purchase.href` to buy another pack, or call the checkout endpoint programmatically. Balances live in an append-only double-entry ledger — every grant, consumption, refund, and manual correction is a permanent, hash-chained row.


    ## Idempotency and webhook resilience


    **Requests**: every audit takes a `clientRequestId` you choose (8–120 characters). Retrying with the same id and the same text returns the original result with `idempotentReplay: true` — never a duplicate charge. The same id with *different* text returns `409 Conflict`. Safe retry loop: keep the same id until you get a terminal status.


    **Payments**: Stripe webhooks are processed exactly once. Each event id is claimed atomically in the same database transaction that moves credits, so a redelivered webhook can never double-credit a balance — duplicates get `200 OK` with `"duplicate": true` and change nothing. A crash between claim and grant rolls both back together. You never need to reconcile double-grants; the ledger cannot express them.'
  contact:
    name: Maha Strategies
    url: https://www.mahastrategies.com/contact
servers:
- url: https://www.mahastrategies.com
tags:
- name: x402 Conformance
  description: Factual protocol and Bazaar discovery observations without trust, security, or uptime scoring.
paths:
  /api/x402-observatory:
    get:
      tags:
      - x402 Conformance
      operationId: getX402ConformanceObservatory
      summary: Read the latest public x402 protocol and discovery observations
      description: Returns factual point-in-time checks from the open x402 conformance observatory. A pass is not a security, quality, uptime, reputation, or trust endorsement.
      security: []
      responses:
        '200':
          description: Latest observation for each explicitly allowlisted public resource.
          content:
            application/json:
              schema:
                type: object
                required:
                - schemaVersion
                - generatedAt
                - scope
                - resources
                properties:
                  schemaVersion:
                    type: string
                    const: 1.0.0
                  generatedAt:
                    type: string
                    format: date-time
                  scope:
                    type: string
                  resources:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - url
                      - operator
                      - boundedSettlementEnabled
                      - latest
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        url:
                          type: string
                          format: uri
                        operator:
                          type: string
                        boundedSettlementEnabled:
                          type: boolean
                        latest:
                          type:
                          - object
                          - 'null'
                          description: Latest append-only observation. Check states are pass, fail, unknown, or not_applicable.
                        lastSuccessfulBoundedSettlementAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        lastSuccessfulBoundedSettlementTransaction:
                          type:
                          - string
                          - 'null'
components:
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.