openapi: 3.1.0
info:
  title: 區塊勢 Blocktrend x402 API
  description: |
    Programmatic content access and licensing API for 區塊勢 (Blocktrend).
    Content is gated behind the x402 protocol — send an HTTP request, receive
    HTTP 402 with payment requirements, pay via USDC on Base, then
    retry with the X-Payment header to receive the full licensed content.
  version: "2.0"
  contact:
    email: contact@blocktrend.today

servers:
  - url: https://us-central1-x402-blocktrend.cloudfunctions.net
    description: Firebase Cloud Functions (production)

paths:
  /x402Article/list:
    get:
      operationId: listArticles
      summary: List all published articles
      description: Returns a catalog of published articles with title, date, excerpt, price, and article ID. No payment required.
      responses:
        "200":
          description: Array of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Article ID used in x402Article endpoint
                    title:
                      type: string
                    excerpt:
                      type: string
                    published_date:
                      type: string
                      format: date
                    price_amount:
                      type: number
                      description: Price in USDC (e.g. 0.02)

  /x402Article:
    get:
      operationId: getArticle
      summary: Fetch full article content (x402 payment required)
      description: |
        Returns full article content. If no valid payment header is provided,
        responds with HTTP 402 and X-Payment-Required header containing
        Base64-encoded PaymentRequirements JSON. Retry with X-Payment header
        containing the signed EIP-3009 payment to receive the article.
      parameters:
        - name: articleId
          in: query
          required: true
          schema:
            type: string
          description: Article ID from the list endpoint
      responses:
        "200":
          description: Full article content with license receipt
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    type: object
                    properties:
                      title:
                        type: string
                      content:
                        type: string
                      author_name:
                        type: string
                  receipt:
                    type: object
                    properties:
                      nft:
                        type: object
                        properties:
                          tokenId:
                            type: string
                          verifyUrl:
                            type: string
                      certificate:
                        type: object
                        properties:
                          url:
                            type: string
        "402":
          description: Payment required
          headers:
            X-Payment-Required:
              schema:
                type: string
              description: Base64-encoded PaymentRequirements JSON
      security: []

  /serveLlmsTxt:
    get:
      operationId: getLlmsTxt
      summary: Get machine-readable licensing instructions (tracked)
      description: Returns the llms.txt discovery file. This endpoint is tracked — use it to register your agent's interest in content licensing.
      responses:
        "200":
          description: Plain-text licensing instructions
          content:
            text/plain:
              schema:
                type: string