From 112c40a1a0fcf3016d7d19bd21210408f8b2658b Mon Sep 17 00:00:00 2001
From: Peter Argue <89119817+peterargue@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:34:17 -0700
Subject: [PATCH 1/2] Add experimental FT and NFT REST API endpoints to OpenAPI
 spec

---
 openapi/experimental/openapi.yaml | 529 ++++++++++++++++++++++++++++++
 1 file changed, 529 insertions(+)

diff --git a/openapi/experimental/openapi.yaml b/openapi/experimental/openapi.yaml
index 47a357860..ef4bcea1c 100644
--- a/openapi/experimental/openapi.yaml
+++ b/openapi/experimental/openapi.yaml
@@ -17,6 +17,10 @@ security: []
 tags:
   - name: Accounts
     description: Endpoints for querying account-related data.
+  - name: FungibleTokens
+    description: Endpoints for querying fungible token data.
+  - name: NonFungibleTokens
+    description: Endpoints for querying non-fungible token data.
   - name: ScheduledTransactions
     description: Endpoints for querying scheduled transaction data.
   - name: Contracts
@@ -168,6 +172,324 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /experimental/v1/ft:
+    get:
+      summary: List fungible tokens
+      description: |
+        Returns a paginated list of fungible tokens known to the network.
+      operationId: getFungibleTokens
+      tags:
+        - FungibleTokens
+      parameters:
+        - $ref: "#/components/parameters/cursorParam"
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/labelParam"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: A page of fungible tokens.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FungibleTokensResponse"
+        "400":
+          description: Bad request (invalid cursor, limit, or filter).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/ft/transfers:
+    get:
+      summary: List fungible token transfers
+      description: |
+        Returns a paginated list of fungible token transfers across the network,
+        ordered descending by block height (newest first).
+      operationId: getFungibleTransfers
+      tags:
+        - FungibleTokens
+      parameters:
+        - $ref: "#/components/parameters/cursorParam"
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/tokenTypeParam"
+        - $ref: "#/components/parameters/sourceAddressParam"
+        - $ref: "#/components/parameters/recipientAddressParam"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: A page of fungible token transfers.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FungibleTransfersResponse"
+        "400":
+          description: Bad request (invalid cursor, limit, or filter).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/ft/{token}:
+    get:
+      summary: Get fungible token details
+      description: Returns details for the fungible token with the given fully qualified identifier.
+      operationId: getFungibleTokenByID
+      tags:
+        - FungibleTokens
+      parameters:
+        - name: token
+          in: path
+          required: true
+          description: Fully qualified token type identifier (e.g. `A.1654653399040a61.FlowToken`).
+          schema:
+            $ref: "#/components/schemas/ContractIdentifier"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: The fungible token details.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FungibleToken"
+        "400":
+          description: Bad request (invalid token identifier).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No fungible token found for the given identifier.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/ft/{token}/holders:
+    get:
+      summary: List fungible token holders
+      description: |
+        Returns a paginated list of holders of the given fungible token,
+        ordered descending by balance.
+      operationId: getFungibleTokenHolders
+      tags:
+        - FungibleTokens
+      parameters:
+        - name: token
+          in: path
+          required: true
+          description: Fully qualified token type identifier (e.g. `A.1654653399040a61.FlowToken`).
+          schema:
+            $ref: "#/components/schemas/ContractIdentifier"
+        - $ref: "#/components/parameters/cursorParam"
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: A page of token holders.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FungibleTokenHoldersResponse"
+        "400":
+          description: Bad request (invalid token identifier, cursor, or limit).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No fungible token found for the given identifier.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/nft:
+    get:
+      summary: List non-fungible tokens
+      description: |
+        Returns a paginated list of non-fungible token collections known to the network.
+      operationId: getNonFungibleTokens
+      tags:
+        - NonFungibleTokens
+      parameters:
+        - $ref: "#/components/parameters/cursorParam"
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/labelParam"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: A page of non-fungible token collections.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NonFungibleTokensResponse"
+        "400":
+          description: Bad request (invalid cursor, limit, or filter).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/nft/transfers:
+    get:
+      summary: List non-fungible token transfers
+      description: |
+        Returns a paginated list of non-fungible token transfers across the network,
+        ordered descending by block height (newest first).
+      operationId: getNonFungibleTransfers
+      tags:
+        - NonFungibleTokens
+      parameters:
+        - $ref: "#/components/parameters/cursorParam"
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/tokenTypeParam"
+        - $ref: "#/components/parameters/sourceAddressParam"
+        - $ref: "#/components/parameters/recipientAddressParam"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: A page of non-fungible token transfers.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NonFungibleTransfersResponse"
+        "400":
+          description: Bad request (invalid cursor, limit, or filter).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/nft/{token}:
+    get:
+      summary: Get non-fungible token details
+      description: Returns details for the non-fungible token collection with the given fully qualified identifier.
+      operationId: getNonFungibleTokenByID
+      tags:
+        - NonFungibleTokens
+      parameters:
+        - name: token
+          in: path
+          required: true
+          description: Fully qualified NFT collection type identifier (e.g. `A.1654653399040a61.TopShot`).
+          schema:
+            $ref: "#/components/schemas/ContractIdentifier"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: The non-fungible token collection details.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NonFungibleToken"
+        "400":
+          description: Bad request (invalid token identifier).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No non-fungible token found for the given identifier.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/nft/{token}/holders:
+    get:
+      summary: List non-fungible token holders
+      description: |
+        Returns a paginated list of holders of the given non-fungible token collection,
+        ordered descending by count.
+      operationId: getNonFungibleTokenHolders
+      tags:
+        - NonFungibleTokens
+      parameters:
+        - name: token
+          in: path
+          required: true
+          description: Fully qualified NFT collection type identifier (e.g. `A.1654653399040a61.TopShot`).
+          schema:
+            $ref: "#/components/schemas/ContractIdentifier"
+        - $ref: "#/components/parameters/cursorParam"
+        - $ref: "#/components/parameters/limitParam"
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: A page of token holders.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NonFungibleTokenHoldersResponse"
+        "400":
+          description: Bad request (invalid token identifier, cursor, or limit).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No non-fungible token found for the given identifier.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   /experimental/v1/scheduled:
     get:
       summary: List scheduled transactions
@@ -621,6 +943,13 @@ components:
         type: string
         format: uint64
       required: false
+    labelParam:
+      description: Filter by token label.
+      name: label
+      in: query
+      schema:
+        type: string
+      required: false
     contractNameParam:
       description: Filter by case sensitive contract name (unqualified, e.g. `EVM`).
       name: contract_name
@@ -1055,6 +1384,206 @@ components:
         - sender
         - recipient
 
+    FungibleToken:
+      type: object
+      required:
+        - name
+        - symbol
+        - decimals
+        - total_supply
+        - address
+        - contract
+        - holder_count
+      properties:
+        name:
+          description: Display name of the token.
+          type: string
+        symbol:
+          description: Ticker symbol of the token.
+          type: string
+        description:
+          description: Human-readable description of the token.
+          type: string
+        decimals:
+          description: Number of decimal places for the token.
+          type: integer
+        total_supply:
+          description: Total supply of the token, as a decimal string.
+          type: string
+        coingecko_url:
+          description: URL to the token's CoinGecko page.
+          type: string
+          format: uri
+        coinmarketcap_url:
+          description: URL to the token's CoinMarketCap page.
+          type: string
+          format: uri
+        created_at:
+          description: Timestamp when the token contract was first deployed (RFC 3339).
+          type: string
+          format: date-time
+        created_tx_id:
+          description: Transaction ID of the initial contract deployment.
+          $ref: "#/components/schemas/Identifier"
+        address:
+          description: Account address that owns the token contract.
+          $ref: "#/components/schemas/Address"
+        contract:
+          description: Fully qualified contract identifier.
+          $ref: "#/components/schemas/ContractIdentifier"
+        holder_count:
+          description: Number of accounts holding a non-zero balance.
+          type: integer
+        labels:
+          description: Classification labels for the token.
+          type: array
+          items:
+            type: string
+        _links:
+          $ref: "#/components/schemas/Links"
+    FungibleTokensResponse:
+      type: object
+      required:
+        - tokens
+      properties:
+        tokens:
+          type: array
+          items:
+            $ref: "#/components/schemas/FungibleToken"
+        next_cursor:
+          $ref: "#/components/schemas/Cursor"
+    FungibleTransfersResponse:
+      type: object
+      required:
+        - transfers
+      properties:
+        transfers:
+          type: array
+          items:
+            $ref: "#/components/schemas/FungibleTokenTransfer"
+        next_cursor:
+          $ref: "#/components/schemas/Cursor"
+    FungibleTokenHolder:
+      type: object
+      required:
+        - address
+        - balance
+        - percent
+      properties:
+        address:
+          $ref: "#/components/schemas/Address"
+        balance:
+          description: Token balance held by the account, as a decimal string.
+          type: string
+        percent:
+          description: Percentage of total supply held by the account, as a decimal string.
+          type: string
+    FungibleTokenHoldersResponse:
+      type: object
+      required:
+        - holders
+      properties:
+        holders:
+          type: array
+          items:
+            $ref: "#/components/schemas/FungibleTokenHolder"
+        next_cursor:
+          $ref: "#/components/schemas/Cursor"
+
+    NonFungibleToken:
+      type: object
+      required:
+        - display_name
+        - total_count
+        - address
+        - contract
+      properties:
+        display_name:
+          description: Display name of the NFT collection.
+          type: string
+        description:
+          description: Human-readable description of the NFT collection.
+          type: string
+        total_count:
+          description: Total number of NFTs minted in this collection.
+          type: integer
+        external_url:
+          description: External URL for the NFT collection.
+          type: string
+          format: uri
+        logo_url:
+          description: URL to the collection's logo image.
+          type: string
+          format: uri
+        created_at:
+          description: Timestamp when the NFT contract was first deployed (RFC 3339).
+          type: string
+          format: date-time
+        created_tx_id:
+          description: Transaction ID of the initial contract deployment.
+          $ref: "#/components/schemas/Identifier"
+        address:
+          description: Account address that owns the NFT contract.
+          $ref: "#/components/schemas/Address"
+        contract:
+          description: Fully qualified contract identifier.
+          $ref: "#/components/schemas/ContractIdentifier"
+        labels:
+          description: Classification labels for the NFT collection.
+          type: array
+          items:
+            type: string
+        _links:
+          $ref: "#/components/schemas/Links"
+    NonFungibleTokensResponse:
+      type: object
+      required:
+        - tokens
+      properties:
+        tokens:
+          type: array
+          items:
+            $ref: "#/components/schemas/NonFungibleToken"
+        next_cursor:
+          $ref: "#/components/schemas/Cursor"
+    NonFungibleTransfersResponse:
+      type: object
+      required:
+        - transfers
+      properties:
+        transfers:
+          type: array
+          items:
+            $ref: "#/components/schemas/NonFungibleTokenTransfer"
+        next_cursor:
+          $ref: "#/components/schemas/Cursor"
+    NonFungibleTokenHolder:
+      type: object
+      required:
+        - address
+        - count
+        - percent
+      properties:
+        address:
+          $ref: "#/components/schemas/Address"
+        count:
+          description: Number of NFTs held by the account in this collection.
+          type: integer
+        percent:
+          description: Percentage of total collection held by the account, as a decimal string.
+          type: string
+    NonFungibleTokenHoldersResponse:
+      type: object
+      required:
+        - holders
+      properties:
+        holders:
+          type: array
+          items:
+            $ref: "#/components/schemas/NonFungibleTokenHolder"
+        next_cursor:
+          $ref: "#/components/schemas/Cursor"
+
     ScheduledTransactionsResponse:
       type: object
       required:

From b6290333b86ba4e2f29dd309909bc5ec61ed4291 Mon Sep 17 00:00:00 2001
From: Peter Argue <89119817+peterargue@users.noreply.github.com>
Date: Thu, 2 Apr 2026 12:40:08 -0700
Subject: [PATCH 2/2] Rename path params to ft_type/nft_type and add individual
 NFT item endpoint

---
 openapi/experimental/openapi.yaml | 65 +++++++++++++++++++++++++++----
 1 file changed, 57 insertions(+), 8 deletions(-)

diff --git a/openapi/experimental/openapi.yaml b/openapi/experimental/openapi.yaml
index ef4bcea1c..30a28b827 100644
--- a/openapi/experimental/openapi.yaml
+++ b/openapi/experimental/openapi.yaml
@@ -243,7 +243,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
-  /experimental/v1/ft/{token}:
+  /experimental/v1/ft/{ft_type}:
     get:
       summary: Get fungible token details
       description: Returns details for the fungible token with the given fully qualified identifier.
@@ -251,7 +251,7 @@ paths:
       tags:
         - FungibleTokens
       parameters:
-        - name: token
+        - name: ft_type
           in: path
           required: true
           description: Fully qualified token type identifier (e.g. `A.1654653399040a61.FlowToken`).
@@ -285,7 +285,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
-  /experimental/v1/ft/{token}/holders:
+  /experimental/v1/ft/{ft_type}/holders:
     get:
       summary: List fungible token holders
       description: |
@@ -295,7 +295,7 @@ paths:
       tags:
         - FungibleTokens
       parameters:
-        - name: token
+        - name: ft_type
           in: path
           required: true
           description: Fully qualified token type identifier (e.g. `A.1654653399040a61.FlowToken`).
@@ -402,7 +402,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
-  /experimental/v1/nft/{token}:
+  /experimental/v1/nft/{nft_type}:
     get:
       summary: Get non-fungible token details
       description: Returns details for the non-fungible token collection with the given fully qualified identifier.
@@ -410,7 +410,7 @@ paths:
       tags:
         - NonFungibleTokens
       parameters:
-        - name: token
+        - name: nft_type
           in: path
           required: true
           description: Fully qualified NFT collection type identifier (e.g. `A.1654653399040a61.TopShot`).
@@ -444,7 +444,56 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
-  /experimental/v1/nft/{token}/holders:
+  /experimental/v1/nft/{nft_type}/item/{nft_id}:
+    get:
+      summary: Get individual NFT
+      description: Returns details for a specific NFT within a collection.
+      operationId: getNonFungibleTokenItem
+      tags:
+        - NonFungibleTokens
+      parameters:
+        - name: nft_type
+          in: path
+          required: true
+          description: Fully qualified NFT collection type identifier (e.g. `A.1654653399040a61.TopShot`).
+          schema:
+            $ref: "#/components/schemas/ContractIdentifier"
+        - name: nft_id
+          in: path
+          required: true
+          description: Unique identifier of the NFT within its collection.
+          schema:
+            type: string
+            format: uint64
+        - $ref: "#/components/parameters/expandParam"
+        - $ref: "#/components/parameters/selectParam"
+      responses:
+        "200":
+          description: The NFT details.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NonFungibleToken"
+        "400":
+          description: Bad request (invalid token identifier or NFT ID).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No NFT found for the given identifier.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many requests.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /experimental/v1/nft/{nft_type}/holders:
     get:
       summary: List non-fungible token holders
       description: |
@@ -454,7 +503,7 @@ paths:
       tags:
         - NonFungibleTokens
       parameters:
-        - name: token
+        - name: nft_type
           in: path
           required: true
           description: Fully qualified NFT collection type identifier (e.g. `A.1654653399040a61.TopShot`).