openapi: 3.0.3
info:
  title: VETS Coin API
  description: |
    Partner + public API for the VETS Coin ecosystem.

    Partner authentication uses an HMAC signature over the request:
    - X-Partner-Key: key id
    - X-Partner-Timestamp: unix epoch seconds
    - X-Partner-Signature: hex(hmac_sha256(secret, "{ts}.{method}.{path}.{body}"))
    - Optional: X-Partner-Nonce (replay protection; server can be configured to require it)
  version: 0.1.0
servers:
  - url: https://api.vets-coin.com
  - url: https://vets-coin.com
tags:
  - name: Public
  - name: Partner
  - name: Salutes
paths:
  /api/public-stats:
    get:
      tags: [Public]
      summary: Public counters and stats
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/transactions/latest:
    get:
      tags: [Public]
      summary: Latest known token transactions
      parameters:
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 200 }
          required: false
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/partner/capabilities:
    get:
      tags: [Partner]
      summary: Partner API capability discovery
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/partner/user-lookup:
    get:
      tags: [Partner]
      summary: Lookup a user by email/username/id
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
        - in: query
          name: q
          schema: { type: string }
          required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/partner/users:
    post:
      tags: [Partner]
      summary: Create a user
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/partner/users/{user_id}:
    get:
      tags: [Partner]
      summary: Get a user
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
        - in: path
          name: user_id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    patch:
      tags: [Partner]
      summary: Update a user (partial)
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
        - in: path
          name: user_id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/partner/users/{user_id}/wallets:
    post:
      tags: [Partner]
      summary: Link a wallet to a user
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
        - in: path
          name: user_id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/partner/webhooks:
    get:
      tags: [Partner]
      summary: List partner webhooks
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
      responses:
        "200":
          description: OK
    post:
      tags: [Partner]
      summary: Create partner webhook
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: OK

  /api/partner/webhooks/{webhook_id}:
    delete:
      tags: [Partner]
      summary: Delete partner webhook
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
        - in: path
          name: webhook_id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: OK

  /api/partner/webhooks/{webhook_id}/test:
    post:
      tags: [Partner]
      summary: Test webhook delivery
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
        - in: path
          name: webhook_id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: OK

  /api/partner/donation-claim:
    post:
      tags: [Partner]
      summary: Issue a donation claim (if enabled)
      parameters:
        - $ref: "#/components/parameters/PartnerKey"
        - $ref: "#/components/parameters/PartnerTimestamp"
        - $ref: "#/components/parameters/PartnerSignature"
        - $ref: "#/components/parameters/PartnerNonce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: OK

  /api/salutes/balance:
    get:
      tags: [Salutes]
      summary: Get salutes balance for the authenticated user
      responses:
        "200":
          description: OK

  /api/salutes/ledger:
    get:
      tags: [Salutes]
      summary: Get salutes ledger for the authenticated user
      responses:
        "200":
          description: OK

  /api/salutes/credit:
    post:
      tags: [Salutes]
      summary: Credit salutes (partner/admin)
      responses:
        "200":
          description: OK

  /api/salutes/debit:
    post:
      tags: [Salutes]
      summary: Debit salutes (partner/admin)
      responses:
        "200":
          description: OK

  /api/salutes/conversion-policy:
    get:
      tags: [Salutes]
      summary: Fetch current salutes conversion policy
      responses:
        "200":
          description: OK

  /api/salutes/convert:
    post:
      tags: [Salutes]
      summary: Convert salutes to VETS (policy-controlled)
      responses:
        "200":
          description: OK

components:
  parameters:
    PartnerKey:
      in: header
      name: X-Partner-Key
      required: true
      schema: { type: string }
      description: Partner key id
    PartnerTimestamp:
      in: header
      name: X-Partner-Timestamp
      required: true
      schema: { type: string }
      description: Unix epoch seconds
    PartnerSignature:
      in: header
      name: X-Partner-Signature
      required: true
      schema: { type: string }
      description: Hex HMAC-SHA256 signature
    PartnerNonce:
      in: header
      name: X-Partner-Nonce
      required: false
      schema: { type: string }
      description: Optional replay-protection nonce

