openapi.yaml

---
openapi: 3.1.1
info:
  title: ar.io Gateway API
  # Served specs report the running gateway's release in place of this.
  version: '84'
  x-logo:
    url: 'https://ar.io/brand/ario-full-black.svg'
    altText: ar.io
  summary: The HTTP API every ar.io gateway serves, for reading, verifying, querying and uploading permanent data.
  description: |
    ar.io is the open network that makes permanent data fast, verifiable, and
    accessible through independent gateways, without ongoing storage fees or
    dependence on a single vendor. This is the HTTP API each of those
    gateways serves. Data on Arweave is addressed by content, not by host, so
    the same request works against any gateway: pick one near you, or let a
    client such as Wayfinder choose.

    ## What a gateway serves

    - **Data**: any Arweave transaction or ANS-104 data item by ID
      (`/{txId}`, `/raw/{txId}`), with manifest path resolution, byte
      ranges, and caching.
    - **Names**: ArNS names resolve as subdomains of the gateway
      (`https://{name}.{gateway}`), and through `/ar-io/resolver/{name}`.
    - **Queries**: a GraphQL endpoint (`/graphql`) over layer 1
      transactions and bundled data items, filterable by tags, owners and
      block ranges.
    - **Uploads**: signed transactions and data chunks, forwarded to the
      Arweave network.
    - **Arweave node API**: node-compatible routes (`/info`, `/tx/{txId}`,
      `/chunk/{offset}`, blocks, wallets, pricing), so existing Arweave
      clients work unchanged.
    - **Index Sharing**: a gateway can publish index bands at
      `/ar-io/indexes`, signed with its registered observer key: root-TX
      bands, which locate data items inside their bundles, and L1 bands of
      the base layer. Other gateways and clients verify and use them.
    - **The gateway itself**: `/ar-io/info` (release, capabilities),
      `/ar-io/peers`, health checks and metrics.

    ## Verifying what you receive

    A gateway is one party among many, so its responses say what it knows
    about the bytes it served:

    - `X-AR-IO-Digest`: the SHA-256 of the data, when the gateway knows it.
    - `X-AR-IO-Verified`: `true` when the gateway has verified the data
      against its Arweave data root and is serving it from its own cache.
    - `X-AR-IO-Trusted`: whether the data came from a source the gateway
      trusts.
    - `X-AR-IO-Stable`: whether the data's block is past the maximum fork
      depth. Absent when the gateway has no local record of the data.
    - **HTTP message signatures** (RFC 9421, `Signature` and
      `Signature-Input`): when enabled, the gateway signs these headers and,
      through `Content-Digest`, the body, so a client can prove which
      gateway said what.

    For data you need to trust without trusting the gateway, check the
    digest yourself or fetch through a verifying client.

    ## Limits and payments

    Gateways may rate-limit data egress. A request over the limit gets
    `429 Too Many Requests`, or, on a gateway that accepts x402 payments,
    `402 Payment Required` with the price, payable in USDC (then retried
    with an `X-PAYMENT` header). Both are the gateway operator's choice; see
    [x402 and rate limiting](https://github.com/ar-io/ar-io-node/blob/main/docs/x402-and-rate-limiting.md).

    ## Errors

    Standard HTTP status codes. `404` means the gateway could not find the
    data, not that it doesn't exist on Arweave; another gateway may have it.
    A `503` may carry `Retry-After`.

    ## Authentication

    Reading, querying and resolving are unauthenticated. Uploads carry their
    own authorization: every transaction and data item must be signed by the
    wallet paying for it, and the network verifies that signature. Admin
    routes (`/ar-io/admin/*`) require the operator's `ADMIN_API_KEY` as a
    bearer token.

    ## Versions

    Gateways upgrade independently. `info.version` in a served copy of this
    spec (`/openapi.json`) is that gateway's release; `/ar-io/info` reports
    it too.
  contact:
    name: ar.io
    url: https://ar.io
  license:
    name: GNU Affero General Public License v3.0
    identifier: AGPL-3.0-only
externalDocs:
  description: ar.io documentation, including running a gateway
  url: https://docs.ar.io
servers:
  - url: /
    description: The gateway serving this page. Every ar.io gateway serves the same API.
tags:
  - name: Gateway
    description: |
      Operations related to the AR.IO Gateway server itself, including health checks, metrics, and gateway-specific information
  - name: Data
    description: |
      Core data retrieval operations for accessing transaction and data item content. Supports manifest resolution,
      range requests, caching, and verification status. These endpoints serve as the primary interface for retrieving
      data from the Permaweb.
  - name: Network
    description: |
      Get Arweave node info, peers and network status
  - name: Pricing
    description: |
      Get the price (in winston) for an amount of bytes
  - name: Wallets
    description: |
      Get Arweave wallet balance and last transaction information
  - name: Blocks
    description: |
      Get current or historical Arweave block information
  - name: Transactions
    description: |
      Submit a new Arweave transaction or get existing transaction information
  - name: Chunks
    description: |
      Upload Arweave data chunks or get existing chunk offset information
  - name: ArNS
    description: |
      Resolve ArNS names (the ar.io Arweave Name System) and serve their data
  - name: Index Querying
    description: |
      Get data from the AR.IO Gateway index using GQL
  - name: Farcaster Frames
    description: |
      Retrieve and interact with Farcaster Frames using Arweave transactions.
  - name: Admin
    description: |
      Access several password protected features and functions specific to your AR.IO Gateway.
  - name: Rate Limiting
    description: |
      Query and manage rate limit bucket balances. Supports both public balance queries and top-ups via x402 payments or admin authentication.

      **⚠️ EXPERIMENTAL FEATURES**: The rate limiter and x402 payment protocol are experimental features subject to change. API endpoints, parameters, behavior, and configuration options (environment variables) may evolve in future releases as these systems continue to be developed. See [docs/x402-and-rate-limiting.md](https://github.com/ar-io/ar-io-node/blob/develop/docs/x402-and-rate-limiting.md) for details.
  - name: Indexes
    description: |
      Index Sharing: the signed publication of the root-TX and L1 bands
      this gateway offers to other gateways and clients, their files by
      name, by SHA-256 and as a WebSeed, their torrents, an RSS feed of each
      index's torrents for BitTorrent clients to follow, and the tracker
      peers announce to through the gateway's HTTPS. See
      [Index Sharing](https://docs.ar.io/learn/gateways/index-sharing).
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: apiToken
      description: ADMIN_API_KEY set in your .env file.
  parameters:
    RootTransactionIdHint:
      name: X-AR-IO-Root-Transaction-Id
      in: header
      required: false
      schema:
        $ref: '#/components/schemas/Base64Url43'
      description: |
        Optional retrieval hint identifying the root L1 transaction that contains
        the requested ANS-104 data item. The data item ID remains the path
        parameter. The gateway validates this hint and falls back to its normal
        lookup process when the hint is unusable.
      example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
    RootPathHint:
      name: X-AR-IO-Root-Path
      in: header
      required: false
      schema:
        type: string
        pattern: '^[0-9a-zA-Z_-]{43}(\s*,\s*[0-9a-zA-Z_-]{43})*$'
      description: |
        Optional comma-separated traversal path of transaction IDs from the root
        L1 transaction through each parent bundle to the requested ANS-104 data
        item's immediate parent. Use this when the item is nested in multiple
        bundles. Every value must be a 43-character base64url transaction ID.
      example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc,hs48Pj6C9TqAk7W7D3T8F5kWg3q5W7K3m9Gf2L4n8Ps'
    RootItemOffsetHint:
      name: X-AR-IO-Root-Item-Offset
      in: header
      required: false
      schema:
        type: integer
        minimum: 0
      description: |
        Optional byte offset of the complete ANS-104 data item, including its
        header, from the start of the root transaction's data. This header is
        only used when X-AR-IO-Root-Item-Size is also provided, and only for
        requests without a Range header. The gateway reads the item header at
        this offset and serves the payload only if the item's signature
        verifies over it; otherwise the hint is ignored. It is not forwarded to
        other gateways.
      example: 2048
    RootItemSizeHint:
      name: X-AR-IO-Root-Item-Size
      in: header
      required: false
      schema:
        type: integer
        minimum: 1
      description: |
        Optional size of the complete ANS-104 data item, including its header,
        in bytes. This header is only used when X-AR-IO-Root-Item-Offset is also
        provided, under the same conditions: no Range header, and the item's
        signature must verify over the payload it frames. It is not forwarded to
        other gateways.
      example: 2092
  schemas:
    ParquetExportStatus:
      type: object
      description: Status record for a Parquet export job
      properties:
        status:
          type: string
          enum: [not_started, running, completed, errored]
          description: Lifecycle state of the export job
        jobId:
          type: string
          description: Server-assigned id for the job
        outputDir:
          type: string
          description: Directory where Parquet files are being saved
        startHeight:
          type: integer
          description: Starting block height of the export
        endHeight:
          type: integer
          description: Ending block height of the export
        maxFileRows:
          type: integer
          description: Maximum number of rows per Parquet file
        heightPartitionSize:
          type: integer
          description: Blocks per Parquet partition
        skipL1Transactions:
          type: boolean
        skipL1Tags:
          type: boolean
        currentPartitionStart:
          type: integer
          description: First height of the partition currently being exported
        currentPartitionEnd:
          type: integer
          description: Last height of the partition currently being exported
        completedPartitions:
          type: integer
          description: Number of partitions completed so far
        totalPartitions:
          type: integer
          description: Total number of partitions for the job
        durationInSeconds:
          type: number
          description: Duration of the export process in seconds
        endTime:
          type: string
          format: date-time
          description: ISO timestamp when the export completed
        endTimestamp:
          type: integer
          description: Unix timestamp (ms) when the export completed
        error:
          type: string
          description: Error message if the export failed
      required:
        - status
    Base64Url:
      type: string
      pattern: '^[A-Za-z0-9_-]+$'
    Base64Url43:
      type: string
      pattern: '^[0-9a-zA-Z_-]{43}$'
    Base64Url64:
      type: string
      pattern: '^[0-9a-zA-Z_-]{64}$'
    Base64Url4364:
      type: string
      pattern: '^[0-9a-zA-Z_-]{43}$|^[0-9a-zA-Z_-]{64}$'
    WinstonAmount:
      type: string
      pattern: '^[0-9]{1,21}$'
    NumericString:
      type: string
      pattern: '^[0-9]+$'
    IntegerOrNumericString:
      description: A value that can be either an integer or a string representation of an integer
      anyOf:
        - type: integer
        - type: string
          pattern: '^[0-9]+$'
    TagList:
      type: array
      maxItems: 2048
      items:
        type: object
        properties:
          name:
            type: string
            pattern: '^[0-9a-zA-Z_-]{1,2731}$'
          value:
            type: string
            pattern: '^[0-9a-zA-Z_-]{1,2731}$'
    Owner:
      type: string
      pattern: '^[0-9a-zA-Z_-]{1,683}$'
    Signature:
      type: string
      pattern: '^[0-9a-zA-Z_-]{1,683}$'
    L1TransactionHeader:
      type: object
      description: |
        A signed Arweave L1 transaction header (the same JSON shape returned by
        `GET /tx/:id`). The signature is verified server-side, so every
        consequential field (data_root, owner, target, quantity, reward,
        last_tx, tags, data_size) is bound to the signature.
      properties:
        id:
          $ref: '#/components/schemas/Base64Url43'
          description: Transaction ID (sha256 of the signature)
        owner:
          $ref: '#/components/schemas/Owner'
          description: Transaction signer's public key
        signature:
          $ref: '#/components/schemas/Signature'
          description: Transaction signature
        last_tx:
          type: string
          description: Anchor (a recent block hash or tx ID)
        data_root:
          $ref: '#/components/schemas/Base64Url43'
          description: Merkle root of the transaction's data
        data_size:
          type: string
          description: Size of the data in bytes (stringified integer)
        format:
          type: integer
          description: Transaction format (2 for current data transactions)
        target:
          type: string
          description: Optional recipient address
        quantity:
          type: string
          description: Optional transfer amount in winston (stringified integer)
        reward:
          type: string
          description: Mining reward in winston (stringified integer)
        tags:
          $ref: '#/components/schemas/TagList'
          description: Optional transaction tags
      required:
        - id
        - owner
        - signature
        - last_tx
    ByteRange:
      type: string
      pattern: '^bytes=\d*-\d*(?:,\d*-\d*)*$'
      description: |
        HTTP byte range specifying which parts of the data to retrieve.
        Supports single ranges (e.g. "bytes=0-1023") and multiple ranges (e.g. "bytes=0-50,100-150").
      example: 'bytes=0-1023'
    CacheStatus:
      type: string
      enum: [HIT, MISS]
      description: Indicates whether the data was served from cache
    VerificationStatus:
      type: string
      enum: [true, false]
      description: Indicates whether the data has been verified
    Block:
      type: object
      properties:
        usd_to_ar_rate:
          type: array
          minItems: 2
          maxItems: 2
          items:
            $ref: '#/components/schemas/Base64Url'
        scheduled_usd_to_ar_rate:
          type: array
          minItems: 2
          maxItems: 2
          items:
            $ref: '#/components/schemas/Base64Url'
        packing_2_5_threshold:
          $ref: '#/components/schemas/Base64Url'
        strict_data_split_threshold:
          $ref: '#/components/schemas/NumericString'
        nonce:
          $ref: '#/components/schemas/Base64Url'
        previous_block:
          $ref: '#/components/schemas/Base64Url64'
        timestamp:
          type: integer
        last_retarget:
          type: integer
        diff:
          $ref: '#/components/schemas/IntegerOrNumericString'
        height:
          type: integer
        hash:
          $ref: '#/components/schemas/Base64Url4364'
        txs:
          type: array
          minItems: 0
          maxItems: 1000
          items:
            $ref: '#/components/schemas/Base64Url43'
        tx_root:
          $ref: '#/components/schemas/Base64Url43'
        tx_tree:
          type: array
          maxItems: 0
          items:
            type: string
        wallet_list:
          $ref: '#/components/schemas/Base64Url4364'
        reward_addr:
          $ref: '#/components/schemas/Base64Url43'
        tags:
          $ref: '#/components/schemas/TagList'
        reward_pool:
          # TODO add length restriction
          $ref: '#/components/schemas/IntegerOrNumericString'
        weave_size:
          $ref: '#/components/schemas/IntegerOrNumericString'
        block_size:
          $ref: '#/components/schemas/IntegerOrNumericString'
        cumulative_diff:
          $ref: '#/components/schemas/NumericString'
        hash_list_merkle:
          $ref: '#/components/schemas/Base64Url64'
        poa:
          type: object
          properties:
            option:
              $ref: '#/components/schemas/NumericString'
            tx_path:
              # TODO specify length
              $ref: '#/components/schemas/Base64Url'
            data_path:
              # TODO specify length
              $ref: '#/components/schemas/Base64Url'
            chunk:
              # TODO specify length
              $ref: '#/components/schemas/Base64Url'
      required:
        - nonce
        - previous_block
        - timestamp
        - last_retarget
        - diff
        - height
        - hash
        - indep_hash
        - txs
        - tx_root
        - wallet_list
        - reward_addr
        - tags
        - reward_pool
        - weave_size
        - block_size
        - poa
    Chunk:
      type: object
      properties:
        tx_path:
          $ref: '#/components/schemas/Base64Url'
        packing:
          type: string
          # TODO add all types
          pattern: '^unpacked$'
        data_path:
          $ref: '#/components/schemas/Base64Url'
        chunk:
          $ref: '#/components/schemas/Base64Url'
      required:
        - tx_path
        - packing
        - data_path
        - chunk
    Transaction:
      type: object
      properties:
        format:
          type: integer
        id:
          $ref: '#/components/schemas/Base64Url43'
        last_tx:
          $ref: '#/components/schemas/Base64Url4364'
        owner:
          $ref: '#/components/schemas/Owner'
        tags:
          $ref: '#/components/schemas/TagList'
        target:
          $ref: '#/components/schemas/Base64Url43'
        quantity:
          $ref: '#/components/schemas/WinstonAmount'
        data:
          $ref: '#/components/schemas/Base64Url'
        data_tree:
          type: array
          items:
            # TODO determine contents of array (is this just for v1?)
            type: string
        data_root:
          $ref: '#/components/schemas/Base64Url'
        reward:
          $ref: '#/components/schemas/WinstonAmount'
        signature:
          $ref: '#/components/schemas/Signature'
      required:
        - format
        - id
        - last_tx
        - owner
        - tags
        - target
        - quantity
        - data
        - data_tree
        - data_root
        - reward
        - signature
    TransactionOffset:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/NumericString'
        offset:
          $ref: '#/components/schemas/NumericString'
      required:
        - size
        - offset
    TransactionStatus:
      type: object
      properties:
        block_height:
          type: integer
        block_indep_hash:
          $ref: '#/components/schemas/Base64Url64'
        number_of_confirmations:
          type: integer
      required:
        - block_height
        - block_indep_hash
        - number_of_confirmations
    Mempool:
      type: array
      items:
        $ref: '#/components/schemas/Base64Url43'
    NetworkInfo:
      type: object
      properties:
        network:
          type: string
        version:
          type: integer
        release:
          type: integer
        current:
          $ref: '#/components/schemas/Base64Url64'
        blocks:
          type: integer
        peers:
          type: integer
        queue_length:
          type: integer
        node_state_latency:
          type: integer
      required:
        - network
        - version
        - release
        - current
        - blocks
        - peers
        - queue_length
        - node_state_latency
    PeerList:
      type: array
      items:
        type: string
        pattern: '^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}:\d+$'
    Height:
      type: string
      pattern: '^[0-9]{16}$'
    ArNSResolution:
      type: object
      description: Response containing ArNS name resolution details
      properties:
        txId:
          $ref: '#/components/schemas/Base64Url43'
          description: The resolved transaction ID
        ttlSeconds:
          type: integer
          description: Time-to-live in seconds for this resolution
        antId:
          type: string
          description: |
            Per-ANT identifier for the ANT that resolved this name — the
            ANT mint's PDA (base58 pubkey). Omitted when resolution came
            via a trusted-gateway peer that has not yet shipped the
            X-ArNS-Ant-Id header.
        resolvedAt:
          type: integer
          description: Unix timestamp when the name was resolved
        index:
          type: integer
          description: Index of the name in the sorted list of names
        limit:
          type: integer
          description: The undername limit for the base ArNS name
      required:
        - txId
        - ttlSeconds
        - resolvedAt
        - index
        - limit
  requestBodies:
    QueueTxRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Base64Url43'
                description: TX ID of the transaction you would like to prioritize.
          examples:
            example1:
              value:
                id: '3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ'
  responses:
    MissingId:
      description: Bad Request. Id is required.
      content:
        text/plain:
          schema:
            type: string
            example: "Must provide 'id'"
    MissingIdOrBypassFilter:
      description: Bad Request. The request is missing required parameters.
      content:
        text/plain:
          schema:
            type: string
          examples:
            missingId:
              summary: ID is required
              value: "Must provide 'id'"
            missingFilter:
              summary: bypassFilter must be a boolean
              value: "'bypassFilter' must be a boolean"
    QueueTxSuccess:
      description: Successful operation
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'TX queued'
            required:
              - message
    Unauthorized:
      description: Unauthorized
      content:
        text/plain:
          schema:
            type: string
            example: 'Unauthorized'
    ServerError:
      description: Internal Server Error
      content:
        text/plain:
          schema:
            type: string
            example: 'Internal Server Error'

paths:
  # Gateway
  '/':
    get:
      tags: [Gateway]
      summary: Gateway Info or Apex Content
      description: |
        Returns either gateway information or serves content based on configuration:

        - If neither APEX_TX_ID nor APEX_ARNS_NAME is set, returns gateway information
        - If APEX_TX_ID is set, serves that transaction's content
        - If APEX_ARNS_NAME is set, resolves and serves that ArNS name's content

        The Content-Type of the response will match the content type of the transaction or ArNS-resolved data (e.g., text/html for HTML documents, application/json for JSON documents, application/octet-stream for binary data, etc.).
      responses:
        '200':
          description: |-
            Either gateway information or transaction/ArNS content
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Gateway information
                    properties:
                      wallet:
                        $ref: '#/components/schemas/Base64Url43'
                        description: Gateway wallet address
                      ans104UnbundleFilter:
                        type: object
                        description: Configuration for ANS-104 unbundling filter
                      ans104IndexFilter:
                        type: object
                        description: Configuration for ANS-104 indexing filter
                      supportedManifestVersions:
                        type: array
                        description: List of supported manifest versions
                        items:
                          type: string
                          enum: ['0.1.0', '0.2.0']
                      release:
                        type: string
                        description: Gateway software release version
                    required:
                      - supportedManifestVersions
                      - release
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Transaction or ArNS content when APEX_TX_ID or APEX_ARNS_NAME is set
  '/ar-io/healthcheck':
    get:
      tags: [Gateway]
      summary: Health check endpoint
      description: Get the current health status of the AR.IO Gateway.
      responses:
        '200':
          description: Health check response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok, unhealthy]
                    description: Current health status of the gateway
                  uptime:
                    type: number
                    description: Process uptime in seconds
                  date:
                    type: string
                    format: date-time
                    description: Current server timestamp
                  reasons:
                    type: array
                    items:
                      type: string
                    description: Array of reasons if status is unhealthy
                required:
                  - status
                  - uptime
                  - date
  '/ar-io/offsets/{id}':
    get:
      tags: [Gateway]
      summary: Get root transaction offsets for a data item
      description: |
        Returns the location of a data item within its root L1 transaction,
        from this node's own data: its index first, then CDB64 indexes on its
        local disk, such as bands installed by Index Sharing.

        This is the cheap counterpart to `HEAD /raw/{id}`, which exposes the
        same values in `X-AR-IO-Root-*` headers but only as a side effect of a
        successful data retrieval — on a cache miss that route runs the node's
        entire retrieval cascade before answering. This endpoint never reads
        contiguous data and never makes a network request. A hit costs one
        index read; a miss costs that plus a read or two per local CDB64
        index.

        Offsets resolve for any data item this node has unbundled and indexed,
        or that an installed CDB64 index covers, even when none of its bytes
        are cached locally. CDB64 indexes are consulted only while `cdb` is
        in `ROOT_TX_LOOKUP_ORDER`, as it is by default.

        A 200 is cached for `CACHE_DEFAULT_MAX_AGE` seconds, short because a
        band can be replaced or withdrawn; a 404 for `CACHE_NOT_FOUND_MAX_AGE`
        seconds with `must-revalidate`; a 500 is `no-store`.

        A 200 is signed with HTTP Message Signatures (when the gateway signs
        responses, the default), with `Content-Digest` binding the body, so
        it is this gateway's attributable claim. The offsets are still a
        claim, not proof: confirm them by reading the data item header at
        `rootOffset` (its ID must match) or with a chunk proof. An answer from
        a CDB64 index never includes `contentType` or `dataSize`.
      parameters:
        - name: id
          in: path
          required: true
          description: The 43-character base64url data item or transaction ID.
          schema:
            type: string
            pattern: '^[a-zA-Z0-9_-]{43}$'
      responses:
        '200':
          description: Offsets resolved from the local index or a local CDB64 index
          headers:
            Cache-Control:
              description: '`public, max-age=<CACHE_DEFAULT_MAX_AGE>`'
              schema:
                type: string
            X-AR-IO-Root-Transaction-Id:
              description: The root transaction ID, as in the body. Its presence makes the response signed.
              schema:
                type: string
            Content-Digest:
              description: RFC 9530 SHA-256 digest of the response body, covered by the signature.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  rootTxId:
                    type: string
                    description: base64url ID of the root L1 transaction containing the data item.
                  path:
                    type: array
                    items:
                      type: string
                    description: |
                      Bundle traversal path from root to the immediate parent
                      bundle. From the local index, only emitted in the
                      single-level case, where the parent is the root bundle;
                      a CDB64 index may give the full path.
                  rootOffset:
                    type: integer
                    description: Byte offset of the data item header within the root transaction's data.
                  rootDataOffset:
                    type: integer
                    description: Byte offset of the data item's payload within the root transaction's data.
                  contentType:
                    type: string
                    description: Content type of the data item, when known. Never set by a CDB64 index.
                  size:
                    type: integer
                    description: Total size of the data item in bytes, including its header.
                  dataSize:
                    type: integer
                    description: Size of the data item's payload in bytes, excluding its header. Never set by a CDB64 index.
                required:
                  - rootTxId
        '400':
          description: Invalid data ID
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: |
            This node cannot place the ID inside a root transaction — the ID is
            unknown to its index, or has no indexed root parent, and no local
            CDB64 index covers it.
          headers:
            Cache-Control:
              description: '`public, max-age=<CACHE_NOT_FOUND_MAX_AGE>, must-revalidate`'
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Failed to resolve offsets
          headers:
            Cache-Control:
              description: '`no-store`'
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
  '/ar-io/info':
    get:
      tags: [Gateway]
      summary: Get AR.IO Gateway information
      description: |
        Returns information about the AR.IO Gateway, including:
        - Gateway wallet address
        - The AR.IO Network's Solana program IDs
        - ANS-104 filter configurations
        - Supported manifest versions
        - Gateway software release version
        - Bundler service URLs for data upload service discovery
        - Rate limiter configuration (if enabled)
        - x402 payment protocol configuration (if enabled)
        - HTTPSIG response signing configuration (if enabled)
        - The indexes it publishes, and their feeds (if it publishes any)
      responses:
        '200':
          description: Gateway information response
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet:
                    type: string
                    description: The gateway's registered wallet (`AR_IO_WALLET`), a Solana address
                    example: '34LYvMptiDvBP5sqfh1oAd6Q4qFsy4PWaZ1HTFmML7h5'
                  programIds:
                    type: object
                    description: The AR.IO Network's Solana program IDs this gateway reads protocol state from
                    properties:
                      core:
                        type: string
                        example: '73YoECm6NKXpVRoe5f1Q9BcP5DJGPFUjnFy6AxBE5Nvh'
                      gar:
                        type: string
                        example: '89fNiiwgpFSPHKuqfNUkgYTYjtAJAhyqHjXmgXeppGpf'
                      arns:
                        type: string
                        example: '2yCUx5edFvUrkibYaUa2ZXWyx9kuJkS8CwyzsgHPWdZZ'
                      ant:
                        type: string
                        example: '2MWexMHfMhGJwMHv9Qm9YAVCqjUFUJwDJAysW4oCUGk5'
                  ans104UnbundleFilter:
                    type: object
                    description: Configuration for ANS-104 unbundling filter
                  ans104IndexFilter:
                    type: object
                    description: Configuration for ANS-104 indexing filter
                  supportedManifestVersions:
                    type: array
                    description: List of supported manifest versions
                    items:
                      type: string
                      enum: ['0.1.0', '0.2.0']
                  release:
                    type: string
                    description: Gateway software release version
                  services:
                    type: object
                    description: Service discovery information
                    properties:
                      bundlers:
                        type: array
                        description: List of bundler service URLs for data upload service discovery
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              format: uri
                              description: Bundler service URL
                              example: 'https://turbo.ardrive.io/'
                          required:
                            - url
                    required:
                      - bundlers
                  rateLimiter:
                    type: object
                    description: Rate limiter configuration (only present when rate limiting is enabled)
                    properties:
                      enabled:
                        type: boolean
                        description: Whether rate limiting is enabled
                        example: true
                      dataEgress:
                        type: object
                        description: Data egress rate limiting configuration
                        properties:
                          buckets:
                            type: object
                            description: Token bucket configurations for rate limiting
                            properties:
                              resource:
                                type: object
                                description: Per-resource (transaction ID) rate limits
                                properties:
                                  capacity:
                                    type: number
                                    description: Maximum tokens in bucket (1 token = 1 KiB)
                                    example: 1000000
                                  refillRate:
                                    type: number
                                    description: Tokens added per second
                                    example: 100
                                  capacityBytes:
                                    type: number
                                    description: Maximum bytes in bucket (capacity * 1024)
                                    example: 1024000000
                                  refillRateBytesPerSec:
                                    type: number
                                    description: Bytes added per second (refillRate * 1024)
                                    example: 102400
                                required:
                                  - capacity
                                  - refillRate
                                  - capacityBytes
                                  - refillRateBytesPerSec
                              ip:
                                type: object
                                description: Per-IP address rate limits
                                properties:
                                  capacity:
                                    type: number
                                    description: Maximum tokens in bucket (1 token = 1 KiB)
                                    example: 100000
                                  refillRate:
                                    type: number
                                    description: Tokens added per second
                                    example: 20
                                  capacityBytes:
                                    type: number
                                    description: Maximum bytes in bucket (capacity * 1024)
                                    example: 102400000
                                  refillRateBytesPerSec:
                                    type: number
                                    description: Bytes added per second (refillRate * 1024)
                                    example: 20480
                                required:
                                  - capacity
                                  - refillRate
                                  - capacityBytes
                                  - refillRateBytesPerSec
                            required:
                              - resource
                              - ip
                        required:
                          - buckets
                    required:
                      - enabled
                      - dataEgress
                  x402:
                    type: object
                    description: x402 payment protocol configuration (only present when x402 is enabled)
                    properties:
                      enabled:
                        type: boolean
                        description: Whether x402 payment protocol is enabled
                        example: true
                      network:
                        type: string
                        description: Blockchain network for payments
                        enum: ['base', 'base-sepolia']
                        example: 'base-sepolia'
                      walletAddress:
                        type: string
                        description: Gateway wallet address for receiving payments
                        example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
                      facilitatorUrl:
                        type: string
                        format: uri
                        description: x402 facilitator service URL
                        example: 'https://x402.org/facilitator'
                      dataEgress:
                        type: object
                        description: Data egress payment configuration
                        properties:
                          pricing:
                            type: object
                            description: Pricing information for data egress
                            properties:
                              perBytePrice:
                                type: string
                                description: Price in USDC per byte, as a decimal string (never exponent notation)
                                example: '0.0000000001'
                              minPrice:
                                type: string
                                description: Minimum price in USDC per request, as a decimal string
                                example: '0.001000'
                              maxPrice:
                                type: string
                                description: Maximum price in USDC per request, as a decimal string
                                example: '1.000000'
                              currency:
                                type: string
                                description: Payment currency
                                enum: ['USDC']
                                example: 'USDC'
                              exampleCosts:
                                type: object
                                description: Example costs for common data sizes
                                properties:
                                  1KB:
                                    type: number
                                    description: Cost for 1 kilobyte in USDC
                                    example: 0.001
                                  1MB:
                                    type: number
                                    description: Cost for 1 megabyte in USDC
                                    example: 0.0001024
                                  1GB:
                                    type: number
                                    description: Cost for 1 gigabyte in USDC
                                    example: 0.1048576
                                required:
                                  - 1KB
                                  - 1MB
                                  - 1GB
                            required:
                              - perBytePrice
                              - minPrice
                              - maxPrice
                              - currency
                              - exampleCosts
                          rateLimiterCapacityMultiplier:
                            type: number
                            description: Capacity multiplier for paid tier (applied to rate limiter buckets)
                            example: 10
                        required:
                          - pricing
                          - rateLimiterCapacityMultiplier
                    required:
                      - enabled
                      - network
                      - walletAddress
                      - facilitatorUrl
                      - dataEgress
                  httpsig:
                    type: object
                    description: |
                      RFC 9421 HTTP Message Signature configuration, present only when
                      HTTPSIG is enabled. Responses are signed with the observer's key
                      when `OBSERVER_PRIVATE_KEY` or `OBSERVER_KEYPAIR_PATH` is set, so a
                      signature verifies against the observer address registered for the
                      gateway on chain. Otherwise they are signed with a key generated at
                      `HTTPSIG_KEY_FILE`, which is registered nowhere.
                    properties:
                      algorithm:
                        type: string
                        description: Signature algorithm
                        enum: ['ed25519']
                        example: 'ed25519'
                      solanaAddress:
                        type: string
                        description: The Solana address of the key that signs responses (base58)
                        example: 'FJwaz3DWJ2TuDRDaBRsE7t29LDm1wB8txPHcBNoCDwkt'
                    required:
                      - algorithm
                      - solanaAddress
                  indexes:
                    type: object
                    description: |
                      Index artifacts this gateway publishes through its index-swarm
                      sidecar. Present only while a valid publication exists, so a
                      crawler can decide whether this gateway offers anything it
                      wants without fetching the document. A node that serves an
                      operator's indexes without signing them
                      (`INDEXES_ADVERTISE_FROM_URL`) advertises the signing node's
                      publication here instead, while its own `/ar-io/indexes`
                      answers 404; behind a load balancer that routes
                      `/ar-io/indexes*` to the signing node, both answers agree.
                    properties:
                      manifestUrl:
                        type: string
                        description: Where the signed publication document is served
                        example: '/ar-io/indexes'
                      names:
                        type: array
                        description: Names of the indexes currently published, sorted
                        items:
                          type: string
                        example: ['root-tx-index']
                      feeds:
                        type: object
                        description: |
                          The RSS feed of each index that has a band offered as a
                          torrent, relative to this gateway (see
                          `/ar-io/indexes/feed/{index}.xml`). A BitTorrent client
                          subscribed to one follows that index. Present only when
                          the gateway serves a feed, which needs a public origin
                          (INDEXES_PUBLIC_URL, or ARNS_ROOT_HOST).
                        additionalProperties:
                          type: string
                        example:
                          parquet-l1: '/ar-io/indexes/feed/parquet-l1.xml'
                    required:
                      - manifestUrl
                      - names
                required:
                  - supportedManifestVersions
                  - release
                  - services
  '/ar-io/indexes':
    get:
      tags: [Indexes]
      summary: Get the index publication this gateway offers
      description: |
        Returns the signed document listing the bands this gateway's
        index-swarm sidecar publishes: each index, its bands, and every file in
        each band with its size and SHA-256. The document carries a detached
        Ed25519 signature by the gateway's registered observer key, so it
        verifies against the gateway registry however it was obtained. When
        HTTPSIG_ENABLED is set, the live response is also signed with
        HTTPSIG, covering Content-Digest; a client must not require that
        signature, since the detached one is what proves the document.

        The byte routes below serve only what this document lists.
        404 when the gateway publishes nothing. Not rate limited, so a client
        that has run out of tokens can still learn what it could fetch. HEAD
        is supported.

        Every error response on the six /ar-io/indexes routes (document,
        file by name, blob, torrent, WebSeed and feed) carries
        `Cache-Control: no-store`. Only 200, 206 and 304 carry a cacheable
        value. See docs/index-swarm.md, "Running behind nginx".
      responses:
        '200':
          description: The publication document.
          headers:
            Cache-Control:
              schema: { type: string, example: 'public, max-age=60' }
            ETag:
              schema: { type: string }
            Content-Digest:
              schema: { type: string }
              description: RFC 9530 SHA-256 of the body.
            x-ar-io-index-publication:
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
        '304':
          description: Not modified.
        '404':
          description: 'Nothing published. Body `{}`, `Cache-Control: no-store`.'
  '/ar-io/indexes/{name}/{band}/{file}':
    get:
      tags: [Indexes]
      summary: Get a published index file by name
      description: |
        Serves one file of a published band. Rate limited and priced as data
        egress. Supports a single byte range; several ranges get the whole
        file. The bytes are read from the publisher's hard link for the
        listed digest. 503 with Retry-After while that link is missing or
        disagrees with the publication during a band update. Success
        responses carry `Cache-Control: public, no-cache`, or
        `private, no-cache` when the gateway meters these routes (a rate
        limiter or x402 is configured). Error responses carry
        `Cache-Control: no-store`. Only a publisher serves this route; a
        subscriber answers 404.
      parameters:
        - { name: name, in: path, required: true, schema: { type: string } }
        - { name: band, in: path, required: true, schema: { type: string } }
        - { name: file, in: path, required: true, schema: { type: string } }
        - { name: Range, in: header, required: false, schema: { type: string } }
      responses:
        '200':
          description: The whole file.
          headers:
            Cache-Control: { schema: { type: string, example: 'public, no-cache' }, description: '`private, no-cache` when the gateway meters the byte routes.' }
            ETag: { schema: { type: string }, description: The file's SHA-256, quoted. }
            X-AR-IO-Index-File: { schema: { type: string }, description: 'The SHA-256 the publication lists for this file, hex. An HTTPSIG trigger: the response is signed.' }
            Repr-Digest: { schema: { type: string }, description: RFC 9530 SHA-256 of the whole file. Covered by the signature. }
            Content-Digest: { schema: { type: string }, description: RFC 9530 SHA-256 of this body. Covered by the signature. }
            Signature: { schema: { type: string }, description: RFC 9421 signature (when HTTPSIG_ENABLED) }
            Signature-Input: { schema: { type: string }, description: RFC 9421 covered components, key ID and creation time }
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '206':
          description: A byte range of the file. Carries Repr-Digest but not Content-Digest. When HTTPSIG_ENABLED is set it is signed, the signature covering Repr-Digest.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '304':
          description: Not modified.
        '400':
          description: Malformed name or range.
        '402':
          description: Payment required (x402), when rate limited and payments are enabled.
        '404':
          description: Not listed in the publication.
        '416':
          description: Range not satisfiable.
        '429':
          description: Rate limited.
        '503':
          description: The file is being updated or its digest has no link yet; retry.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema: { type: string }
  '/ar-io/indexes/blob/{sha256}':
    get:
      tags: [Indexes]
      summary: Get a published index file by content address
      description: |
        The same bytes as the named route, addressed by SHA-256, so a client
        that knows a digest can fetch it from any gateway publishing it.
        Rate limited, priced and signed like the named route, with the same
        headers, except that success responses carry
        `Cache-Control: public, max-age=31536000, immutable`, or
        `private, max-age=31536000, immutable` when the gateway meters the
        byte routes. Error responses carry `Cache-Control: no-store`.
      parameters:
        - { name: sha256, in: path, required: true, schema: { type: string, pattern: '^[0-9a-f]{64}$' } }
      responses:
        '200':
          description: The file.
          headers:
            Cache-Control: { schema: { type: string, example: 'public, max-age=31536000, immutable' }, description: '`private, max-age=31536000, immutable` when the gateway meters the byte routes.' }
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '206':
          description: A byte range of the file.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '304':
          description: Not modified.
        '400':
          description: Malformed `Range` header.
        '402':
          description: Payment required (x402), when rate limited and payments are enabled.
        '404':
          description: No published file has this digest.
        '416':
          description: The range cannot be satisfied.
        '429':
          description: Rate limited.
        '503':
          description: The digest is published but not yet servable (the publisher is replacing a band or has not linked the file). Retry after `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema: { type: string }
  '/ar-io/indexes/webseed/{torrentName}/{file}':
    get:
      tags: [Indexes]
      summary: Get a published index file as a BitTorrent WebSeed
      description: |
        BEP 19 WebSeed for bands offered as torrents: clients fetch
        `<url><torrent name>/<file>`, where the torrent name is derived from
        the band's file names, sizes and digests (see
        docs/index-publication.md). Metered, range-capable and cached like
        the blob route: `public` or, when the gateway meters the byte
        routes, `private, max-age=31536000, immutable`; errors carry
        `Cache-Control: no-store`.
      parameters:
        - { name: torrentName, in: path, required: true, schema: { type: string, pattern: '^[0-9a-f]{16}$' } }
        - { name: file, in: path, required: true, schema: { type: string } }
        - { name: Range, in: header, required: false, schema: { type: string } }
      responses:
        '200':
          description: The file.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '206':
          description: A byte range of the file.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '304':
          description: Not modified.
        '400':
          description: Malformed file name.
        '402':
          description: Payment required (x402), when rate limited and payments are enabled.
        '404':
          description: No torrent this gateway offers has this name and file.
        '416':
          description: The range cannot be satisfied.
        '429':
          description: Rate limited.
        '503':
          description: The file is published but not yet servable. Retry after `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema: { type: string }
  '/ar-io/indexes/torrents/{infohash}.torrent':
    get:
      tags: [Indexes]
      summary: Get a published band's torrent, by its v1 infohash
      description: |
        The `.torrent` for a band the publication offers as a torrent, at the
        `torrentUrl` the band's signed entry names, addressed by the v1
        infohash. Not metered. When the gateway knows its public origin
        (INDEXES_PUBLIC_URL, default `https://<ARNS_ROOT_HOST>`) and
        `INDEXES_TORRENT_WEBSEED` is on (the default), the torrent names its
        WebSeed, `<origin>/ar-io/indexes/webseed/` (BEP 19 `url-list`), so a
        stock client can finish a band no peer delivers.
        That and the trackers are outside the info dictionary, so the
        infohashes are the publisher's. A client must check the info
        dictionary against the infohashes in the signed publication before
        using it: nothing outside it is covered by that signature. When
        HTTPSIG_ENABLED is set, the response is signed, covering
        `x-ar-io-index-torrent` and Content-Digest. `Cache-Control: public,
        max-age=86400`; errors carry `no-store`. HEAD is supported.
      parameters:
        - name: infohash
          in: path
          required: true
          schema: { type: string, pattern: '^[0-9a-f]{40}$' }
      responses:
        '200':
          description: The torrent metainfo.
          headers:
            Cache-Control:
              schema: { type: string, example: 'public, max-age=86400' }
            ETag:
              schema: { type: string }
              description: The SHA-256 (hex) of the body, quoted.
            Content-Digest:
              schema: { type: string }
              description: RFC 9530 SHA-256 of the body.
            x-ar-io-index-torrent:
              schema: { type: string }
              description: The v1 infohash, the one the publication signs.
          content:
            application/x-bittorrent:
              schema: { type: string, format: binary }
        '304':
          description: Not modified.
        '400':
          description: Not a 40-character lowercase hex infohash.
        '404':
          description: No band the publication offers has this infohash, or its torrent is not built yet.
  '/ar-io/indexes/feed/{index}.xml':
    get:
      tags: [Indexes]
      summary: Get an RSS feed of an index's torrents
      description: |
        RSS 2.0, one item per band of the index that the publication offers
        as a torrent, newest heights first. Each item's `enclosure` is the
        band's `.torrent` and its `link` the magnet, so a BitTorrent client
        subscribed with an auto-download rule takes every band, and each new
        one as it is published. `guid` is `urn:btih:<v1 infohash>`.
        Elements in the `urn:ar-io:index-feed:1` namespace carry the
        publisher, sequence, the publication's SHA-256, and each band's id,
        v2 infohash, heights, torrent name (the folder a client saves it in)
        and the bands it supersedes. Each enclosure's `length` is that of
        the `.torrent` as served, WebSeed included.

        A view of the signed publication and nothing else. Absolute URLs
        start with INDEXES_PUBLIC_URL (default `https://<ARNS_ROOT_HOST>`),
        never with the request's Host header. Not metered. When
        HTTPSIG_ENABLED is set, the response is signed, covering
        `x-ar-io-index-feed` and Content-Digest. HEAD is supported. See
        docs/index-publication.md, "Following an index in a BitTorrent
        client".
      parameters:
        - name: index
          in: path
          required: true
          schema: { type: string, pattern: '^[a-z0-9-]{1,64}$' }
      responses:
        '200':
          description: The feed.
          headers:
            Cache-Control:
              schema: { type: string, example: 'public, max-age=60' }
            ETag:
              schema: { type: string }
            Content-Digest:
              schema: { type: string }
              description: RFC 9530 SHA-256 of the body.
            x-ar-io-index-feed:
              schema: { type: string }
              description: SHA-256 (hex) of the publication document the feed was built from.
          content:
            application/rss+xml:
              schema: { type: string }
        '304':
          description: Not modified.
        '400':
          description: Not `<index name>.xml`.
        '404':
          description: No such index is published, or the gateway has no public URL configured.
        '500':
          description: 'The feed could not be built. `Cache-Control: no-store`.'
  '/ar-io/indexes/announce':
    get:
      tags: [Indexes]
      summary: Announce to the publisher's closed BitTorrent tracker
      description: |
        A BitTorrent tracker announce (BEP 3, compact BEP 23), forwarded by
        the gateway's Envoy to the index-swarm sidecar's tracker; core never
        sees it. Answers only for the bands the publication offers as
        torrents, under either infohash, and fails any other with
        `unregistered torrent`. The peer's address is read from
        X-Forwarded-For, so proxies in front of the gateway must append it.
        Bodies are bencoded; every response is `Cache-Control: no-store`.
        Peers are always listed compactly (`peers`, and `peers6` for IPv6),
        whatever `compact` asks. Routed only on the gateway's own host, not
        on ArNS subdomains, and only by the Envoy image from release 85 on
        (an older Envoy passes the path to core, which answers 404). See
        docs/index-swarm.md, "The tracker".
      parameters:
        - { name: info_hash, in: query, required: true, schema: { type: string }, description: 'The 20-byte v1 infohash (or a v2 infohash truncated to 20 bytes), percent-encoded.' }
        - { name: port, in: query, required: true, schema: { type: integer, minimum: 1, maximum: 65535 } }
        - { name: left, in: query, required: false, schema: { type: integer }, description: 'Bytes still to download; 0 counts the peer as a seeder. Taken as 1 when absent.' }
        - { name: event, in: query, required: false, schema: { type: string, enum: [started, stopped, completed] }, description: '`stopped` forgets the peer.' }
        - { name: peer_id, in: query, required: false, schema: { type: string }, description: 'Accepted and ignored: a peer is known by its address and port.' }
        - { name: compact, in: query, required: false, schema: { type: integer }, description: 'Accepted and ignored: answers are always compact.' }
      responses:
        '200':
          description: 'A bencoded tracker response: peers, or `failure reason`.'
          content:
            text/plain:
              schema: { type: string, format: binary }
        '403':
          description: 'The request bears a browser''s marks (`Sec-Fetch-Site`, `Sec-Fetch-Dest`, `Origin`, `Referer`, or an `Accept` asking for an image or a page): a web page may not list its visitors as peers.'
        '503':
          description: The gateway runs no tracker (no index-swarm sidecar publishing torrents).
  '/ar-io/peers':
    get:
      tags: [Gateway]
      summary: Get AR.IO Gateway peer information
      description: |
        Returns information about AR.IO Gateway peers and Arweave node peers.
        For gateways, includes both data and chunk weights used for peer selection,
        and what the gateway registry says about each peer (wallet, observer
        address, operator stake, status), from the registry read the gateway
        refreshes hourly. Peer keys are formatted as host:port.
      responses:
        '200':
          description: Peer information response
          content:
            application/json:
              schema:
                type: object
                properties:
                  gateways:
                    type: object
                    description: AR.IO Gateway peers with their weights
                    additionalProperties:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: Full URL of the gateway peer
                          example: "https://gateway.example.com"
                        dataWeight:
                          type: number
                          minimum: 1
                          maximum: 100
                          description: Weight for data retrieval operations
                          example: 50
                        chunkWeight:
                          type: number
                          minimum: 1
                          maximum: 100
                          description: Weight for chunk retrieval operations
                          example: 50
                        wallet:
                          type: string
                          description: The gateway's registered wallet, from the gateway registry
                        observerAddress:
                          type: string
                          description: The key the gateway observes and signs with, from the registry
                        operatorStake:
                          type: number
                          description: The operator's own stake, as the registry reports it
                        status:
                          type: string
                          description: Registry status; `leaving` gateways appear only when SKIP_LEAVING_GATEWAYS is false
                      required:
                        - url
                        - dataWeight
                        - chunkWeight
                  self:
                    type: object
                    description: |
                      This gateway's own registry entry, present when its
                      `AR_IO_WALLET` is registered. A gateway is never its own
                      peer, so it is kept out of `gateways`; the index-swarm
                      sidecar of a fleet node resolves its own fleet's
                      publication through it.
                    properties:
                      url:
                        type: string
                        format: uri
                      wallet:
                        type: string
                      observerAddress:
                        type: string
                      operatorStake:
                        type: number
                      status:
                        type: string
                    required:
                      - url
                      - wallet
                  arweaveNodes:
                    type: object
                    description: Arweave node peers with their metadata
                    additionalProperties:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: URL of the Arweave node peer
                          example: "http://arweave.example.com:1984"
                        blocks:
                          type: number
                          description: Number of blocks stored by this peer
                          example: 165967
                        height:
                          type: number
                          description: Current block height of this peer
                          example: 1732652
                        lastSeen:
                          type: number
                          description: Unix timestamp when peer was last seen
                          example: 1755190447700
                required:
                  - gateways
                  - arweaveNodes
                example:
                  gateways:
                    "gateway.example.com:443":
                      url: "https://gateway.example.com"
                      dataWeight: 50
                      chunkWeight: 50
                  arweaveNodes:
                    "arweave.example.com:1984":
                      url: "http://arweave.example.com:1984"
                      blocks: 165967
                      height: 1732652
                      lastSeen: 1755190447700
  '/ar-io/__gateway_metrics':
    get:
      tags: [Gateway]
      summary: Get Prometheus metrics
      description: |
        Returns metrics in Prometheus format for monitoring the Gateway's performance and status.
        These metrics include various counters, gauges, and histograms tracking:
        - HTTP request statistics
        - Transaction processing metrics
        - System resource usage
        - Cache performance
        - Bundle processing statistics
      responses:
        '200':
          description: Prometheus metrics response
          content:
            text/plain:
              schema:
                type: string
                description: Metrics in Prometheus format
                example: |
                  # HELP errors_total Total error count
                  # TYPE errors_total counter
                  errors_total 0

                  # HELP uncaught_exceptions_total Count of uncaught exceptions
                  # TYPE uncaught_exceptions_total counter
                  uncaught_exceptions_total 0

  # Data
  '/{txId}':
    get:
      tags: [Data]
      summary: Get transaction or data item content
      description: |
        Get the content of a specified transaction or data item. Supports manifest path resolution,
        range requests, and returns various informational headers about data verification and caching status.

        For ANS-104 data items, offset headers are returned to help navigate bundle hierarchies:
        - Root offset headers (X-AR-IO-Root-Data-Item-Offset, X-AR-IO-Root-Data-Offset) provide byte offsets from the start of the root L1 transaction
        - Parent offset headers provide byte offsets from the start of the immediate parent bundle's payload
        - Offset relationships: rootDataItemOffset = rootParentOffset + offset, rootDataOffset = rootParentOffset + dataOffset
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
        - name: Range
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/ByteRange'
          description: Byte range(s) to retrieve
        - $ref: '#/components/parameters/RootTransactionIdHint'
        - $ref: '#/components/parameters/RootPathHint'
        - $ref: '#/components/parameters/RootItemOffsetHint'
        - $ref: '#/components/parameters/RootItemSizeHint'
      responses:
        '200':
          description: Successful response
          headers:
            Accept-Ranges:
              schema:
                type: string
                example: bytes
            Cache-Control:
              schema:
                type: string
                example: public, max-age=2592000, immutable
            Content-Length:
              schema:
                type: string
                example: 1024
            Content-Type:
              schema:
                type: string
                example: application/octet-stream
            X-Cache:
              schema:
                $ref: '#/components/schemas/CacheStatus'
                example: HIT
            X-AR-IO-Verified:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
                example: true
            X-AR-IO-Digest:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            Content-Digest:
              schema:
                type: string
                description: RFC 9530 compliant digest header with SHA-256
                example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
            ETag:
              description: |-
                The content digest (base64url SHA-256), quoted. On a response
                served through an ArNS name it is `<digest>.<X-ArNS-Resolved-Id>`,
                so it changes when the name is re-pointed even if the bytes do
                not, and a 304 means the same bytes and the same resolution.
                Treat it as opaque; read the digest from X-AR-IO-Digest.
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            X-AR-IO-Root-Transaction-Id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
                description: For data items, the root transaction ID
                example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
            X-AR-IO-Hops:
              schema:
                type: integer
                example: 1
            X-AR-IO-Stable:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data is before max fork depth (stable on chain)
              example: 'true'
            X-AR-IO-Trusted:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data source is trusted
              example: 'true'
            X-AR-IO-Data-Id:
              schema:
                type: string
              description: The data ID being served (may differ from txId for manifests)
              example: 'YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE'
            Content-Encoding:
              schema:
                type: string
              description: Content encoding when present (e.g., gzip, br)
              example: 'gzip'
            X-AR-IO-Root-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2048
            X-AR-IO-Root-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2176
            X-AR-IO-Data-Item-Root-Parent-Offset:
              schema:
                type: integer
              description: Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)
              example: 1536
            X-AR-IO-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 512
            X-AR-IO-Data-Item-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 640
            X-AR-IO-Data-Item-Size:
              schema:
                type: integer
              description: Total size of data item including headers and payload in bytes (ANS-104 bundles only)
              example: 2092
            X-Arweave-Tag-Count:
              schema:
                type: integer
              description: Total number of tags (opt-in via ARWEAVE_TAG_RESPONSE_HEADERS_ENABLED)
              example: 5
            X-Arweave-Tags-Truncated:
              schema:
                type: string
                enum: ['true']
              description: Present when tags exceed count or byte budget limit
            X-Arweave-Signature:
              schema:
                type: string
              description: Data item signature (base64url)
            X-Arweave-Owner:
              schema:
                type: string
              description: Full public key of the signer (base64url)
            X-Arweave-Owner-Address:
              schema:
                $ref: '#/components/schemas/Base64Url43'
              description: SHA-256 of owner public key (base64url)
            X-Arweave-Target:
              schema:
                type: string
              description: Transfer target (base64url, empty if none)
            X-Arweave-Anchor:
              schema:
                type: string
              description: Transaction anchor / nonce (base64url)
            X-Arweave-Signature-Type:
              schema:
                type: integer
              description: Signature algorithm (1 = RSA-4096/Arweave)
              example: 1
            Signature:
              schema:
                type: string
              description: RFC 9421 HTTP Message Signature (opt-in via HTTPSIG_ENABLED)
              example: 'sig1=:oU151iAt3RBEvThMpQvCiJzjkFhXDVpDFSUg43vxZsIoTFSqkSDyLbshT2tBWAcWIq1mc3AAXLhEdUqN+ifbBw==:'
            Signature-Input:
              schema:
                type: string
              description: RFC 9421 Signature-Input listing signed components, algorithm, and key ID (opt-in via HTTPSIG_ENABLED)
              example: 'sig1=("@status" "content-type" "x-ar-io-data-id" "x-ar-io-verified");created=1712505600;keyid="ed25519:...";alg="ed25519"'
        '206':
          description: Partial content for range requests
          headers:
            Accept-Ranges:
              schema:
                type: string
                example: bytes
            Cache-Control:
              schema:
                type: string
                example: public, max-age=2592000, immutable
            Content-Range:
              schema:
                type: string
                example: bytes 0-1023/146515
            Repr-Digest:
              schema:
                type: string
              description: |-
                RFC 9530 SHA-256 of the whole item, sent when the gateway can
                stand behind it (cached data or HEAD). A range response
                carries this instead of `Content-Digest`, which would cover
                only the bytes sent. Covered by the HTTPSIG signature.
              example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
            Content-Type:
              schema:
                type: string
                example: application/octet-stream
            X-Cache:
              schema:
                $ref: '#/components/schemas/CacheStatus'
                example: HIT
            X-AR-IO-Verified:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
                example: true
            X-AR-IO-Digest:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            ETag:
              description: |-
                The content digest (base64url SHA-256), quoted. On a response
                served through an ArNS name it is `<digest>.<X-ArNS-Resolved-Id>`,
                so it changes when the name is re-pointed even if the bytes do
                not, and a 304 means the same bytes and the same resolution.
                Treat it as opaque; read the digest from X-AR-IO-Digest.
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            X-AR-IO-Root-Transaction-Id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
                description: For data items, the root transaction ID
                example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
            X-AR-IO-Hops:
              schema:
                type: integer
                example: 1
            X-AR-IO-Stable:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data is before max fork depth (stable on chain)
              example: 'true'
            X-AR-IO-Trusted:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data source is trusted
              example: 'true'
            X-AR-IO-Data-Id:
              schema:
                type: string
              description: The data ID being served (may differ from txId for manifests)
              example: 'YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE'
            Content-Encoding:
              schema:
                type: string
              description: Content encoding when present (e.g., gzip, br)
              example: 'gzip'
            X-AR-IO-Root-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2048
            X-AR-IO-Root-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2176
            X-AR-IO-Data-Item-Root-Parent-Offset:
              schema:
                type: integer
              description: Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)
              example: 1536
            X-AR-IO-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 512
            X-AR-IO-Data-Item-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 640
            X-AR-IO-Data-Item-Size:
              schema:
                type: integer
              description: Total size of data item including headers and payload in bytes (ANS-104 bundles only)
              example: 2092
        '301':
          description: Redirect for manifest paths without trailing slash
        '404':
          description: Data not found or blocked
        '416':
          description: Range not satisfiable
    head:
      tags: [Data]
      summary: Get transaction or data item headers
      description: |
        Get the headers for a specified transaction or data item without the content.
        Returns the same headers as the GET request.
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
        - name: Range
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/ByteRange'
          description: Byte range(s) to check
        - $ref: '#/components/parameters/RootTransactionIdHint'
        - $ref: '#/components/parameters/RootPathHint'
        - $ref: '#/components/parameters/RootItemOffsetHint'
        - $ref: '#/components/parameters/RootItemSizeHint'
      responses:
        '200':
          description: Successful response
          headers:
            Accept-Ranges:
              schema:
                type: string
                example: bytes
            Cache-Control:
              schema:
                type: string
                example: public, max-age=2592000, immutable
            Content-Length:
              schema:
                type: string
                example: 1024
            Content-Type:
              schema:
                type: string
                example: application/octet-stream
            X-Cache:
              schema:
                $ref: '#/components/schemas/CacheStatus'
                example: HIT
            X-AR-IO-Verified:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
                example: true
            X-AR-IO-Digest:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            Content-Digest:
              schema:
                type: string
                description: RFC 9530 compliant digest header with SHA-256
                example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
            ETag:
              description: |-
                The content digest (base64url SHA-256), quoted. On a response
                served through an ArNS name it is `<digest>.<X-ArNS-Resolved-Id>`,
                so it changes when the name is re-pointed even if the bytes do
                not, and a 304 means the same bytes and the same resolution.
                Treat it as opaque; read the digest from X-AR-IO-Digest.
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            X-AR-IO-Root-Transaction-Id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
                description: For data items, the root transaction ID
                example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
            X-AR-IO-Hops:
              schema:
                type: integer
                example: 1
  '/raw/{txId}':
    get:
      tags: [Data]
      summary: Get raw transaction data
      description: |
        Get the raw content of a specified transaction without manifest resolution.

        For ANS-104 data items, offset headers are returned to help navigate bundle hierarchies:
        - Root offset headers (X-AR-IO-Root-Data-Item-Offset, X-AR-IO-Root-Data-Offset) provide byte offsets from the start of the root L1 transaction
        - Parent offset headers provide byte offsets from the start of the immediate parent bundle's payload
        - Offset relationships: rootDataItemOffset = rootParentOffset + offset, rootDataOffset = rootParentOffset + dataOffset
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
        - name: Range
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/ByteRange'
          description: Byte range(s) to retrieve
        - $ref: '#/components/parameters/RootTransactionIdHint'
        - $ref: '#/components/parameters/RootPathHint'
        - $ref: '#/components/parameters/RootItemOffsetHint'
        - $ref: '#/components/parameters/RootItemSizeHint'
      responses:
        '200':
          description: Successful response
          headers:
            Accept-Ranges:
              schema:
                type: string
                example: bytes
            Cache-Control:
              schema:
                type: string
                example: public, max-age=2592000, immutable
            Content-Length:
              schema:
                type: string
                example: 1024
            Content-Type:
              schema:
                type: string
                example: application/octet-stream
            X-Cache:
              schema:
                $ref: '#/components/schemas/CacheStatus'
                example: HIT
            X-AR-IO-Verified:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
                example: true
            X-AR-IO-Digest:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            Content-Digest:
              schema:
                type: string
                description: RFC 9530 compliant digest header with SHA-256
                example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
            ETag:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            X-AR-IO-Root-Transaction-Id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
                description: For data items, the root transaction ID
                example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
            X-AR-IO-Hops:
              schema:
                type: integer
                example: 1
            X-AR-IO-Stable:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data is before max fork depth (stable on chain)
              example: 'true'
            X-AR-IO-Trusted:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data source is trusted
              example: 'true'
            X-AR-IO-Data-Id:
              schema:
                type: string
              description: The data ID being served (may differ from txId for manifests)
              example: 'YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE'
            Content-Encoding:
              schema:
                type: string
              description: Content encoding when present (e.g., gzip, br)
              example: 'gzip'
            X-AR-IO-Root-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2048
            X-AR-IO-Root-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2176
            X-AR-IO-Data-Item-Root-Parent-Offset:
              schema:
                type: integer
              description: Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)
              example: 1536
            X-AR-IO-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 512
            X-AR-IO-Data-Item-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 640
            X-AR-IO-Data-Item-Size:
              schema:
                type: integer
              description: Total size of data item including headers and payload in bytes (ANS-104 bundles only)
              example: 2092
            X-Arweave-Tag-Count:
              schema:
                type: integer
              description: Total number of tags (opt-in via ARWEAVE_TAG_RESPONSE_HEADERS_ENABLED)
              example: 5
            X-Arweave-Tags-Truncated:
              schema:
                type: string
                enum: ['true']
              description: Present when tags exceed count or byte budget limit
            X-Arweave-Signature:
              schema:
                type: string
              description: Data item signature (base64url)
            X-Arweave-Owner:
              schema:
                type: string
              description: Full public key of the signer (base64url)
            X-Arweave-Owner-Address:
              schema:
                $ref: '#/components/schemas/Base64Url43'
              description: SHA-256 of owner public key (base64url)
            X-Arweave-Target:
              schema:
                type: string
              description: Transfer target (base64url, empty if none)
            X-Arweave-Anchor:
              schema:
                type: string
              description: Transaction anchor / nonce (base64url)
            X-Arweave-Signature-Type:
              schema:
                type: integer
              description: Signature algorithm (1 = RSA-4096/Arweave)
              example: 1
            Signature:
              schema:
                type: string
              description: RFC 9421 HTTP Message Signature (opt-in via HTTPSIG_ENABLED)
              example: 'sig1=:oU151iAt3RBEvThMpQvCiJzjkFhXDVpDFSUg43vxZsIoTFSqkSDyLbshT2tBWAcWIq1mc3AAXLhEdUqN+ifbBw==:'
            Signature-Input:
              schema:
                type: string
              description: RFC 9421 Signature-Input listing signed components, algorithm, and key ID (opt-in via HTTPSIG_ENABLED)
              example: 'sig1=("@status" "content-type" "x-ar-io-data-id" "x-ar-io-verified");created=1712505600;keyid="ed25519:...";alg="ed25519"'
        '206':
          description: Partial content for range requests
          headers:
            Accept-Ranges:
              schema:
                type: string
                example: bytes
            Cache-Control:
              schema:
                type: string
                example: public, max-age=2592000, immutable
            Content-Range:
              schema:
                type: string
                example: bytes 0-1023/146515
            Repr-Digest:
              schema:
                type: string
              description: |-
                RFC 9530 SHA-256 of the whole item, sent when the gateway can
                stand behind it (cached data or HEAD). A range response
                carries this instead of `Content-Digest`, which would cover
                only the bytes sent. Covered by the HTTPSIG signature.
              example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
            Content-Type:
              schema:
                type: string
                example: application/octet-stream
            X-Cache:
              schema:
                $ref: '#/components/schemas/CacheStatus'
                example: HIT
            X-AR-IO-Verified:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
                example: true
            X-AR-IO-Digest:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            ETag:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            X-AR-IO-Root-Transaction-Id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
                description: For data items, the root transaction ID
                example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
            X-AR-IO-Hops:
              schema:
                type: integer
                example: 1
            X-AR-IO-Stable:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data is before max fork depth (stable on chain)
              example: 'true'
            X-AR-IO-Trusted:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data source is trusted
              example: 'true'
            X-AR-IO-Data-Id:
              schema:
                type: string
              description: The data ID being served (may differ from txId for manifests)
              example: 'YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE'
            Content-Encoding:
              schema:
                type: string
              description: Content encoding when present (e.g., gzip, br)
              example: 'gzip'
            X-AR-IO-Root-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2048
            X-AR-IO-Root-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2176
            X-AR-IO-Data-Item-Root-Parent-Offset:
              schema:
                type: integer
              description: Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)
              example: 1536
            X-AR-IO-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 512
            X-AR-IO-Data-Item-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 640
            X-AR-IO-Data-Item-Size:
              schema:
                type: integer
              description: Total size of data item including headers and payload in bytes (ANS-104 bundles only)
              example: 2092
            Signature:
              schema:
                type: string
              description: RFC 9421 HTTP Message Signature (opt-in via HTTPSIG_ENABLED)
            Signature-Input:
              schema:
                type: string
              description: RFC 9421 Signature-Input listing signed components, algorithm, and key ID (opt-in via HTTPSIG_ENABLED)
        '404':
          description: Data not found or blocked
        '416':
          description: Range not satisfiable
    head:
      tags: [Data]
      summary: Get raw transaction data headers
      description: Get the headers for raw transaction data without manifest resolution
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
        - name: Range
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/ByteRange'
          description: Byte range(s) to check
        - $ref: '#/components/parameters/RootTransactionIdHint'
        - $ref: '#/components/parameters/RootPathHint'
        - $ref: '#/components/parameters/RootItemOffsetHint'
        - $ref: '#/components/parameters/RootItemSizeHint'
      responses:
        '200':
          description: Successful response
          headers:
            Accept-Ranges:
              schema:
                type: string
                example: bytes
            Cache-Control:
              schema:
                type: string
                example: public, max-age=2592000, immutable
            Content-Length:
              schema:
                type: string
                example: 1024
            Content-Type:
              schema:
                type: string
                example: application/octet-stream
            X-Cache:
              schema:
                $ref: '#/components/schemas/CacheStatus'
                example: HIT
            X-AR-IO-Verified:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
                example: true
            X-AR-IO-Digest:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            Content-Digest:
              schema:
                type: string
                description: RFC 9530 compliant digest header with SHA-256
                example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
            ETag:
              schema:
                type: string
                example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            X-AR-IO-Root-Transaction-Id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
                description: For data items, the root transaction ID
                example: '283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc'
            X-AR-IO-Hops:
              schema:
                type: integer
                example: 1
            X-AR-IO-Stable:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data is before max fork depth (stable on chain)
              example: 'true'
            X-AR-IO-Trusted:
              schema:
                type: string
                enum: ['true', 'false']
              description: Whether data source is trusted
              example: 'true'
            X-AR-IO-Data-Id:
              schema:
                type: string
              description: The data ID being served (may differ from txId for manifests)
              example: 'YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE'
            Content-Encoding:
              schema:
                type: string
              description: Content encoding when present (e.g., gzip, br)
              example: 'gzip'
            X-AR-IO-Root-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2048
            X-AR-IO-Root-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)
              example: 2176
            X-AR-IO-Data-Item-Root-Parent-Offset:
              schema:
                type: integer
              description: Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)
              example: 1536
            X-AR-IO-Data-Item-Offset:
              schema:
                type: integer
              description: Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 512
            X-AR-IO-Data-Item-Data-Offset:
              schema:
                type: integer
              description: Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)
              example: 640
            X-AR-IO-Data-Item-Size:
              schema:
                type: integer
              description: Total size of data item including headers and payload in bytes (ANS-104 bundles only)
              example: 2092
            Signature:
              schema:
                type: string
              description: RFC 9421 HTTP Message Signature (opt-in via HTTPSIG_ENABLED)
            Signature-Input:
              schema:
                type: string
              description: RFC 9421 Signature-Input listing signed components, algorithm, and key ID (opt-in via HTTPSIG_ENABLED)
        '404':
          description: Data not found or blocked
        '416':
          description: Range not satisfiable for HEAD request

  # Network and Node Status
  '/info':
    get:
      tags: [Network]
      summary: Network and Gateway Status, alternate endpoint.
      description: An alternative option for accessing network and Gateway status.
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/NetworkInfo'
  '/peers':
    get:
      tags: [Network]
      summary: Get active peer list.
      description: Gets a list of ip addresses for peers your Gateway is currently connected with.
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/PeerList'
  '/height':
    get:
      tags: [Network]
      summary: Get current block height.
      description: Gets the current block height of the Arweave network.
      responses:
        '200':
          description: |-
            200 response
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Height'
  '/tx_anchor':
    get:
      tags: [Network]
      summary: Get the current transaction anchor.
      description: Get the current transaction anchor of the Arweave network.
      responses:
        '200':
          description: |-
            200 response
          content:
            text/plain:
              schema:
                '$ref': '#/components/schemas/Base64Url43'

  # Pricing
  '/price/{size}':
    get:
      tags: [Pricing]
      summary: Get price to store an amount of data.
      description: Get the price, in Winston, required to store a specified amount of data, in bytes, on the Arweave network.
      parameters:
        - name: size
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/NumericString'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            text/plain:
              schema:
                type: integer
  '/price/{size}/target':
    get:
      tags: [Pricing]
      summary: Get price to transfer AR into a wallet and store an amount of data
      description: |
        Get the price, in Winston, required to transfer AR into a wallet and store a specified amount of data, in bytes, on the Arweave network.
      parameters:
        - name: size
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/NumericString'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            text/html:
              schema:
                type: integer

  # Wallets
  '/wallet/{address}/balance':
    get:
      tags: [Wallets]
      summary: Get the current balance of a wallet.
      description: Get the current balance of AR, in Winston, of a specified wallet address.
      parameters:
        - name: address
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            text/plain:
              schema:
                type: integer
  '/wallet/{address}/last_tx':
    get:
      tags: [Wallets]
      summary: Get the last transaction of a wallet.
      description: Get the TX ID from the most recent transaction a specified wallet completed.
      parameters:
        - name: address
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Base64Url43'

  # Blocks
  '/current_block':
    get:
      tags: [Blocks]
      summary: Get information about the current block.
      description: Get detailed information about the current block on the Arweave network.
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Block'
  '/block/height/{height}':
    get:
      tags: [Blocks]
      summary: Get current block height.
      description: Gets the current block height of the Arweave network.
      parameters:
        - name: height
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/NumericString'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Block'
  '/block/hash/{hash}':
    get:
      tags: [Blocks]
      summary: Get block by hash.
      description: Get block information based on a block's hash.
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url64'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Block'
  '/block/current':
    get:
      tags: [Blocks]
      summary: Alternative endpoint to get current block.
      description: Alternative endpoint to `/current_block`, gets current block information.
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Block'
  # "/block/hash/{block hash}/wallet_list"

  # Transactions
  '/tx':
    post:
      tags: [Transactions]
      summary: Post a transaction
      description: |
        Submits a signed L1 transaction (JSON), as an Arweave node's
        `POST /tx` does. Envoy sends it on to Arweave nodes: the peers it
        discovers by default, or `TRUSTED_NODE_HOST` and `FALLBACK_NODE_HOST`
        with `ENABLE_ARWEAVE_PEER_EDS=false`. With `ARWEAVE_POST_DRY_RUN=true`
        the gateway answers it itself: with
        `ARWEAVE_POST_DRY_RUN_SKIP_VALIDATION=true` it accepts anything,
        otherwise it checks the required fields and the signature, and it
        broadcasts nothing. Reaching the gateway directly (port 4000), it
        forwards to `TRUSTED_NODE_URL` itself. The gateway's own handler
        accepts bodies up to 10 MB.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: A signed Arweave transaction in its JSON form.
              required: [id, owner, signature, last_tx]
      responses:
        '200':
          description: Accepted (or, in dry-run mode, valid).
        '400':
          description: Missing required fields or an invalid signature (dry-run mode).
        default:
          description: Whatever the Arweave node answers, passed through.
  '/tx/pending':
    get:
      tags: [Transactions]
      summary: Get pending transactions.
      description: Get list of transactions that are currently pending.
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Mempool'
  '/tx/{txId}':
    get:
      tags: [Transactions]
      summary: Get information about a transaction.
      description: Get detailed information about a specific transaction.
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Transaction'
  '/tx/{txId}/offset':
    get:
      tags: [Transactions]
      summary: Get transaction offset information.
      description: Get information about the size and offset of a specified transaction.
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/TransactionOffset'
  '/tx/{txId}/status':
    get:
      tags: [Transactions]
      summary: Get transaction status.
      description: Get the status of a specified transaction.
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/TransactionStatus'
  # "/tx/{txId}/field"
  # "/unconfirmed_tx/{txId}"

  # Chunks
  '/chunk':
    post:
      tags: [Chunks]
      summary: Post a chunk
      description: |
        Broadcasts a chunk of an uploaded transaction's data, with its Merkle
        proof, to Arweave nodes, as an Arweave node's `POST /chunk` does. It
        succeeds when at least `CHUNK_POST_MIN_SUCCESS_COUNT` nodes accept
        it, `CHUNK_POST_MIN_PREFERRED_SUCCESS_COUNT` of them preferred nodes
        (`PREFERRED_CHUNK_POST_NODE_URLS`). Otherwise the status is the one
        most of the failing nodes gave: 504 for a timeout, 502 for a network
        error, 499 when cancelled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The chunk and its proof, as an Arweave node takes them.
              properties:
                data_root: { type: string, description: base64url }
                data_size: { type: string }
                data_path: { type: string, description: base64url Merkle proof }
                offset: { type: string }
                chunk: { type: string, description: base64url chunk bytes }
      responses:
        '200':
          description: Enough nodes accepted the chunk.
          content:
            application/json:
              schema:
                type: object
                properties:
                  successCount: { type: integer }
                  preferredSuccessCount: { type: integer }
                  failureCount: { type: integer }
                  results:
                    type: array
                    description: One entry per node tried.
                    items: { type: object }
        '500':
          description: The broadcast could not be made.
        default:
          description: Too few nodes accepted the chunk; the body is the same result object.
  '/chunk/{offset}':
    get:
      tags: [Chunks]
      summary: Get chunk offset information.
      description: Fetches information about the size and offset of a specified chunk.
      parameters:
        - name: offset
          in: path
          required: true
          schema:
            type: integer
        - name: If-None-Match
          in: header
          required: false
          description: ETag value for conditional request. Returns 304 if chunk hash matches.
          schema:
            type: string
      responses:
        '200':
          description: |-
            200 response
          headers:
            ETag:
              description: Entity tag based on chunk hash (when available)
              schema:
                type: string
            Content-Digest:
              description: RFC 9530 compliant digest header with SHA-256 (when available)
              schema:
                type: string
                example: 'sha-256=:YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE=:'
            Content-Length:
              description: Size of the response body in bytes
              schema:
                type: integer
            X-Cache:
              description: |-
                Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).
                Always present.
              schema:
                type: string
                enum: [HIT, MISS]
              example: HIT
            X-AR-IO-Chunk-Source-Type:
              description: Source type of the chunk data
              schema:
                type: string
            X-AR-IO-Chunk-Host:
              description: Host that provided the chunk
              schema:
                type: string
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Chunk'
        '304':
          description: Not Modified - chunk hash matches If-None-Match header
        '400':
          description: Invalid offset parameter
        '404':
          description: Chunk not found
    head:
      tags: [Chunks]
      summary: Get chunk metadata without body.
      description: Returns the same headers as GET but without the response body. Useful for checking chunk existence and metadata.
      parameters:
        - name: offset
          in: path
          required: true
          schema:
            type: integer
        - name: If-None-Match
          in: header
          required: false
          description: ETag value for conditional request. Returns 304 if chunk hash matches.
          schema:
            type: string
      responses:
        '200':
          description: |-
            200 response with headers only
          headers:
            Content-Type:
              description: Media type of the response
              schema:
                type: string
            ETag:
              description: Entity tag based on chunk hash (when available)
              schema:
                type: string
            Content-Digest:
              description: RFC 9530 compliant digest header with SHA-256 (when available)
              schema:
                type: string
                example: 'sha-256=:YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE=:'
            Content-Length:
              description: Size of the response body in bytes
              schema:
                type: integer
            X-Cache:
              description: |-
                Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).
                Always present.
              schema:
                type: string
                enum: [HIT, MISS]
              example: HIT
            X-AR-IO-Chunk-Source-Type:
              description: Source type of the chunk data
              schema:
                type: string
            X-AR-IO-Chunk-Host:
              description: Host that provided the chunk
              schema:
                type: string
        '304':
          description: Not Modified - chunk hash matches If-None-Match header
        '400':
          description: Invalid offset parameter
        '404':
          description: Chunk not found

  '/chunk/{offset}/data':
    get:
      tags: [Chunks]
      summary: Get chunk as raw binary data with metadata in headers.
      description: |-
        Fetches chunk data as raw binary (application/octet-stream) with metadata in response headers.
        This endpoint provides ~40% bandwidth savings compared to the base64url-encoded JSON endpoint.

        Chunk boundaries and merkle tree structure:
        - Chunks are determined by Arweave's merkle tree structure (maximum 256 KiB per chunk)
        - When you request data at an arbitrary offset, the full chunk containing that offset is returned
        - Use X-Arweave-Chunk-Read-Offset to determine where to start reading within the returned chunk
        - Merkle proof headers (X-Arweave-Chunk-Data-Path, X-Arweave-Chunk-Data-Root) provide cryptographic verification

        Offset relationships:
        - X-Arweave-Chunk-Start-Offset: Weave position where this chunk begins
        - X-Arweave-Chunk-Tx-Start-Offset: Weave position where the containing transaction begins
        - X-Arweave-Chunk-Relative-Start-Offset: Chunk position within its transaction (Chunk-Start-Offset - Tx-Start-Offset)
        - X-Arweave-Chunk-Read-Offset: Byte offset within the returned chunk where your requested data starts

        Example: Requesting a specific byte
        - Request: GET /chunk/50100/data (you want byte 50100 of the weave)
        - Response might have:
          - X-Arweave-Chunk-Start-Offset: 50000 (chunk starts at weave byte 50000)
          - X-Arweave-Chunk-Tx-Start-Offset: 49500 (transaction starts at weave byte 49500)
          - X-Arweave-Chunk-Relative-Start-Offset: 500 (chunk is 500 bytes into the transaction)
          - X-Arweave-Chunk-Read-Offset: 100 (start reading at byte 100 of the chunk body)
          - Content-Length: 262144 (256 KiB chunk returned)
        - To get your data: read from byte 100 to end of the response body
      parameters:
        - name: offset
          in: path
          required: true
          description: Weave offset (0-based byte position in the weave)
          schema:
            type: integer
        - name: If-None-Match
          in: header
          required: false
          description: ETag value for conditional request. Returns 304 if chunk hash matches.
          schema:
            type: string
      responses:
        '200':
          description: Raw binary chunk data with metadata in headers
          headers:
            Content-Type:
              description: |-
                Media type of the response.
                Always application/octet-stream for this endpoint.
                Always present.
              schema:
                type: string
                example: application/octet-stream
            Content-Length:
              description: |-
                Size of the chunk data in bytes (maximum 256 KiB).
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Data-Path:
              description: |-
                Base64url-encoded merkle proof path for this chunk.
                Provides cryptographic proof of the chunk's position in the merkle tree.
                Uses base64url encoding (URL-safe), not standard base64.
                Always present.
              schema:
                type: string
            X-Arweave-Chunk-Data-Root:
              description: |-
                Base64url-encoded merkle tree root hash.
                Root of the merkle tree used to verify chunk integrity.
                Uses base64url encoding (URL-safe), not standard base64.
                Always present.
              schema:
                type: string
            X-Arweave-Chunk-Start-Offset:
              description: |-
                Start offset of this chunk in the weave (inclusive, 0-based byte position).
                This is the weave-relative position where this chunk begins.
                To calculate chunk end offset: startOffset + Content-Length.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Relative-Start-Offset:
              description: |-
                Byte offset where this chunk starts within its containing transaction (inclusive, 0-based).
                Calculated as: X-Arweave-Chunk-Start-Offset - X-Arweave-Chunk-Tx-Start-Offset.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Read-Offset:
              description: |-
                Byte offset within the returned chunk body where your requested data starts (0-based).
                Since full chunks are always returned (determined by merkle tree boundaries),
                this tells you where to start reading within the response body to get the data at your requested offset.
                Example: if you request offset 50100 and the chunk starts at 50000, this will be 100.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Tx-Data-Size:
              description: |-
                Total size of the containing transaction's data in bytes.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Tx-Path:
              description: |-
                Base64url-encoded transaction-level merkle path.
                Always present but may be empty string if transaction path is not available.
                Uses base64url encoding (URL-safe), not standard base64.
              schema:
                type: string
            X-Arweave-Chunk-Tx-Id:
              description: |-
                The Arweave transaction ID (base64url) containing this chunk.
                Always present.
              schema:
                type: string
            X-Arweave-Chunk-Tx-Start-Offset:
              description: |-
                Start offset of the containing transaction in the weave (inclusive, 0-based byte position).
                This is the weave-relative position where the transaction begins.
                To calculate transaction end offset: txStartOffset + X-Arweave-Chunk-Tx-Data-Size.
                Always present.
              schema:
                type: integer
            X-Cache:
              description: |-
                Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).
                Always present.
              schema:
                type: string
                enum: [HIT, MISS]
              example: HIT
            X-AR-IO-Chunk-Source-Type:
              description: |-
                Source type of the chunk data (e.g., 'cache', 'origin', 'peer').
                Present when source information is available.
              schema:
                type: string
              example: cache
            X-AR-IO-Chunk-Host:
              description: |-
                Hostname or identifier of the source that provided this chunk.
                Present when source host information is available.
              schema:
                type: string
              example: gateway.example.com
            ETag:
              description: |-
                Strong ETag based on SHA-256 hash of chunk data (base64url-encoded).
                Present only for cached chunks or HEAD requests to ensure hash accuracy.
                Use with If-None-Match header for conditional requests.
              schema:
                type: string
              example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            Content-Digest:
              description: |-
                RFC 9530 compliant digest header with SHA-256 hash of chunk data.
                Present only for cached chunks or HEAD requests to ensure hash accuracy.
                Format: sha-256=:<base64-encoded-hash>: (uses standard base64, not base64url).
              schema:
                type: string
              example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '304':
          description: Not Modified - chunk hash matches If-None-Match header
        '400':
          description: Invalid offset parameter
        '404':
          description: Chunk not found
        '500':
          description: Internal server error (e.g., merkle path parsing failed)
    head:
      tags: [Chunks]
      summary: Get chunk metadata without body.
      description: |-
        Returns the same headers as GET but without the response body.
        Useful for checking chunk existence, getting metadata (boundaries, offsets, merkle proofs),
        and obtaining hashes (ETag, Content-Digest) without downloading the full chunk.
      parameters:
        - name: offset
          in: path
          required: true
          description: Weave offset (0-based byte position in the weave)
          schema:
            type: integer
        - name: If-None-Match
          in: header
          required: false
          description: ETag value for conditional request. Returns 304 if chunk hash matches.
          schema:
            type: string
      responses:
        '200':
          description: Chunk metadata in headers only
          headers:
            Content-Type:
              description: Media type of the response (if body were returned)
              schema:
                type: string
                example: application/octet-stream
            Content-Length:
              description: Size of the raw chunk in bytes
              schema:
                type: integer
            X-Arweave-Chunk-Data-Path:
              description: |-
                Base64url-encoded merkle proof path for this chunk.
                Provides cryptographic proof of the chunk's position in the merkle tree.
                Uses base64url encoding (URL-safe), not standard base64.
                Always present.
              schema:
                type: string
            X-Arweave-Chunk-Data-Root:
              description: |-
                Base64url-encoded merkle tree root hash.
                Root of the merkle tree used to verify chunk integrity.
                Uses base64url encoding (URL-safe), not standard base64.
                Always present.
              schema:
                type: string
            X-Arweave-Chunk-Start-Offset:
              description: |-
                Start offset of this chunk in the weave (inclusive, 0-based byte position).
                This is the weave-relative position where this chunk begins.
                To calculate chunk end offset: startOffset + Content-Length.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Relative-Start-Offset:
              description: |-
                Byte offset where this chunk starts within its containing transaction (inclusive, 0-based).
                Calculated as: X-Arweave-Chunk-Start-Offset - X-Arweave-Chunk-Tx-Start-Offset.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Read-Offset:
              description: |-
                Byte offset within the returned chunk body where your requested data starts (0-based).
                Since full chunks are always returned (determined by merkle tree boundaries),
                this tells you where to start reading within the response body to get the data at your requested offset.
                Example: if you request offset 50100 and the chunk starts at 50000, this will be 100.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Tx-Data-Size:
              description: |-
                Total size of the containing transaction's data in bytes.
                Always present.
              schema:
                type: integer
            X-Arweave-Chunk-Tx-Path:
              description: |-
                Base64url-encoded transaction-level merkle path.
                Always present but may be empty string if transaction path is not available.
                Uses base64url encoding (URL-safe), not standard base64.
              schema:
                type: string
            X-Arweave-Chunk-Tx-Id:
              description: |-
                The Arweave transaction ID (base64url) containing this chunk.
                Always present.
              schema:
                type: string
            X-Arweave-Chunk-Tx-Start-Offset:
              description: |-
                Start offset of the containing transaction in the weave (inclusive, 0-based byte position).
                This is the weave-relative position where the transaction begins.
                To calculate transaction end offset: txStartOffset + X-Arweave-Chunk-Tx-Data-Size.
                Always present.
              schema:
                type: integer
            X-Cache:
              description: |-
                Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).
                Always present.
              schema:
                type: string
                enum: [HIT, MISS]
              example: HIT
            X-AR-IO-Chunk-Source-Type:
              description: |-
                Source type of the chunk data (e.g., 'cache', 'origin', 'peer').
                Present when source information is available.
              schema:
                type: string
              example: cache
            X-AR-IO-Chunk-Host:
              description: |-
                Hostname or identifier of the source that provided this chunk.
                Present when source host information is available.
              schema:
                type: string
              example: gateway.example.com
            ETag:
              description: |-
                Strong ETag based on SHA-256 hash of chunk data (base64url-encoded).
                Present only for cached chunks or HEAD requests to ensure hash accuracy.
                Use with If-None-Match header for conditional requests.
              schema:
                type: string
              example: '4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4'
            Content-Digest:
              description: |-
                RFC 9530 compliant digest header with SHA-256 hash of chunk data.
                Present only for cached chunks or HEAD requests to ensure hash accuracy.
                Format: sha-256=:<base64-encoded-hash>: (uses standard base64, not base64url).
              schema:
                type: string
              example: 'sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:'
        '304':
          description: Not Modified - chunk hash matches If-None-Match header
        '400':
          description: Invalid offset parameter
        '404':
          description: Chunk not found
        '500':
          description: Internal server error (e.g., merkle path parsing failed)

  # Index
  '/graphql':
    post:
      tags: [Index Querying]
      summary: Query indexed data using GraphQL
      description: |
        GraphQL endpoint for querying indexed transaction and block data. Supports:
        - Transaction queries by ID, owner, recipient, tags, and bundle
        - Block queries by ID and height
        - Pagination and sorting
        - Rich metadata including sizes, content types, and signatures

        Open `/graphql` in a browser for the Apollo Sandbox, an interactive
        query UI with full schema documentation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: GraphQL query string
                variables:
                  type: object
                  description: Query variables
              example:
                query: |
                  query {
                    transaction(
                      id: "D6I-Ke9oLg7sU_PS4oADQmnyFRa1jj2Zs1DP9BltrFs"
                    ) {
                      signature
                      owner {
                        address
                      }
                      bundledIn {
                        id
                      }
                      block {
                        height
                      }
                    }
                  }
      responses:
        '200':
          description: Successful GraphQL response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    description: Query results
                    example: |
                      {
                        "transaction": {
                          "signature": "4wh6PDJH6eyCKAWZoW26T0qt5NNjnVgyPjLs5HDR7fYgOyzEZF8FyIJiz01IRVvmXC9WZKvy2uLGiIdW4GtUNhs",
                          "owner": {
                            "address": "WbE3R_GcAalEP-VonRpL2P5TG30PJRA1-Tj20E_xIK0"
                          },
                          "bundledIn": {
                            "id": "yU5ilscWlDecDhUmNcd24zqe9HmNZ31h31BxC_VcXIM"
                          },
                          "block": null
                        }
                      }
                  errors:
                    type: array
                    description: Query errors if any
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        locations:
                          type: array
                          items:
                            type: object
                            properties:
                              line:
                                type: integer
                              column:
                                type: integer
                        path:
                          type: array
                          items:
                            type: string
        '400':
          description: Invalid GraphQL query
        '500':
          description: Server error

  # ArNS
  '/ar-io/resolver/{name}':
    get:
      tags: [ArNS]
      summary: Get ArNS name resolution.
      description: Get detailed information of a specified ArNS name.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful resolution of ArNS name. With HTTPSIG_ENABLED, the
            response signature covers every X-ArNS-* header listed here. It
            binds them as this gateway's claim, not as chain state: a gateway
            resolving through a trusted gateway relays that gateway's values.
          headers:
            x-arns-resolved-id:
              schema:
                $ref: '#/components/schemas/Base64Url43'
              description: The resolved transaction ID
            x-arns-ttl-seconds:
              schema:
                type: string
              description: Time-to-live in seconds for this resolution
            x-arns-ant-program-id:
              schema:
                type: string
              description: |
                Solana program ID of the AR.IO ANT program that owns the
                ANT mint that resolved this name. Single value across all
                ArNS names served by this gateway. Set from
                ARIO_ANT_PROGRAM_ID.
            x-arns-ant-id:
              schema:
                type: string
              description: |
                Per-ANT identifier for the ANT that resolved this request —
                the ANT mint's PDA (base58 pubkey). Omitted when resolution
                came via a trusted-gateway peer that has not yet shipped
                this header.
            x-arns-resolved-at:
              schema:
                type: string
              description: Unix timestamp when the name was resolved
            x-arns-record-index:
              schema:
                type: number
              description: Index of the name in the sorted list of names
            x-arns-undername-limit:
              schema:
                type: number
              description: The undername limit for the base ArNS name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArNSResolution'
        '404':
          description: ArNS name not found.

  # Admin
  '/ar-io/admin/debug':
    get:
      tags: [Admin]
      summary: Admin debugging information.
      description: Get detailed information about the current operational state of your AR.IO Gateway, including information about any current warnings or errors.
      operationId: adminDebug
      responses:
        '200':
          description: Successful operation.
        '401':
          description: Unauthorized, API key likely incorrect.
      security:
        - bearerAuth: []
  '/ar-io/admin/queue-tx':
    post:
      tags: [Admin]
      summary: Prioritize a transaction or bundle in the queue.
      description: Stage a specific TX ID as priority for your Gateway to locate and index. This will trigger and queue bundle processing if the transaction is a bundle, and your Gateway is configured to unbundle and index.
      operationId: adminQueueTx
      requestBody:
        $ref: '#/components/requestBodies/QueueTxRequest'
      responses:
        '200':
          $ref: '#/components/responses/QueueTxSuccess'
        '400':
          $ref: '#/components/responses/MissingId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
  '/ar-io/admin/queue-bundle':
    post:
      tags: [Admin]
      summary: Queue a bundle for indexing, bypassing any filter settings by default.
      description: Queue a bundle for indexing, bypassing any filter settings by default.
      operationId: adminQueueBundle
      requestBody:
        $ref: '#/components/requestBodies/QueueTxRequest'
      responses:
        '200':
          $ref: '#/components/responses/QueueTxSuccess'
        '400':
          $ref: '#/components/responses/MissingIdOrBypassFilter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
  '/ar-io/admin/queue-data-item':
    post:
      tags: [Admin]
      summary: Queue data items for indexing
      description: |
        Queue one or more data items for indexing. This endpoint
        accepts an array of data item headers and prioritizes them for processing.
      operationId: adminQueueDataItem
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  data_size:
                    type: integer
                    description: Size of the data item in bytes
                  id:
                    $ref: '#/components/schemas/Base64Url43'
                    description: Data item ID
                  owner:
                    $ref: '#/components/schemas/Owner'
                    Description: Data item signer's public key
                  owner_address:
                    $ref: '#/components/schemas/Base64Url43'
                    description: Normalized address
                  signature:
                    $ref: '#/components/schemas/Signature'
                    description: Data item signature
                  tags:
                    $ref: '#/components/schemas/TagList'
                    description: Optional tags associated with the data item
                  content_type:
                    type: string
                    description: Optional content type of the data item
                  target:
                    $ref: '#/components/schemas/Base64Url43'
                    description: Optional target address
                  anchor:
                    $ref: '#/components/schemas/Base64Url43'
                    description: Optional anchor
                required:
                  - data_size
                  - id
                  - owner
                  - owner_address
                  - signature
              minItems: 1
      responses:
        '200':
          description: Data items successfully queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Data item(s) queued'
        '400':
          description: >-
            Invalid request body, or the batch exceeds
            QUEUE_DATA_ITEM_MAX_BATCH_SIZE (split the request).
          content:
            text/plain:
              schema:
                type: string
                example: 'Must provide array of data item headers'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: >-
            Indexer saturated — backpressure. Returned when the DataItemIndexer
            queue depth exceeds QUEUE_DATA_ITEM_BACKPRESSURE_DEPTH. Retry after
            the Retry-After interval.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            text/plain:
              schema:
                type: string
                example: 'Data item indexer saturated (queue depth 100001 exceeds 100000); retry after backpressure clears'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/admin/queue-optimistic-tx':
    post:
      tags: [Admin]
      summary: Optimistically index a signed L1 transaction before it mines
      description: |
        Index one or more signed L1 transaction headers so the transaction is
        resolvable (GraphQL `transaction(id)`, returning `block: null`) before it
        is mined. Trusted/allowlist only: requires the admin bearer token AND
        `OPTIMISTIC_TX_INDEXING_ENABLED=true` (disabled by default → 403). Every
        transaction is cryptographically verified (`arweave.transactions.verify`),
        so a forged id or `data_root` is rejected. The row is inserted with a NULL
        height and promoted in place when the transaction mines; never-mined rows
        are reclaimed by the stale-transaction GC. The data is never marked
        `verified` while the transaction is unmined (`height IS NULL`). Accepts a single
        transaction object or an array, up to `OPTIMISTIC_TX_MAX_BATCH_SIZE`.
      operationId: adminQueueOptimisticTx
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/L1TransactionHeader'
                - type: array
                  items:
                    $ref: '#/components/schemas/L1TransactionHeader'
                  minItems: 1
      responses:
        '200':
          description: Transaction(s) successfully indexed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Optimistic transaction(s) indexed'
        '400':
          description: Invalid request body, invalid signature, or batch over the size cap
          content:
            text/plain:
              schema:
                type: string
                example: 'Invalid signature for transaction <id>'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Optimistic transaction indexing is disabled (OPTIMISTIC_TX_INDEXING_ENABLED=false)
          content:
            text/plain:
              schema:
                type: string
                example: 'Optimistic tx indexing is disabled'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/admin/bundle-status/{id}':
    get:
      tags: [Admin]
      summary: Get bundle processing status
      description: |
        Returns detailed status information about a bundle's processing state, including counts of data items,
        processing timestamps, and retry attempts. This endpoint helps monitor the progress and state of bundle
        processing through the gateway's pipeline.
      operationId: adminBundleStatus
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
          description: Bundle ID
      responses:
        '200':
          description: Bundle status details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/Base64Url43'
                    description: Bundle transaction ID
                  formatId:
                    type: integer
                    description: Format ID of the bundle
                  unbundleFilterId:
                    type: integer
                    description: ID of the current unbundle filter configuration
                  indexFilterId:
                    type: integer
                    description: ID of the current index filter configuration
                  dataItemCount:
                    type: integer
                    description: Total number of data items in the bundle
                  matchedDataItemCount:
                    type: integer
                    description: Number of data items matching filter criteria
                  firstQueuedAt:
                    type: integer
                    description: Unix timestamp of first queue attempt
                  lastQueuedAt:
                    type: integer
                    description: Unix timestamp of most recent queue attempt
                  firstSkippedAt:
                    type: integer
                    nullable: true
                    description: Unix timestamp of first skip, if any
                  lastSkippedAt:
                    type: integer
                    nullable: true
                    description: Unix timestamp of most recent skip, if any
                  firstUnbundledAt:
                    type: integer
                    description: Unix timestamp when unbundling first started
                  lastUnbundledAt:
                    type: integer
                    description: Unix timestamp when unbundling was last performed
                  firstFullyIndexedAt:
                    type: integer
                    description: Unix timestamp when indexing first completed
                  lastFullyIndexedAt:
                    type: integer
                    description: Unix timestamp when indexing was last completed
                  rootTransactionId:
                    $ref: '#/components/schemas/Base64Url43'
                    description: Transaction ID of the root bundle
                  importAttemptCount:
                    type: integer
                    description: Number of times bundle import was attempted
                  duplicatedDataItemCount:
                    type: integer
                    description: Number of duplicate data items found
                  previousUnbundleFilterId:
                    type: integer
                    description: ID of the previous unbundle filter configuration
                  previousIndexFilterId:
                    type: integer
                    description: ID of the previous index filter configuration
                  retryAttemptCount:
                    type: integer
                    description: Number of retry attempts
                  firstRetriedAt:
                    type: integer
                    description: Unix timestamp of first retry attempt
                  lastRetriedAt:
                    type: integer
                    description: Unix timestamp of most recent retry attempt
                required:
                  - id
                  - formatId
                  - unbundleFilterId
                  - indexFilterId
                  - dataItemCount
                  - matchedDataItemCount
                  - rootTransactionId
                  - importAttemptCount
                  - duplicatedDataItemCount
        '400':
          description: Invalid bundle ID format
          content:
            text/plain:
              schema:
                type: string
                example: 'Must provide a valid bundle id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Bundle not found
          content:
            text/plain:
              schema:
                type: string
                example: 'Bundle not found'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/admin/block-data':
    put:
      tags: [Admin]
      summary: Blocks transactions or data-items so your AR.IO Gateway will not serve them.
      description: |
        Submits a TX ID/data-item ID or sha-256 content hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items.


        WARNING - Testing a TX ID here WILL result in that data being blocked by your Gateway.
      operationId: adminBlockData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: TX ID for a transaction you want to block.
                notes:
                  type: string
                  description: Any notes or comments related to the block data. Documentation purposes only.
                source:
                  type: string
                  description: The source from which the block data was obtained. Documentation purposes only.
            examples:
              example1:
                value:
                  id: '3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ'
                  notes: 'This content is offensive'
                  source: 'Public Block list'
      responses:
        '200':
          description: Successful operation.
        '401':
          description: Unauthorized, API key likely incorrect.
      security:
        - bearerAuth: []
  '/ar-io/admin/block-name':
    put:
      tags: [Admin]
      summary: Blocks an ARNS name so your AR.IO Gateway will not serve it.
      description: Blocks an ARNS name so your AR.IO Gateway will not serve it.
      operationId: adminBlockName
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name you want to block.
                notes:
                  type: string
                  description: Any notes or comments related to the block name. Documentation purposes only.
                source:
                  type: string
                  description: The source from which the block name was obtained. Documentation purposes only.
      responses:
        '200':
          description: Successful operation.
        '401':
          description: Unauthorized, API key likely incorrect.
      security:
        - bearerAuth: []
  '/ar-io/admin/unblock-data':
    put:
      tags: [Admin]
      summary: Unblock data.
      description: Unblock data blocked with `PUT /ar-io/admin/block-data`, by ID or by data hash, so your AR.IO Gateway will serve it again.
      operationId: adminUnblockData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The transaction or data item ID to unblock.
                hash:
                  type: string
                  description: The data hash to unblock.
            example:
              id: '3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ'
      responses:
        '200':
          description: Unblocked (`{"message":"Content unblocked"}`).
        '400':
          description: Neither `id` nor `hash` given, or one is not a string.
        '401':
          description: Unauthorized, API key likely incorrect.
      security:
        - bearerAuth: []
  '/ar-io/admin/unblock-name':
    put:
      tags: [Admin]
      summary: Unblock an ARNS name.
      description: Unblock an ARNS name so your AR.IO Gateway will serve it again.
      operationId: adminUnblockName
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name you want to unblock.
      responses:
        '200':
          description: Successful operation.
        '401':
          description: Unauthorized, API key likely incorrect.
      security:
        - bearerAuth: []
  '/ar-io/admin/export-parquet':
    post:
      tags: [Admin]
      summary: Export data to Parquet format
      description: |
        Initiates an export of data to Parquet format files. This process runs in the background
        and exports data for the specified block height range.
      operationId: adminExportParquet
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                outputDir:
                  type: string
                  description: Directory in the server where Parquet files will be saved
                startHeight:
                  type: integer
                  minimum: 0
                  description: Starting block height for the export
                endHeight:
                  type: integer
                  minimum: 0
                  description: Ending block height for the export
                maxFileRows:
                  type: integer
                  minimum: 0
                  description: Maximum number of rows per Parquet file
              required:
                - outputDir
                - startHeight
                - endHeight
                - maxFileRows
      responses:
        '200':
          description: Export process started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Parquet export started'
                  jobId:
                    type: string
                    description: |
                      Unique id for this export. Clients should poll
                      `/ar-io/admin/export-parquet/status/{jobId}` to track
                      outcome rather than the shared singleton endpoint,
                      which can be overwritten by other concurrent callers.
                    example: '2c3f4f8e-1b2d-4a4e-9e2a-6f2d2c3b4a5e'
        '400':
          description: Invalid parameters provided
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: An export is already in progress
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/admin/export-parquet/status':
    get:
      tags: [Admin]
      summary: Get latest Parquet export status (singleton)
      description: |
        Returns the most recently updated export status. Because the server
        runs at most one export at a time, this endpoint reflects whichever
        export POSTed last — it can be overwritten mid-poll if another
        caller submits. Prefer `/status/{jobId}` for per-job tracking.
      operationId: adminExportParquetStatus
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current export status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParquetExportStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/admin/export-parquet/status/{jobId}':
    get:
      tags: [Admin]
      summary: Get Parquet export status for a specific job
      description: |
        Returns the status record for the export identified by `jobId`
        (returned by `POST /ar-io/admin/export-parquet`). The server retains
        a bounded history of recent jobs; older job ids are evicted and
        return 404.
      operationId: adminExportParquetStatusByJobId
      security:
        - bearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Status for the requested job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParquetExportStatus'
        '404':
          description: Job id is unknown or has been evicted from history
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/admin/prune-stable-data-items':
    post:
      tags: [Admin]
      summary: Prune stable data items
      description: |
        Removes stable data items from the database that were indexed before the specified timestamp.
        This helps manage database size by removing older, stable data items.
      operationId: adminPruneStableDataItems
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                indexedAtThreshold:
                  type: integer
                  minimum: 0
                  description: Unix timestamp - data items indexed before this time will be pruned
              required:
                - indexedAtThreshold
            example:
              indexedAtThreshold: 1677721600
      responses:
        '200':
          description: Data items successfully pruned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Stable data items pruned successfully'
        '400':
          description: Invalid indexedAtThreshold parameter
          content:
            text/plain:
              schema:
                type: string
                example: 'Invalid indexedAtThreshold - must be a positive integer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  # Rate Limiting
  '/ar-io/rate-limit/ip/{ip}':
    get:
      tags: [Rate Limiting]
      summary: Query IP bucket balance
      description: |
        Get the current rate limit token balance for an IP address. Returns both regular
        (refilling) and paid tokens. Buckets are created on first request and refill over time.

        **Token System:**
        - 1 token = 1 KiB (1,024 bytes)
        - Regular tokens: Automatically refill based on configured rate (e.g., 20 KB/s)
        - Paid tokens: Acquired via x402 payments, never refill, consumed after regular tokens
      operationId: getRateLimitIpBalance
      parameters:
        - name: ip
          in: path
          required: true
          schema:
            type: string
            format: ipv4 or ipv6
          description: IP address (IPv4, IPv6, or IPv4-mapped IPv6 format)
          example: '192.168.1.100'
      responses:
        '200':
          description: Successfully retrieved IP bucket balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: IP address
                    example: '192.168.1.100'
                  tokens:
                    type: number
                    description: Regular tokens (refilling)
                    example: 95000
                  paidTokens:
                    type: number
                    description: Paid tokens (non-refilling)
                    example: 50000
                  capacity:
                    type: number
                    description: Maximum regular token capacity
                    example: 100000
                  refillRate:
                    type: number
                    description: Refill rate in tokens per second
                    example: 20
                  lastRefill:
                    type: number
                    format: int64
                    description: Last refill timestamp (Unix milliseconds)
                    example: 1735689600000
                required:
                  - ip
                  - tokens
                  - paidTokens
                  - capacity
                  - refillRate
                  - lastRefill
        '400':
          description: Invalid IP address format
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Invalid IP address format'
        '404':
          description: Bucket not found (created on first request)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Bucket not found'
                  message:
                    type: string
                    example: 'No rate limit bucket exists for this IP. Buckets are created on first request.'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags: [Rate Limiting]
      summary: Top up IP bucket
      description: |
        Add paid tokens to an IP bucket via x402 payment or admin authentication.

        **Authentication Modes:**

        1. **x402 Payment (Public):**
           - Provide X-Payment header with payment data
           - Tokens calculated from payment amount
           - 10x capacity multiplier applied
           - Example: $0.10 payment → ~976 KB equivalent → ~976,000 tokens

        2. **Admin (Private/Testing):**
           - Provide Authorization: Bearer header with admin API key
           - Specify exact token count and type in request body
           - No multiplier applied (raw token count)
           - Only supports paid tokens currently
      operationId: topUpRateLimitIpBucket
      parameters:
        - name: ip
          in: path
          required: true
          schema:
            type: string
            format: ipv4 or ipv6
          description: IP address
          example: '192.168.1.100'
        - name: X-Payment
          in: header
          required: false
          schema:
            type: string
            format: base64
          description: |
            Base64-encoded x402 payment data (for x402 payment mode).
            Mutually exclusive with Authorization header.
      security:
        - {}
        - bearerAuth: []
      requestBody:
        description: |
          Required for admin authentication mode. Omit for x402 payment mode.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                tokens:
                  type: number
                  minimum: 1
                  description: Number of tokens to add (admin mode only)
                  example: 50000
                tokenType:
                  type: string
                  enum: [paid]
                  description: Type of tokens (admin mode only, currently only "paid" supported)
                  example: 'paid'
              required:
                - tokens
                - tokenType
      responses:
        '200':
          description: Successfully topped up IP bucket
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    example: '192.168.1.100'
                  tokens:
                    type: number
                    example: 95000
                  paidTokens:
                    type: number
                    example: 150000
                  capacity:
                    type: number
                    example: 100000
                  refillRate:
                    type: number
                    example: 20
                  lastRefill:
                    type: number
                    format: int64
                    example: 1735689600000
                  topUp:
                    type: object
                    description: Information about the top-up operation
                    properties:
                      tokensAdded:
                        type: number
                        description: Number of tokens added
                        example: 100000
                      paymentAmount:
                        type: string
                        description: Payment amount in USDC atomic units (x402 mode only)
                        example: '1000000'
                      multiplierApplied:
                        type: number
                        description: Capacity multiplier applied (10 for x402, 1 for admin)
                        example: 10
                      tokenType:
                        type: string
                        description: Type of tokens added (admin mode only)
                        example: 'paid'
                    required:
                      - tokensAdded
                      - multiplierApplied
        '400':
          description: Invalid IP format or invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Invalid tokens value'
                  message:
                    type: string
                    example: 'tokens must be a positive number'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Unauthorized'
                  message:
                    type: string
                    example: 'Provide X-Payment header for x402 payment or Authorization: Bearer header for admin access'
        '402':
          description: Payment verification or settlement failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Payment failed'
                  message:
                    type: string
                    example: 'Payment verification failed: insufficient amount'
        '500':
          $ref: '#/components/responses/ServerError'
  '/ar-io/rate-limit/resource':
    get:
      tags: [Rate Limiting]
      summary: Query resource bucket balance
      description: |
        Get the current rate limit token balance for a specific resource (method + host + path combination).
        Useful for monitoring resource-specific usage.

        **Smart Defaults:**
        - `method`: Defaults to "GET" (most common)
        - `host`: Defaults to current request's Host header
        - `path`: Required parameter
      operationId: getRateLimitResourceBalance
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
          description: Request path
          example: '/TX_ID'
        - name: method
          in: query
          required: false
          schema:
            type: string
            enum: [GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS]
            default: GET
          description: HTTP method
          example: 'GET'
        - name: host
          in: query
          required: false
          schema:
            type: string
          description: Host header (defaults to current request host)
          example: 'gateway.example.com'
      responses:
        '200':
          description: Successfully retrieved resource bucket balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  method:
                    type: string
                    example: 'GET'
                  host:
                    type: string
                    example: 'gateway.example.com'
                  path:
                    type: string
                    example: '/TX_ID'
                  tokens:
                    type: number
                    description: Regular tokens (refilling)
                    example: 980000
                  paidTokens:
                    type: number
                    description: Paid tokens (non-refilling)
                    example: 100000
                  capacity:
                    type: number
                    description: Maximum regular token capacity
                    example: 1000000
                  refillRate:
                    type: number
                    description: Refill rate in tokens per second
                    example: 100
                  lastRefill:
                    type: number
                    format: int64
                    description: Last refill timestamp (Unix milliseconds)
                    example: 1735689600000
                required:
                  - method
                  - host
                  - path
                  - tokens
                  - paidTokens
                  - capacity
                  - refillRate
                  - lastRefill
        '400':
          description: Missing path parameter or invalid method
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Missing required parameter: path'
                  validMethods:
                    type: array
                    items:
                      type: string
                    example: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
        '404':
          description: Bucket not found (created on first request)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Bucket not found'
                  message:
                    type: string
                    example: 'No rate limit bucket exists for this resource. Buckets are created on first request.'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags: [Rate Limiting]
      summary: Top up resource bucket
      description: |
        Add paid tokens to a resource bucket via x402 payment or admin authentication.
        Uses same authentication modes as IP bucket top-up.

        **Resource Identification:**
        - Combination of method + host + path uniquely identifies a resource bucket
        - Smart defaults: method=GET, host=current request host
      operationId: topUpRateLimitResourceBucket
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
          description: Request path
          example: '/TX_ID'
        - name: method
          in: query
          required: false
          schema:
            type: string
            enum: [GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS]
            default: GET
          description: HTTP method
          example: 'GET'
        - name: host
          in: query
          required: false
          schema:
            type: string
          description: Host header (defaults to current request host)
          example: 'gateway.example.com'
        - name: X-Payment
          in: header
          required: false
          schema:
            type: string
            format: base64
          description: Base64-encoded x402 payment data (for x402 payment mode)
      security:
        - {}
        - bearerAuth: []
      requestBody:
        description: Required for admin authentication mode. Omit for x402 payment mode.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                tokens:
                  type: number
                  minimum: 1
                  description: Number of tokens to add (admin mode only)
                  example: 50000
                tokenType:
                  type: string
                  enum: [paid]
                  description: Type of tokens (admin mode only)
                  example: 'paid'
              required:
                - tokens
                - tokenType
      responses:
        '200':
          description: Successfully topped up resource bucket
          content:
            application/json:
              schema:
                type: object
                properties:
                  method:
                    type: string
                    example: 'GET'
                  host:
                    type: string
                    example: 'gateway.example.com'
                  path:
                    type: string
                    example: '/TX_ID'
                  tokens:
                    type: number
                    example: 980000
                  paidTokens:
                    type: number
                    example: 150000
                  capacity:
                    type: number
                    example: 1000000
                  refillRate:
                    type: number
                    example: 100
                  lastRefill:
                    type: number
                    format: int64
                    example: 1735689600000
                  topUp:
                    type: object
                    properties:
                      tokensAdded:
                        type: number
                        example: 100000
                      paymentAmount:
                        type: string
                        example: '1000000'
                      multiplierApplied:
                        type: number
                        example: 10
                      tokenType:
                        type: string
                        example: 'paid'
                    required:
                      - tokensAdded
                      - multiplierApplied
        '400':
          description: Missing parameters or invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Missing required parameter: path'
                  validMethods:
                    type: array
                    items:
                      type: string
                    example: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Unauthorized'
                  message:
                    type: string
                    example: 'Provide X-Payment header for x402 payment or Authorization: Bearer header for admin access'
        '402':
          description: Payment verification or settlement failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Payment failed'
                  message:
                    type: string
                    example: 'Payment settlement failed: timeout'
        '500':
          $ref: '#/components/responses/ServerError'

  # Farcaster
  '/local/farcaster/frame/{txId}':
    get:
      tags: [Farcaster Frames]
      summary: Handle a Farcaster initial Frame request.
      description: Responds to a Farcaster initial Frame GET request by
        returning the content of a specified Arweave transaction or data item.
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Transaction'
    post:
      tags: [Farcaster Frames]
      summary: Handle a Farcaster response Frame request.
      description: Responds to a Farcaster response Frame POST request by
        returning the content of a specified Arweave transaction or data item.
      parameters:
        - name: txId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Base64Url43'
      responses:
        '200':
          description: |-
            Successful operation.
          content:
            application/json:
              schema:
                '$ref': '#/components/schemas/Transaction'