openapi: 3.0.3
info:
  title: NABD Explorer Public API
  version: 1.0.0
  description: "Same-origin APIs implemented by the Bun explorer. These routes provide public chain projections and faucet request intake. They do not submit arbitrary chain transactions. Read APIs reject unsupported or duplicate query parameters and use Cache-Control: no-store. Large integer values remain exact decimal strings where needed; retain them without floating-point conversion. Public projections omit private participant/payload data and internal node origins. Operator, branding administration and static media APIs are documented separately."
servers:
  - url: /
    description: This explorer origin
paths:
  /api/status:
    get:
      summary: Chain identity and public status
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/public-status:
    get:
      summary: Alias of the public chain status facade
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/stats:
    get:
      summary: Public chain counters
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/network/status:
    get:
      summary: Public network observations
      description: "Returns public node aliases, registry membership and bounded observations. Membership does not imply liveness. Internal origins and IP addresses are omitted."
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/explorer/bootstrap:
    get:
      summary: Explorer overview snapshot
      description: "Independent unavailable sections are listed in errors; unavailable counters are null and collections may be empty. This is a composed overview, not proof of chain health."
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Overview"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/blocks:
    get:
      summary: List blocks from configured history
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/blocks/{round}":
    get:
      summary: Read a block by round
      parameters:
        - name: round
          in: path
          required: true
          description: "Nonnegative decimal block round, passed as text to preserve precision."
          schema:
            type: string
        - name: include_proof
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/blocks/hash/{hash}":
    get:
      summary: Read a block by hash
      parameters:
        - name: hash
          in: path
          required: true
          description: Canonical block hash or supported base32 display alias.
          schema:
            type: string
        - name: include_proof
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/transactions:
    get:
      summary: List public transaction records
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/transactions/{hash}":
    get:
      summary: Read a transaction
      description: "Private transaction participant, payload and signature fields remain redacted. include_proof=1 exposes only permitted public certificate evidence, not a cryptographic verification claim."
      parameters:
        - name: hash
          in: path
          required: true
          description: Transaction hash in canonical hex or a supported base32 display alias.
          schema:
            type: string
        - name: include_proof
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/accounts:
    get:
      summary: List accounts
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/accounts/{address}":
    get:
      summary: Read an account and recent activity
      description: Includes up to 50 recent confirmed transactions. transactions_available and pending_available distinguish unavailable history from an empty history.
      parameters:
        - name: address
          in: path
          required: true
          description: NABD display address or canonical 40-hex account/program address.
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/accounts/{address}/transactions":
    get:
      summary: Read paginated confirmed and pending account activity
      description: Confirmed history may use the configured archive; pending transactions use the primary chain source. Pending availability and history source/scope are explicit.
      parameters:
        - name: address
          in: path
          required: true
          description: NABD display address or canonical 40-hex account/program address.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
        - name: include_pending
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 1
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HistoryPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/accounts/{address}/assets":
    get:
      summary: Read native asset holdings with independent cursors
      description: Pass the complete next cursor into the next request; fungible and NFT streams advance independently. Offset pagination is not accepted.
      parameters:
        - name: address
          in: path
          required: true
          description: NABD display address or canonical 40-hex account/program address.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 12
        - name: after_asset_id
          in: query
          description: Canonical decimal cursor through 9223372036854775807. Supply both unit cursors together.
          schema:
            type: string
            pattern: "^(0|[1-9][0-9]{0,18})$"
            default: "0"
        - name: after_unit_asset_id
          in: query
          description: Canonical decimal cursor through 9223372036854775807. Supply both unit cursors together.
          schema:
            type: string
            pattern: "^(0|[1-9][0-9]{0,18})$"
            default: "0"
        - name: after_unit_id
          in: query
          description: Canonical decimal cursor through 9223372036854775807. Supply both unit cursors together.
          schema:
            type: string
            pattern: "^(0|[1-9][0-9]{0,18})$"
            default: "0"
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HoldingsPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/search:
    get:
      summary: "Resolve a transaction, block or account identifier"
      parameters:
        - name: q
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 128
          required: true
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/contracts:
    get:
      summary: List Autonomous Programs
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
        - name: deployer
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProgramPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/contracts/{address}":
    get:
      summary: Read public Autonomous Program metadata
      parameters:
        - name: address
          in: path
          required: true
          description: NABD display address or canonical 40-hex account/program address.
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/contracts/{address}/state":
    get:
      summary: Read a bounded public state page
      description: "Secret-bearing keys and private values are masked. returned counts consumed upstream entries; masked counts omitted entries. Use has_more and next_offset, including when every returned entry was masked."
      parameters:
        - name: address
          in: path
          required: true
          description: NABD display address or canonical 40-hex account/program address.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatePage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/contracts/{address}/executions":
    get:
      summary: Read program execution history
      description: Participant and function fields require a matching explicitly public transaction; missing privacy evidence is redacted.
      parameters:
        - name: address
          in: path
          required: true
          description: NABD display address or canonical 40-hex account/program address.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/executions/{hash}":
    get:
      summary: Read a single program execution
      description: "Opaque return values, raw exception text and unverified participant metadata are not exposed."
      parameters:
        - name: hash
          in: path
          required: true
          description: Transaction hash in canonical hex or a supported base32 display alias.
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicRecord"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/consensus/verify/{round}":
    get:
      summary: "Compare configured validators' block hashes"
      description: "This is an observation comparison. cryptographically_verified is always false. Insufficient nodes, identity mismatches and block-hash disagreements are explicit results."
      parameters:
        - name: round
          in: path
          required: true
          description: "Nonnegative decimal block round, passed as text to preserve precision."
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsensusComparison"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/assets:
    get:
      summary: List native or program-backed assets
      description: Native pages allow limit 200/offset 100000. source=contract caps limit at 50 and offset at 10000 and returns bounded discovery metadata.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
        - name: source
          in: query
          schema:
            type: string
            enum:
              - native
              - contract
            default: native
        - name: type
          in: query
          description: Applies to source=contract; native listing currently ignores this parameter.
          schema:
            type: string
            maxLength: 64
            pattern: "^[a-zA-Z0-9 _-]*$"
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/assets/{identifier}":
    get:
      summary: Read native or program-backed asset metadata
      parameters:
        - name: identifier
          in: path
          required: true
          description: "Native decimal asset ID through 9223372036854775807, or a NABD display/canonical 40-hex program address."
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetDetail"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/assets/{identifier}/balance/{wallet}":
    get:
      summary: Read an exact asset balance or owned NFT units
      description: "Native lookups consume at most ten holdings pages; incomplete pagination returns an error, not a zero balance. Program-backed balances support the documented public balance-map layouts; unsupported layouts return 422."
      parameters:
        - name: identifier
          in: path
          required: true
          description: "Native decimal asset ID through 9223372036854775807, or a NABD display/canonical 40-hex program address."
          schema:
            type: string
        - name: wallet
          in: path
          required: true
          description: NABD display or canonical 40-hex wallet address.
          schema:
            type: string
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetBalance"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: Program balance layout is unsupported
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  "/api/v1/assets/{identifier}/units":
    get:
      summary: List native NFT units
      description: Fungible and program-address requests are rejected with 400.
      parameters:
        - name: identifier
          in: path
          required: true
          description: Native decimal NFT asset ID through 9223372036854775807.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 12
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
        - name: include_burned
          in: query
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
      responses:
        "200":
          description: Public response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnitPage"
        "400":
          description: "Invalid identifier, unsupported or duplicate query parameter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Record not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "Required chain data is unavailable, malformed or incomplete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/faucet/requests:
    post:
      summary: Queue a faucet request
      description: "First fetch /api/v1/faucet/session on this explorer origin and retain its cookie. Send csrf_token as X-NABD-CSRF-Token (or csrf_token in the body), an Origin header matching this explorer, and a fresh CAPTCHA token when required. The response queues a request for operator review; it does not prove issuance or payment confirmation. Request bodies are limited to 16 KiB."
      security:
        - PublicCsrfCookie:
            []
      parameters:
        - name: Origin
          in: header
          required: true
          schema:
            type: string
          description: Must equal the configured public explorer origin.
        - name: X-NABD-CSRF-Token
          in: header
          schema:
            type: string
          description: Use csrf_token from the bootstrap. Required unless csrf_token is supplied in the body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FaucetRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/FaucetRequest"
      responses:
        "202":
          description: Request queued for review
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetQueued"
        "400":
          description: Invalid address or missing CAPTCHA token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Origin, CSRF or CAPTCHA validation failed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: Request body exceeds 16 KiB
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Request rate or address cooldown exceeded; respect Retry-After
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Required CSRF or CAPTCHA protection is unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/faucet/session:
    get:
      summary: Get the public faucet CSRF and CAPTCHA bootstrap
      description: "Returns only csrf_token and public CAPTCHA configuration. Retain the HttpOnly SameSite cookie set by this response, then send csrf_token with a same-origin faucet request. No operator authentication or operator metadata is required or returned."
      responses:
        "200":
          description: Public bootstrap; retain Set-Cookie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetBootstrap"
        "503":
          description: Session protection is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    PublicCsrfCookie:
      type: apiKey
      in: cookie
      name: nabd_csrf
      description: Public signed CSRF cookie established by GET /api/v1/faucet/session. Send the corresponding token in the header or request body and a matching Origin.
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        success:
          type: integer
          enum:
            - 0
        error:
          type: string
    PublicRecord:
      type: object
      additionalProperties: true
      description: Public projected record. Private fields and unsupported opaque data are omitted. Exact integers may be JSON safe integers or decimal strings; clients must not coerce decimal strings to floating point.
    ExactInteger:
      oneOf:
        - type: integer
          minimum: 0
          maximum: 9007199254740991
        - type: string
          pattern: "^[0-9]+$"
      description: Safe JSON integer or an exact decimal string for larger values.
    Status:
      type: object
      required:
        - network_id
        - genesis_hash
      properties:
        network_id:
          type: string
        genesis_hash:
          type: string
          pattern: "^[a-fA-F0-9]{64}$"
        round:
          $ref: "#/components/schemas/ExactInteger"
        current_round:
          $ref: "#/components/schemas/ExactInteger"
    Overview:
      type: object
      required:
        - status
        - stats
        - blocks
        - transactions
        - accounts
        - contracts
        - errors
        - generatedAt
      properties:
        status:
          type: object
          nullable: true
        stats:
          type: object
          nullable: true
        blocks:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        transactions:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        accounts:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        contracts:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        errors:
          type: array
          items:
            type: string
        generatedAt:
          type: string
          format: date-time
    BlockPage:
      type: object
      required:
        - blocks
      properties:
        blocks:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
        history_source:
          type: string
        history_scope:
          type: string
    TransactionPage:
      type: object
      required:
        - transactions
      properties:
        transactions:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
        history_source:
          type: string
        history_scope:
          type: string
    AccountPage:
      type: object
      required:
        - accounts
      properties:
        accounts:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
        history_source:
          type: string
        history_scope:
          type: string
    ProgramPage:
      type: object
      required:
        - contracts
      properties:
        contracts:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
        history_source:
          type: string
        history_scope:
          type: string
    ExecutionPage:
      type: object
      required:
        - executions
      properties:
        executions:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
        history_source:
          type: string
        history_scope:
          type: string
    HistoryPage:
      type: object
      required:
        - address
        - confirmed
        - pending
        - pending_available
        - limit
        - offset
      properties:
        address:
          type: string
        confirmed:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        pending:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        pending_available:
          type: boolean
        limit:
          type: integer
        offset:
          type: integer
        history_source:
          type: string
        history_scope:
          type: string
    HoldingsCursor:
      type: object
      required:
        - after_asset_id
        - after_unit_asset_id
        - after_unit_id
      properties:
        after_asset_id:
          type: string
        after_unit_asset_id:
          type: string
        after_unit_id:
          type: string
    HoldingsPage:
      type: object
      required:
        - success
        - address
        - assets
        - has_more
        - next
        - limit
      properties:
        success:
          type: integer
          enum:
            - 1
        address:
          type: string
        assets:
          type: object
          required:
            - fungible
            - units
          properties:
            fungible:
              type: array
              items:
                $ref: "#/components/schemas/PublicRecord"
            units:
              type: array
              items:
                $ref: "#/components/schemas/PublicRecord"
        has_more:
          type: object
          required:
            - fungible
            - units
          properties:
            fungible:
              type: boolean
            units:
              type: boolean
        next:
          type: object
          required:
            - after_asset_id
            - after_unit_asset_id
            - after_unit_id
          properties:
            after_asset_id:
              type: string
            after_unit_asset_id:
              type: string
            after_unit_id:
              type: string
          nullable: true
        limit:
          type: integer
    SearchResult:
      type: object
      required:
        - success
        - type
        - identifier
      properties:
        success:
          type: integer
          enum:
            - 1
        type:
          type: string
          enum:
            - blocks
            - transactions
            - accounts
        identifier:
          type: string
    StatePage:
      type: object
      required:
        - success
        - contract_address
        - state
        - total
        - returned
        - masked
        - limit
        - offset
        - has_more
        - next_offset
      properties:
        success:
          type: integer
          enum:
            - 1
        contract_address:
          type: string
        state:
          type: array
          items:
            type: object
            required:
              - state_key
              - state_value
            properties:
              state_key:
                type: string
              state_value:
                {}
        total:
          type: integer
        returned:
          type: integer
        masked:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        has_more:
          type: boolean
        next_offset:
          type: integer
          nullable: true
    ConsensusComparison:
      type: object
      required:
        - round
        - comparison
        - cryptographically_verified
        - complete
      properties:
        round:
          type: string
        consensus:
          type: boolean
        comparison:
          type: string
          enum:
            - match
            - mismatch
            - identity_mismatch
            - insufficient
        verification:
          type: string
          enum:
            - node_hash_comparison
        cryptographically_verified:
          type: boolean
          enum:
            - false
        configured_validators:
          type: integer
        compared_nodes:
          type: integer
        complete:
          type: boolean
        observed_at:
          type: string
          format: date-time
        nodes:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/PublicRecord"
    AssetPage:
      type: object
      required:
        - success
        - assets
        - limit
        - offset
        - source
      properties:
        success:
          type: integer
          enum:
            - 1
        assets:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
        source:
          type: string
          enum:
            - native
            - contract
    AssetDetail:
      type: object
      required:
        - success
        - asset
      properties:
        success:
          type: integer
          enum:
            - 1
        asset:
          $ref: "#/components/schemas/PublicRecord"
    AssetBalance:
      type: object
      required:
        - success
        - wallet_address
        - balance
        - units
      properties:
        success:
          type: integer
          enum:
            - 1
        asset_id:
          $ref: "#/components/schemas/ExactInteger"
        contract_address:
          type: string
        wallet_address:
          type: string
        balance:
          type: string
          pattern: "^[0-9]+$"
        units:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
    UnitPage:
      type: object
      required:
        - success
        - asset
        - units
        - limit
        - offset
      properties:
        success:
          type: integer
          enum:
            - 1
        asset:
          $ref: "#/components/schemas/PublicRecord"
        units:
          type: array
          items:
            $ref: "#/components/schemas/PublicRecord"
        limit:
          type: integer
        offset:
          type: integer
    FaucetBootstrap:
      type: object
      required:
        - csrf_token
        - captcha
      properties:
        captcha:
          type: object
          required:
            - provider
            - required
            - enabled
            - site_key
          properties:
            provider:
              type: string
              enum:
                - turnstile
                - recaptcha
            required:
              type: boolean
            enabled:
              type: boolean
            site_key:
              type: string
          additionalProperties: false
        csrf_token:
          type: string
      additionalProperties: false
    FaucetRequest:
      type: object
      required:
        - address
      properties:
        address:
          type: string
          pattern: "^[Nn][Aa][Bb][Dd]1[0-9A-Za-z]{20,100}$"
        email:
          type: string
          maxLength: 160
        note:
          type: string
          maxLength: 500
        captcha_token:
          type: string
          maxLength: 4096
        csrf_token:
          type: string
    FaucetQueued:
      type: object
      required:
        - success
        - request_id
        - status
        - address
        - amount_micro
      properties:
        success:
          type: integer
          enum:
            - 1
        request_id:
          type: string
          pattern: "^[a-f0-9]{24}$"
        status:
          type: string
          enum:
            - queued
        address:
          type: string
        amount_micro:
          type: string
          pattern: "^[1-9][0-9]*$"
        message:
          type: string