openapi: 3.0.3
info:
  title: Transpose Block API NFT API API
  description: 'Historical blockchain data REST API providing access to transaction history, token transfers, NFT metadata, smart contract events, DEX swaps, and price data across Ethereum and other EVM-compatible chains. Offers five enterprise-grade REST APIs plus a SQL Analytics API for querying indexed blockchain data across Ethereum, Polygon, Optimism, Base, Arbitrum, Avalanche, BSC, Bitcoin, and Tron.

    '
  version: 1.0.0
  contact:
    name: Transpose Support
    url: https://www.transpose.io/
  license:
    name: Commercial
    url: https://www.transpose.io/pricing
servers:
- url: https://api.transpose.io
  description: Transpose production API
security:
- ApiKeyAuth: []
tags:
- name: NFT API
  description: 'NFT collections, ownership, sales, and transfers for ERC-721 and ERC-1155 tokens.

    '
paths:
  /nft/collections:
    get:
      tags:
      - NFT API
      summary: Get NFT Collections
      operationId: getNftCollections
      description: 'Query NFT collections using flexible parameters to retrieve metadata and images. Filter by contract address, name, symbol, or creation date.

        '
      parameters:
      - $ref: '#/components/parameters/ChainId'
      - name: contract_address
        in: query
        required: false
        description: Filter by collection contract address.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Filter collections by name (partial match).
        schema:
          type: string
      - name: symbol
        in: query
        required: false
        description: Filter collections by symbol.
        schema:
          type: string
      - name: created_after
        in: query
        required: false
        description: Return collections created after this date.
        schema:
          type: string
      - name: created_before
        in: query
        required: false
        description: Return collections created before this date.
        schema:
          type: string
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful response containing NFT collections.
          headers:
            X-Credits-Charged:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/NftCollection'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nft/nfts:
    get:
      tags:
      - NFT API
      summary: Get NFTs
      operationId: getNfts
      description: 'Retrieve individual NFTs with rich metadata and media assets. Filter by contract, token ID, mint date, name, or owner.

        '
      parameters:
      - $ref: '#/components/parameters/ChainId'
      - name: contract_address
        in: query
        required: false
        description: Filter NFTs by collection contract address.
        schema:
          type: string
      - name: token_id
        in: query
        required: false
        description: Filter by specific token ID.
        schema:
          type: string
      - name: owner_address
        in: query
        required: false
        description: Filter NFTs by current owner address.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Filter NFTs by name.
        schema:
          type: string
      - name: minted_after
        in: query
        required: false
        description: Return NFTs minted after this date.
        schema:
          type: string
      - name: minted_before
        in: query
        required: false
        description: Return NFTs minted before this date.
        schema:
          type: string
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful response containing NFTs.
          headers:
            X-Credits-Charged:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Nft'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nft/transfers:
    get:
      tags:
      - NFT API
      summary: Get NFT Transfers
      operationId: getNftTransfers
      description: 'Track all NFT movements including mints, transfers, and burns across ERC-721 and ERC-1155 standards within a specified date range.

        '
      parameters:
      - $ref: '#/components/parameters/ChainId'
      - name: contract_address
        in: query
        required: false
        description: Filter transfers by NFT collection contract address.
        schema:
          type: string
      - name: token_id
        in: query
        required: false
        description: Filter transfers by token ID.
        schema:
          type: string
      - name: from_address
        in: query
        required: false
        description: Filter transfers by sender address.
        schema:
          type: string
      - name: to_address
        in: query
        required: false
        description: Filter transfers by recipient address.
        schema:
          type: string
      - $ref: '#/components/parameters/TransferredAfter'
      - $ref: '#/components/parameters/TransferredBefore'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful response containing NFT transfers.
          headers:
            X-Credits-Charged:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/NftTransfer'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nft/sales:
    get:
      tags:
      - NFT API
      summary: Get NFT Sales
      operationId: getNftSales
      description: 'Query NFT sales transactions across decentralized exchanges including OpenSea, LooksRare, Blur, and other NFT marketplaces.

        '
      parameters:
      - $ref: '#/components/parameters/ChainId'
      - name: contract_address
        in: query
        required: false
        description: Filter sales by NFT collection contract address.
        schema:
          type: string
      - name: token_id
        in: query
        required: false
        description: Filter sales by token ID.
        schema:
          type: string
      - name: account_address
        in: query
        required: false
        description: Filter sales by buyer or seller address.
        schema:
          type: string
      - $ref: '#/components/parameters/TransferredAfter'
      - $ref: '#/components/parameters/TransferredBefore'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful response containing NFT sales.
          headers:
            X-Credits-Charged:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/NftSale'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nft/owners:
    get:
      tags:
      - NFT API
      summary: Get NFT Owners
      operationId: getNftOwners
      description: 'Access ownership information for collections and individual tokens, including historical NFT balances and ownership history.

        '
      parameters:
      - $ref: '#/components/parameters/ChainId'
      - name: contract_address
        in: query
        required: false
        description: Filter owners by collection contract address.
        schema:
          type: string
      - name: token_id
        in: query
        required: false
        description: Filter by specific token ID.
        schema:
          type: string
      - name: owner_address
        in: query
        required: false
        description: Filter by specific owner address.
        schema:
          type: string
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful response containing NFT ownership data.
          headers:
            X-Credits-Charged:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        contract_address:
                          type: string
                        token_id:
                          type: string
                        owner_address:
                          type: string
                        quantity:
                          type: integer
                          description: Token balance (relevant for ERC-1155).
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    TransferredAfter:
      name: transferred_after
      in: query
      required: false
      description: 'The earlier transfer date, inclusive. Accepts Unix epoch seconds or ISO-8601 format.

        '
      schema:
        type: string
    ChainId:
      name: chain_id
      in: query
      required: true
      description: 'A keyword (e.g., "ethereum") or CAIP-2 identifier specifying the blockchain to query. Supported values: ethereum, polygon, optimism, scroll, arbitrum, base, avalanche.

        '
      schema:
        type: string
        example: ethereum
        enum:
        - ethereum
        - polygon
        - optimism
        - scroll
        - arbitrum
        - base
        - avalanche
    Order:
      name: order
      in: query
      required: false
      description: Sort direction for results.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
    TransferredBefore:
      name: transferred_before
      in: query
      required: false
      description: 'The later transfer date, inclusive. Accepts Unix epoch seconds or ISO-8601 format.

        '
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return.
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 500
  schemas:
    Nft:
      type: object
      description: Represents an individual NFT.
      properties:
        contract_address:
          type: string
        token_id:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        minted_timestamp:
          type: string
          format: date-time
        owner_address:
          type: string
    NftTransfer:
      type: object
      description: Represents an NFT transfer event.
      properties:
        transaction_hash:
          type: string
        log_index:
          type: integer
        block_number:
          type: integer
        timestamp:
          type: string
          format: date-time
        contract_address:
          type: string
        token_id:
          type: string
        from_address:
          type: string
        to_address:
          type: string
        token_standard:
          type: string
          enum:
          - erc721
          - erc1155
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Human-readable error description.
    NftCollection:
      type: object
      description: Represents an NFT collection.
      properties:
        contract_address:
          type: string
        name:
          type: string
        symbol:
          type: string
        token_standard:
          type: string
          enum:
          - erc721
          - erc1155
        created_timestamp:
          type: string
          format: date-time
        creator_address:
          type: string
        total_supply:
          type: integer
    NftSale:
      type: object
      description: Represents an NFT sale transaction.
      properties:
        transaction_hash:
          type: string
        log_index:
          type: integer
        block_number:
          type: integer
        timestamp:
          type: string
          format: date-time
        contract_address:
          type: string
        token_id:
          type: string
        seller_address:
          type: string
        buyer_address:
          type: string
        price:
          type: string
          description: Sale price in ETH.
        exchange_name:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key obtained from your Transpose team dashboard.