openapi: 3.2.0
info:
  title: MoltGuard Attestation And Hackathon API
  version: 1.5.0
  description: 'Trust & Integrity Service for the x402 Agent Economy. Sub-API of MolTrust Trust Registry (api.moltrust.ch). See also: https://api.moltrust.ch/openapi.json (parent service).'
  contact:
    name: CryptoKRI GmbH
    url: https://moltrust.ch
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.moltrust.ch/guard
  description: Production
security: []
tags:
- name: attestation-and-hackathon
  description: Wallet attestation + challenge-response + hackathon
paths:
  /api/wallet/attest:
    post:
      tags:
      - attestation-and-hackathon
      summary: Issue a wallet-attestation (DID binding)
      operationId: attestWallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Attestation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAttestResult'
  /api/wallet/attest/{did}:
    get:
      tags:
      - attestation-and-hackathon
      summary: Look up wallet attestation by DID
      operationId: getWalletAttestation
      parameters:
      - name: did
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Attestation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAttestResult'
  /hackathon/register:
    post:
      tags:
      - attestation-and-hackathon
      summary: Register for hackathon (issues API key bypassing x402)
      description: IP-rate-limited. Returns a time-limited hackathon API key.
      operationId: registerHackathon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HackathonRegisterResult'
        '429':
          description: IP rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
  /hackathon/stats:
    get:
      tags:
      - attestation-and-hackathon
      summary: Hackathon participation stats
      operationId: getHackathonStats
      responses:
        '200':
          description: Stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HackathonStats'
  /vc/challenge:
    get:
      tags:
      - attestation-and-hackathon
      summary: Issue a challenge nonce for VC-holder binding
      operationId: getVCChallenge
      responses:
        '200':
          description: Challenge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VCChallenge'
  /vc/register-key:
    post:
      tags:
      - attestation-and-hackathon
      summary: Register a holder public key against a DID
      operationId: registerVCKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VCKeyRegisterResult'
  /vc/verify-binding:
    post:
      tags:
      - attestation-and-hackathon
      summary: Verify a holder signed the challenge nonce
      operationId: verifyVCBinding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Binding result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VCBindingResult'
components:
  schemas:
    HackathonStats:
      type: object
      additionalProperties: true
      properties:
        totalParticipants:
          type: integer
        activeKeys:
          type: integer
    VCBindingResult:
      type: object
      additionalProperties: true
      properties:
        verified:
          type: boolean
    VCKeyRegisterResult:
      type: object
      additionalProperties: true
      properties:
        ok:
          type: boolean
        did:
          type: string
    HackathonRegisterResult:
      type: object
      additionalProperties: true
      properties:
        apiKey:
          type: string
          description: Hackathon-tier API key (bypasses x402)
        expiresAt:
          type: string
          format: date-time
    WalletAttestResult:
      type: object
      additionalProperties: true
      properties:
        ok:
          type: boolean
        did:
          type: string
        address:
          type: string
        signature:
          type: string
    VCChallenge:
      type: object
      additionalProperties: true
      properties:
        challenge:
          type: string
        nonce:
          type: string
        expiresAt:
          type: string
          format: date-time
    RateLimitError:
      type: object
      properties:
        message:
          type: string
          example: 'Free tier: max 1 request(s) per 10 minutes. Use x402 paid endpoints for unlimited access.'
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: 'x402 v2 payment receipt header. Format: "x402 <base64-encoded-receipt>". See https://x402.org/writing/x402-v2-launch.'