AAAA Nexus API

openapi: 3.1.0
info:
  title: AAAA Nexus API
  version: 0.5.1
  description: Formally verified AI safety APIs for autonomous agents. Supports REST, MCP, A2A (Google protocol), and x402 micropayment protocol.
  contact:
    email: atomadic69@gmail.com
    url: https://github.com/atomadictech/aaaa-nexus
servers:
- url: https://atomadic.tech
  description: Production
security: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from https://atomadic.tech/pay
    X402PaymentProof:
      type: apiKey
      in: header
      name: X-Payment-Proof
      description: Base64-encoded USDC payment proof for x402 autonomous payment flow (Base L2, Polygon, or Solana)
    AdminTokenAuth:
      type: apiKey
      in: header
      name: X-Admin-Token
      description: Admin token for privileged operations
  responses:
    PaymentRequired:
      description: 'Payment required. Use x402 protocol: send USDC on Base L2, Polygon, or Solana to the treasury address provided in the response, then retry with the X-Payment-Proof header.'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Payment required
              amount:
                type: string
                example: '0.002'
              currency:
                type: string
                example: USDC
              treasury:
                type: string
                description: Destination wallet address
              chains:
                type: array
                items:
                  type: string
                example:
                - base
                - polygon
                - solana
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
    BadRequest:
      description: Invalid request body or missing required fields.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    HelixStatus:
      type: object
      description: HELIX integrity subsystem status
      properties:
        anti_hallucination:
          type: boolean
        ecc_status:
          type: boolean
        integrity_parity:
          type: boolean
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - user
          - assistant
          - system
          description: Message role
        content:
          type: string
          description: Message content
tags:
- name: Free
  description: Endpoints that require no authentication or payment
- name: Oracle
  description: Entropy oracle and hallucination detection
- name: Security
  description: RatchetGate session security, identity verification, threat scoring, and compliance
- name: Agents
  description: Agent registration, topology, planning, intent classification, and reputation
- name: Inference
  description: LLM inference with built-in hallucination guard
- name: Text
  description: 'Text processing utilities: summarization, sentiment, NER, translation, and more'
- name: Protocol
  description: 'Protocol discovery endpoints: MCP and A2A agent card'
- name: DeFi
  description: 'Decentralized finance: LP optimization, risk scoring, oracle guard, liquidation shield, bridge proof, contract audit, yield oracle'
- name: Compliance
  description: 'Regulatory compliance: EU AI Act, fairness, explainability, lineage, oversight, incidents, transparency'
- name: Payments
  description: Stripe payment sessions, price listing, and payment verification
- name: Forge
  description: 'Model marketplace: leaderboard, quarantine, verification, delta submission, badges'
- name: Shield
  description: 'AAAA Shield: post-quantum key exchange, session management, key rotation'
- name: Delegation
  description: UCAN delegation chain validation, revocation, and depth queries
- name: UCAN
  description: UCAN token creation, verification, revocation, and delegation
- name: Keys
  description: Cryptographic key generation, rotation, and revocation
- name: Credits
  description: Credit balance, usage history, and detailed usage breakdown
- name: Audit
  description: Audit event logging, trail retrieval, and export
- name: Swarm
  description: 'Swarm messaging: relay, broadcast, join, leave, topology, peers'
- name: Trust
  description: Bounded trust scoring and trust history (TCM-100-BoundedMonotonicity)
- name: Reputation
  description: 'Reputation ledger: record interactions, score queries, history'
- name: Escrow
  description: 'Agent-to-agent escrow: create, release, dispute, status'
- name: SLA
  description: 'SLA management: register, report violations, status checks'
- name: VeriRand
  description: Premium verifiable random bytes and batch/stream RNG
- name: VRF
  description: Verifiable random function for gaming draws and verification
- name: Drift
  description: DriftGuard model drift detection and certification
- name: Identity
  description: Agent identity registration, lookup, revocation, and challenges


# --- truncated at 32 KB (184 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atomadic-tech/refs/heads/main/openapi/atomadic-tech-openapi.yml