openapi: 3.1.0
info:
  title: zkOrigoPlus API
  version: 1.0.0
  description: |
    Research-backed compliance-first API for blockchain-banking integration.
    Based on SSRN Abstract 5634150: "Connecting Banking Systems with Blockchain"
  contact:
    email: admin@autodigitalcoin.com
  license:
    name: Proprietary
servers:
  - url: https://api.zkorigoapi.com
    description: Production API
  - url: https://api.zkorigoapi.com/sandbox
    description: Sandbox Environment
security:
  - ApiKeyAuth: []
paths:
  /healthz:
    get:
      summary: Health Check
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: Service healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
  /v1/chain/btc/validate:
    post:
      summary: Bitcoin Address Validation
      operationId: validateBitcoin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainValidationResponse'
  /v1/chain/eth/validate:
    post:
      summary: Ethereum Address Validation
      operationId: validateEthereum
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainValidationResponse'
  /v1/chain/xlm/validate:
    post:
      summary: Stellar Address Validation
      operationId: validateStellar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOOHSUJUJ6"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainValidationResponse'
  /v1/chain/xrpl/validate:
    post:
      summary: XRP Ledger Address Validation
      operationId: validateXRPL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "rN7n7otQDd6FczFgLdlqtyMVrn3HMfXEEK"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainValidationResponse'
  /v1/chain/hbar/validate:
    post:
      summary: Hedera Address Validation
      operationId: validateHedera
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "0.0.123456"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainValidationResponse'
  /v1/chain/matic/validate:
    post:
      summary: Polygon Address Validation
      operationId: validatePolygon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainValidationResponse'
  /v1/aml-unified/check:
    post:
      summary: AML Sanctions Check
      operationId: amlCheck
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address, chain]
              properties:
                address:
                  type: string
                chain:
                  type: string
                  enum: [btc, eth, xlm, xrpl, hbar, matic]
      responses:
        '200':
          description: AML check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMLResponse'
  /v1/iso20022/validate:
    post:
      summary: ISO20022 Message Validation
      operationId: iso20022Validate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message_type, data]
              properties:
                message_type:
                  type: string
                  example: "pain.001"
                data:
                  type: object
      responses:
        '200':
          description: ISO20022 validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ISO20022Response'
  /v1/rwa/attest:
    post:
      summary: Real World Asset Attestation
      operationId: rwaAttest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [asset_type, value]
              properties:
                asset_type:
                  type: string
                  example: "real_estate"
                value:
                  type: number
                metadata:
                  type: object
      responses:
        '200':
          description: RWA attestation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RWAResponse'
  /v1/cbp/validate:
    post:
      summary: Cross-Border Payment Validation
      operationId: cbpValidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from_country, to_country, amount, currency]
              properties:
                from_country:
                  type: string
                  example: "US"
                to_country:
                  type: string
                  example: "GB"
                amount:
                  type: number
                currency:
                  type: string
      responses:
        '200':
          description: CBP validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CBPResponse'
  /v1/usage:
    get:
      summary: Get API Usage Statistics
      operationId: getUsage
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  calls_used:
                    type: integer
                  quota:
                    type: integer
                  plan:
                    type: string
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    ChainValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
        chain:
          type: string
        address:
          type: string
        deterministic_score:
          type: number
          format: float
        risk_level:
          type: string
          enum: [low, medium, high]
    AMLResponse:
      type: object
      properties:
        sanctioned:
          type: boolean
        risk_score:
          type: number
          format: float
        sources:
          type: array
          items:
            type: string
    ISO20022Response:
      type: object
      properties:
        valid:
          type: boolean
        message_type:
          type: string
        compliance_score:
          type: number
          format: float
    RWAResponse:
      type: object
      properties:
        attested:
          type: boolean
        asset_type:
          type: string
        valuation_score:
          type: number
          format: float
    CBPResponse:
      type: object
      properties:
        compliant:
          type: boolean
        corridor:
          type: string
        compliance_score:
          type: number
          format: float
