mahastrategies-com Agentic Commerce API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Agentic Commerce 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: Agentic Commerce
  description: Read-only offer and transaction-policy discovery for agents.
paths:
  /api/health/x402-settlements:
    get:
      tags:
      - Agentic Commerce
      operationId: getSettlementLedgerHealth
      security: []
      summary: Read settlement snapshot freshness without triggering a scan
      description: Read-only operational evidence. Healthy requires a fresh, caught-up saved snapshot. A fallback or stale snapshot returns 503; missing data is not zero transactions.
      responses:
        '200':
          description: Fresh, caught-up saved ledger.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - source
                - stale
                - caughtUp
                - observedAt
                - scannedFromBlock
                - scannedToBlock
                properties:
                  status:
                    type: string
                    enum:
                    - healthy
                    - degraded
                  source:
                    type: string
                    enum:
                    - scheduled_snapshot
                    - bundled_fallback
                  stale:
                    type: boolean
                  caughtUp:
                    type: boolean
                  observedAt:
                    type: string
                    format: date-time
                  scannedFromBlock:
                    type: string
                    pattern: ^[0-9]+$
                  scannedToBlock:
                    type: string
                    pattern: ^[0-9]+$
        '503':
          description: Snapshot is stale, incomplete or falling back; preserve the last successful observation.
  /api/discovery/carp/catalog:
    get:
      tags:
      - Agentic Commerce
      operationId: getCarpSellerCatalogue
      summary: Read the free CABEZON seller product catalogue
      security: []
      description: Array of released digital products and separate enquiry-only physical listings. Digital display prices derive from published x402 base-unit amounts; the live payment challenge remains authoritative. Reading this catalogue creates no order or payment.
      responses:
        '200':
          description: Seller offerings, also available under offers in the CARP seller profile.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - offeringRef
                  - kind
                  - title
                  - descrip
                  - status
                  - price
                  - directSettlement
                  properties:
                    offeringRef:
                      type: string
                    kind:
                      type: string
                      enum:
                      - digital
                      - physical
                    title:
                      type: string
                    descrip:
                      type: string
                    status:
                      type: string
                    price:
                      type:
                      - object
                      - 'null'
                      description: USDC display amount and network for digital offers; null for physical RFQs.
                    directSettlement:
                      type:
                      - object
                      - 'null'
                      description: Published x402 route and exact base-unit terms; null for physical RFQs.
  /api/discovery/agent-infrastructure-compatibility-pack:
    get:
      tags:
      - Agentic Commerce
      operationId: getAgentInfrastructureCompatibilityPackContract
      summary: Inspect the fixed-price Agent Infrastructure Compatibility Pack contract
      description: Returns the exact input and output schemas, fixed price, bounded execution scope, limitations, and failure/refund policy. The runtime is withheld and this read-only route cannot create or pay for a pack.
      security: []
      responses:
        '200':
          description: Public contract. purchase.payableNow remains false until the durable delivery and refund runtime is promoted.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - version
                - name
                - status
                - price
                - purchase
                - execution
                - failureAndRefund
                - limitations
                - inputSchema
                - outputSchema
                - sampleReportUrl
                properties:
                  id:
                    const: agent-infrastructure-compatibility-pack
                  version:
                    const: 1.0.0
                  name:
                    type: string
                  status:
                    const: contract_published_runtime_withheld
                  description:
                    type: string
                  price:
                    type: object
                  deliveryTarget:
                    type: string
                  purchase:
                    type: object
                    required:
                    - payableNow
                    - reason
                    properties:
                      payableNow:
                        const: false
                      reason:
                        type: string
                  execution:
                    type: object
                  failureAndRefund:
                    type: object
                  limitations:
                    type: array
                    items:
                      type: string
                  inputSchema:
                    type: object
                  outputSchema:
                    type: object
                  sampleReportUrl:
                    type: string
                    format: uri
  /api/discovery/agent-infrastructure-compatibility-pack/sample:
    get:
      tags:
      - Agentic Commerce
      operationId: getAgentInfrastructureCompatibilityPackSample
      summary: Inspect a complete sample compatibility report
      description: Returns an illustrative report conforming to the published output schema. It is not a report about a current customer or a certification.
      security: []
      responses:
        '200':
          description: Complete illustrative report.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                $id: https://www.mahastrategies.com/api/discovery/agent-infrastructure-compatibility-pack#output
                title: Agent Infrastructure Compatibility Pack report
                type: object
                additionalProperties: false
                required:
                - version
                - reportId
                - clientRequestId
                - generatedAt
                - inputHash
                - decision
                - summary
                - checks
                - paymentInspection
                - retention
                - limitations
                - refund
                properties:
                  version:
                    const: 1.0.0
                  reportId:
                    type: string
                    pattern: ^compat_[a-f0-9]{32}$
                  clientRequestId:
                    type: string
                    pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{2,119}$
                  generatedAt:
                    type: string
                    format: date-time
                  inputHash:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
                  decision:
                    enum:
                    - compatible
                    - conditionally_compatible
                    - incompatible
                    - inconclusive
                  summary:
                    type: object
                    additionalProperties: false
                    required:
                    - passed
                    - failed
                    - notChecked
                    - highestSeverity
                    properties:
                      passed:
                        type: integer
                        minimum: 0
                      failed:
                        type: integer
                        minimum: 0
                      notChecked:
                        type: integer
                        minimum: 0
                      highestSeverity:
                        enum:
                        - none
                        - low
                        - medium
                        - high
                  checks:
                    type: array
                    minItems: 1
                    maxItems: 50
                    items:
                      type: object
                      additionalProperties: false
                      required:
                      - id
                      - layer
                      - status
                      - severity
                      - summary
                      - evidence
                      - remediation
                      properties:
                        id:
                          type: string
                          pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{2,119}$
                        layer:
                          enum:
                          - identity
                          - protocol
                          - policy
                          - payment
                          - auditability
                        status:
                          enum:
                          - pass
                          - fail
                          - not_checked
                        severity:
                          enum:
                          - info
                          - low
                          - medium
                          - high
                        summary:
                          type: string
                          minLength: 1
                          maxLength: 500
                        evidence:
                          type: array
                          maxItems: 10
                          items:
                            type: object
                            additionalProperties: false
                            required:
                            - sourceUrl
                            - observedAt
                            - digest
                            - observation
                            properties:
                              sourceUrl:
                                type: string
                                format: uri
                                pattern: ^https://
                                maxLength: 500
                              observedAt:
                                type: string
                                format: date-time
                              digest:
                                type: string
                                pattern: ^sha256:[a-f0-9]{64}$
                              observation:
                                type: string
                                minLength: 1
                                maxLength: 500
                        remediation:
                          type:
                          - string
                          - 'null'
                          maxLength: 500
                  paymentInspection:
                    type: object
                    additionalProperties: false
                    required:
                    - challengeObserved
                    - termsWithinPolicy
                    - upstreamSettlementPerformed
                    - reason
                    properties:
                      challengeObserved:
                        type: boolean
                      termsWithinPolicy:
                        type:
                        - boolean
                        - 'null'
                      upstreamSettlementPerformed:
                        const: false
                      reason:
                        type: string
                        minLength: 1
                        maxLength: 500
                  retention:
                    type: object
                    additionalProperties: false
                    required:
                    - credentialsStored
                    - testPayloadsStored
                    - retainedFields
                    properties:
                      credentialsStored:
                        const: false
                      testPayloadsStored:
                        const: false
                      retainedFields:
                        type: array
                        uniqueItems: true
                        items:
                          type: string
                  limitations:
                    type: array
                    minItems: 1
                    uniqueItems: true
                    items:
                      type: string
                  refund:
                    type: object
                    additionalProperties: false
                    required:
                    - status
                    - reason
                    properties:
                      status:
                        enum:
                        - not_applicable
                        - not_eligible
                        - initiated
                        - completed
                      reason:
                        type: string
                        minLength: 1
                        maxLength: 500
                      transaction:
                        type: string
                        pattern: ^0x[a-fA-F0-9]{64}$
  /api/agentic-commerce/offers:
    get:
      tags:
      - Agentic Commerce
      operationId: getAgenticCommerceOffers
      summary: Discover public MPS commercial terms
      description: 'Returns the read-only canonical offer catalog. It cannot create a checkout, disclose a credential, or authorize a payment. Canonical URL: https://www.mahastrategies.com/api/agentic-commerce/offers.'
      responses:
        '200':
          description: Public agentic-commerce discovery document.
          content:
            application/json:
              schema:
                type: object
                required:
                - schema
                - version
                - provider
                - transactionPolicy
                - offers
                properties:
                  schema:
                    type: string
                    format: uri
                  version:
                    type: string
                  provider:
                    type: object
                  discovery:
                    type: object
                  transactionPolicy:
                    type: object
                  offers:
                    type: array
                    minItems: 1
                    items:
                      type: object
  /api/mcp-bridge/manifest:
    get:
      tags:
      - Agentic Commerce
      operationId: getMcpBridgeCompatibility
      summary: Discover local MCP bridge compatibility
      description: Returns the versioned contract for the local commercial bridge and explicitly distinguishes it from the hosted Cognitive Gateway.
      responses:
        '200':
          description: Public compatibility manifest.
          content:
            application/json:
              schema:
                type: object
                required:
                - bridge
                - compatibility
                - security
                properties:
                  bridge:
                    type: object
                  compatibility:
                    type: object
                  security:
                    type: object
                  distinctServices:
                    type: array
components:
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.