Zerion nfts API

openapi: 3.0.3
info:
  version: 1.0.0
  title: REST chains nfts API
  description: REST-like API provides access to rich Zerion ecosystem.
  contact:
    name: Zerion API
    url: https://developers.zerion.io/
    email: api@zerion.io
servers:
- description: Production API
  url: https://api.zerion.io
security:
- APIKeyBasicAuth: []
tags:
- name: nfts
  description: Operations related to non fungible assets, such list them, search or get by ID.
paths:
  /v1/nfts/:
    get:
      operationId: listNFTs
      summary: Get list of NFTs
      description: 'This endpoint returns list of NFTs by using different parameters.


        It returns NFTs of both types - ERC721 and ERC1155.


        This endpoint supports testnets. To get data for testnets use `X-Env` header.


        > NOTE: Consider all IDs as abstract strings, without making any assumptions about their format or relying on such assumptions. There is a non-zero probability that IDs may change in the future, and this should not result in any breaking changes.

        '
      tags:
      - nfts
      parameters:
      - name: filter[references]
        in: query
        style: form
        explode: false
        description: 'Keep only NFTs matching specified references.


          Reference format is `chain_id:contract_address:token_id`.


          References should be separated by comma `,`.


          `chain_id`- ID of the chain where NFT exists, can be found in /chains endpoint.


          `contract_address` address of the deployed contract which NFT belongs to.


          `token_id` id of the NFT withing specified `contract_address`.


          NOTE: parameter currently is mandatory and can not be omitted.

          '
        schema:
          type: string
          example: ethereum:0x932261f9fc8da46c4a22e31b45c4de60623848bf:93673,polygon:0x3d8c06e65ebf06a9d40f313a35353be06bd46038:104901
          minItems: 1
          maxItems: 10
          items:
            type: string
      - $ref: '#/components/parameters/Currency'
      - name: include
        in: query
        required: false
        style: form
        explode: false
        description: Array of related resources to be included to the response (comma-separated list). This parameter corresponds to the JSON API schema.
        schema:
          type: array
          items:
            type: string
            example: nft_collections
            enum:
            - nft_collections
      - name: X-Env
        in: header
        description: Custom header that allows you to get data for testnets.
        required: false
        schema:
          type: string
          enum:
          - testnet
      responses:
        '200':
          $ref: '#/components/responses/NFTsResponse'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/nfts/{nft_id}:
    get:
      operationId: getNFTById
      summary: Get single NFT by ID
      description: 'This endpoint returns single NFT by its unique identifier.


        This endpoint supports testnets. To get data for testnets use `X-Env` header.

        '
      tags:
      - nfts
      parameters:
      - name: nft_id
        in: path
        required: true
        description: NFT unique identifier
        schema:
          type: string
      - $ref: '#/components/parameters/Currency'
      - name: include
        in: query
        required: false
        style: form
        explode: false
        description: Array of related resources to be included to the response (comma-separated list). This parameter corresponds to the JSON API schema.
        schema:
          type: array
          items:
            type: string
            example: nft_collections
            enum:
            - nft_collections
      - name: X-Env
        in: header
        description: Custom header that allows you to get data for testnets.
        required: false
        schema:
          type: string
          enum:
          - testnet
      responses:
        '200':
          $ref: '#/components/responses/NFTResponse'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ContainerShort:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          description: Chain resource type.
          example: chains
        id:
          type: string
          description: Chain unique identifier.
          example: polygon
    ContainerAttributesNoMarketData:
      type: object
      description: Represents an NFT collection attributes corresponding to JSON API specification.
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata-2'
        implementations:
          type: array
          description: List of blockchain implementations where this collection is deployed
          items:
            $ref: '#/components/schemas/Implementation-2'
    ResponseData:
      type: array
      items:
        $ref: '#/components/schemas/Container-5'
    ExternalLinks:
      type: array
      description: A list of relevant URLs.
      items:
        $ref: '#/components/schemas/ExternalLink'
    Relationships-4:
      type: object
      description: Represents relationships of a non-fungible token (NFT) corresponding to JSON API specification.
      required:
      - chain
      properties:
        chain:
          allOf:
          - description: The blockchain on which the NFT exists.
          - $ref: '#/components/schemas/Relationship'
        nft_collection:
          allOf:
          - description: The collection that the NFT belongs to.
          - $ref: '#/components/schemas/Relationship-4'
    Container-5:
      type: object
      description: Represents a non-fungible token (NFT).
      required:
      - type
      - id
      properties:
        type:
          type: string
          description: NFTs resource type.
          example: nfts
        id:
          type: string
          description: Unique identifier of the NFT.
        attributes:
          $ref: '#/components/schemas/Attributes-7'
        relationships:
          $ref: '#/components/schemas/Relationships-4'
    RelationshipLinks:
      type: object
      required:
      - related
      properties:
        related:
          type: string
          format: url
          description: URL to the current chain.
          example: https://api.zerion.io/v1/chains/polygon
    Response-17:
      type: object
      required:
      - links
      - data
      properties:
        links:
          $ref: '#/components/schemas/ResponseLinks-18'
        data:
          $ref: '#/components/schemas/Container-5'
        included:
          $ref: '#/components/schemas/ResponseIncluded'
    Relationship-4:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/ContainerShort-4'
    MarketData-2:
      type: object
      properties:
        prices:
          $ref: '#/components/schemas/MarketDataPrices'
        last_sale:
          $ref: '#/components/schemas/LastSale'
    Relationship:
      type: object
      required:
      - links
      - data
      properties:
        links:
          $ref: '#/components/schemas/RelationshipLinks'
        data:
          $ref: '#/components/schemas/ContainerShort'
    Attributes-7:
      type: object
      description: Represents attributes of a non-fungible token (NFT) corresponding to JSON API specification.
      required:
      - contract_address
      - token_id
      properties:
        contract_address:
          type: string
          description: The address of the contract that manages the NFT.
          example: '0x74ee68a33f6c9f113e22b3b77418b75f85d07d22'
        token_id:
          type: string
          description: The unique identifier for the NFT within its contract.
          example: '10'
        interface:
          $ref: '#/components/schemas/InterfaceEnum'
        metadata:
          $ref: '#/components/schemas/Metadata'
        market_data:
          $ref: '#/components/schemas/MarketData-2'
        external_links:
          $ref: '#/components/schemas/ExternalLinks'
        flags:
          $ref: '#/components/schemas/Flags-3'
    Quantity:
      type: object
      required:
      - int
      - decimals
      - float
      - numeric
      properties:
        int:
          type: string
          description: Objective on-chain raw amount in base units. Use this value for building on-chain transactions.
          example: '12345678'
        decimals:
          type: integer
          description: Decimal number precision of the quantity - digits after the floating point.
          example: 5
        float:
          type: number
          format: float
          description: Ready-to-display value = int / 10^decimals. For Token-2022 ScaledUiAmount assets (a small subset of Solana tokens), the display value is int × multiplier / 10^decimals.
          example: 123.45678
        numeric:
          type: string
          description: Ready-to-display value = int / 10^decimals. For Token-2022 ScaledUiAmount assets (a small subset of Solana tokens), the display value is int × multiplier / 10^decimals.
          example: '123.45678'
    ResponseLinks-17:
      type: object
      required:
      - self
      properties:
        self:
          type: string
          description: Link to the current response
          example: https://api.zerion.io/v1/nfts/?currency=usd&filter%5Breferences%5D=ethereum%3A0x909899c5dbb5002610dd8543b6f638be56e3b17e%3A57896044618658097711785492504343953928676686534345912800509039648547174119787%2Cpolygon%3A0x3a422450db73c450310e6e24191d4221a5be81b1%3A30&include=nft_collections
    ContentLink:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: url
          description: URL to the content
          example: https://token-icons.s3.amazonaws.com/0x1494ca1f11d487c2bbe4543e90080aeba4ba3c2b.png
        content_type:
          type: string
          description: MIME content type
          example: image/png
    Content:
      type: object
      properties:
        preview:
          allOf:
          - description: The URL of the preview image
          - $ref: '#/components/schemas/ContentLink'
        detail:
          allOf:
          - description: The URL of the full-size image
          - $ref: '#/components/schemas/ContentLink'
        audio:
          allOf:
          - description: The URL of the audio file
          - $ref: '#/components/schemas/ContentLink'
        video:
          allOf:
          - description: The URL of the video file
          - $ref: '#/components/schemas/ContentLink'
    ContainerNoMarketData:
      type: object
      properties:
        type:
          type: string
          description: NFT collections resource type.
          example: nft_collections
        id:
          type: integer
          description: Unique NFT collection ID.
          example: 14
        attributes:
          $ref: '#/components/schemas/ContainerAttributesNoMarketData'
    Content-2:
      type: object
      properties:
        icon:
          allOf:
          - description: The URL for the collection's icon.
          - $ref: '#/components/schemas/Icon'
        banner:
          allOf:
          - description: The URL for the collection's banner image.
          - $ref: '#/components/schemas/ContentLink'
    ResponseLinks-18:
      type: object
      required:
      - self
      properties:
        self:
          type: string
          description: Link to the current response
          example: https://api.zerion.io/v1/nfts/polygon:0x3a422450db73c450310e6e24191d4221a5be81b1:2/?currency=usd&include=nft_collections
    ExternalLink:
      type: object
      required:
      - url
      properties:
        type:
          type: string
          description: Type of the link
          example: website
        name:
          type: string
          description: Displayable name of the link
          example: Website
        url:
          type: string
          format: url
          description: Link to the external resource
          example: https://www.indexcoop.com
    Attribute:
      type: object
      required:
      - key
      properties:
        key:
          type: string
          description: 'Attribute key. The key is not unique and is it possible to have several attributes

            with the same key.

            '
          example: Rarity
        value:
          type: string
          description: Attribute value
          example: common
    Icon:
      type: object
      description: Icon related to object.
      properties:
        url:
          type: string
          nullable: true
          format: url
          description: URL of the icon.
          example: https://token-icons.s3.amazonaws.com/0x0391d2021f89dc339f60fff84546ea23e337750f.png
    LastSale:
      type: object
      description: Information about last sale of the NFT.
      properties:
        price:
          type: number
          format: float
          description: The last known sale price of the NFT in the currency specified in the request parameters.
          example: 31
        quantity:
          allOf:
          - description: The quantity of the NFT in the last sale.
          - $ref: '#/components/schemas/Quantity'
    InterfaceEnum:
      type: string
      description: The standard that the NFT contract follows, e.g. ERC-721.
      example: erc1155
      enum:
      - erc721
      - erc1155
    Implementation-2:
      type: object
      description: Represents a blockchain implementation of an NFT collection.
      required:
      - chain_id
      - address
      properties:
        chain_id:
          type: string
          description: The chain ID where the collection is deployed.
          example: ethereum
        address:
          type: string
          nullable: true
          description: The contract address of the collection on the chain.
          example: '0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d'
    Metadata:
      type: object
      description: Metadata associated with the NFT.
      properties:
        name:
          type: string
          description: The name of the NFT
        description:
          type: string
          description: The description of the NFT
        tags:
          type: array
          description: The list of tags associated with the NFT
          items:
            type: string
        content:
          $ref: '#/components/schemas/Content'
        attributes:
          type: array
          description: The list of attributes associated with the NFT
          items:
            $ref: '#/components/schemas/Attribute'
    Flags-3:
      type: object
      properties:
        is_spam:
          type: boolean
          description: Indicates whether the NFT spam or not.
    Response-16:
      type: object
      required:
      - links
      - data
      properties:
        links:
          $ref: '#/components/schemas/ResponseLinks-17'
        data:
          $ref: '#/components/schemas/ResponseData'
        included:
          $ref: '#/components/schemas/ResponseIncluded'
    MarketDataPrices:
      type: object
      description: The prices associated with the NFT expressed in the currency specified in the request parameters.
      properties:
        floor:
          type: number
          format: float
          description: The lowest known price for the NFT.
    ContainerShort-4:
      type: object
      properties:
        type:
          type: string
          description: NFT collections resource type.
          example: nft_collections
        id:
          type: integer
          description: Unique NFT collection ID.
          example: 14
    ResponseIncluded:
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/ContainerNoMarketData'
    Metadata-2:
      type: object
      description: Metadata associated with the NFT.
      properties:
        name:
          type: string
          description: The name of the collection.
        description:
          type: string
          description: The description of the collection.
        content:
          $ref: '#/components/schemas/Content-2'
        payment_token_symbol:
          type: string
          description: The symbol for the payment token used by the collection.
  responses:
    NFTsResponse:
      description: Response for requested list of NFTs
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response-16'
    UnauthenticatedError:
      description: Unathenticated request
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      description: Error short title
                      example: Unauthorized Error
                    detail:
                      type: string
                      description: Long description of the error
                      example: The API key is invalid, please, make sure that you are using a valid key
    MalformedParameters:
      description: Parameters are malformed
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      description: Error short title
                      example: Parameter is malformed
                    detail:
                      type: string
                      description: Long description of the error
                      example: Some validation errors will be described here
    TooManyRequests:
      description: Too many requests error
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      description: Error short title
                      example: Too many requests
                    detail:
                      type: string
                      description: Long description of the error
                      example: Your request had been throttled
    NFTResponse:
      description: Requested NFT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response-17'
  parameters:
    Currency:
      name: currency
      in: query
      required: false
      description: Denominated currency value of returned prices
      schema:
        type: string
        default: usd
        enum:
        - eth
        - btc
        - usd
        - eur
        - krw
        - rub
        - gbp
        - aud
        - cad
        - inr
        - jpy
        - nzd
        - try
        - zar
        - cny
        - chf
  securitySchemes:
    APIKeyBasicAuth:
      type: http
      scheme: basic
      description: To test endpoints here, paste your API key from the [dashboard](https://dashboard.zerion.io/) into the username field and leave the password empty.
x-readme:
  samples-languages:
  - curl
  - javascript
  - python
  - kotlin
  - swift
  - go