openapi: 3.0.3
info:
  title: Asicoin RPC/REST Bridge
  version: "1.0.0"
  description: |
    Minimal REST wrapper over the Asicoin node JSON-RPC.
    Endpoints are designed for autonomous agents (AGI/ASI) with deterministic responses.
  contact:
    name: Asicoin
    url: https://www.asicoin.org/
    email: security@asicoin.org
  license:
    name: MIT
servers:
  - url: https://www.asicoin.org/api
tags:
  - name: Blocks
  - name: Transactions
paths:
  /v1/block/{height}:
    get:
      tags: [Blocks]
      operationId: getBlockByHeight
      summary: Get block by height
      parameters:
        - in: path
          name: height
          required: true
          description: Zero-based block height
          schema:
            type: integer
            minimum: 0
      responses:
        "200":
          description: Block summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockSummary"
              examples:
                example:
                  value:
                    height: 12345
                    hash: "0000000000000000000abc123def..."
                    time: 1735234123
                    txCount: 142
        "404":
          description: Block not found
  /v1/tx:
    post:
      tags: [Transactions]
      operationId: broadcastRawTx
      summary: Broadcast raw transaction (hex)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BroadcastRequest"
            examples:
              example:
                value:
                  hex: "0200000001abcd..."
      responses:
        "200":
          description: Broadcast result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BroadcastResult"
              examples:
                accepted:
                  value:
                    txid: "3a9f...c1"
                    accepted: true
                    error: null
                rejected:
                  value:
                    txid: null
                    accepted: false
                    error: "non-mandatory-script-verify-flag"
components:
  schemas:
    BlockSummary:
      type: object
      required: [height, hash, time]
      properties:
        height: { type: integer, example: 12345 }
        hash:   { type: string,  example: "0000000000000000000abc123def..." }
        time:   { type: integer, format: int64, description: "Unix epoch seconds", example: 1735234123 }
        txCount:{ type: integer, description: "Number of txs in this block", example: 142 }
    BroadcastRequest:
      type: object
      required: [hex]
      properties:
        hex:
          type: string
          description: Raw transaction hex
          minLength: 2
    BroadcastResult:
      type: object
      required: [accepted]
      properties:
        txid:
          type: string
          nullable: true
          description: TXID if accepted
        accepted:
          type: boolean
        error:
          type: string
          nullable: true
          description: Reason if rejected
