openapi.yaml

openapi: 3.0.3
info:
  title: Token Metadata API
  description: Welcome to the API reference overview for the [Token Metadata
    API](https://docs.hiro.so/token-metadata-api). Service that indexes metadata
    for every SIP-009, SIP-010, and SIP-013 Token in the Stacks blockchain and
    exposes it via REST API endpoints.
  version: v2.2.1
components:
  schemas: {}
paths:
  /metadata/v1/ft:
    get:
      operationId: getFungibleTokens
      summary: Fungible Tokens
      tags:
        - Tokens
      description: Retrieves a list of Fungible Tokens
      parameters:
        - schema:
            type: string
          in: query
          name: name
          required: false
        - schema:
            type: string
          in: query
          name: symbol
          required: false
        - schema:
            pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}
            title: Stacks Address
            type: string
          example: SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9
          in: query
          name: address
          required: false
          description: Stacks Address
        - schema:
            type: boolean
          in: query
          name: valid_metadata_only
          required: false
          description: If enabled, only tokens with valid SIP-016 metadata will be returned
        - schema:
            minimum: 0
            title: Offset
            type: integer
          in: query
          name: offset
          required: false
          description: Result offset
        - schema:
            minimum: 1
            maximum: 60
            title: Limit
            type: integer
          in: query
          name: limit
          required: false
          description: Results per page
        - schema:
            title: Order By
            anyOf:
              - type: string
                enum:
                  - name
              - type: string
                enum:
                  - symbol
          in: query
          name: order_by
          required: false
          description: Parameter to order results by
        - schema:
            title: Order
            anyOf:
              - type: string
                enum:
                  - asc
              - type: string
                enum:
                  - desc
          in: query
          name: order
          required: false
          description: Results order
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                title: Paginated Ft Basic Metadata Response
                type: object
                required:
                  - limit
                  - offset
                  - total
                  - results
                properties:
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
                  total:
                    type: integer
                    example: 1
                  results:
                    type: array
                    items:
                      title: Ft Basic Metadata Response
                      type: object
                      required:
                        - tx_id
                        - sender_address
                        - asset_identifier
                        - contract_principal
                      properties:
                        name:
                          type: string
                          example: Wrapped USD
                        symbol:
                          type: string
                          example: xUSD
                        decimals:
                          type: integer
                          example: 8
                        total_supply:
                          type: string
                          example: "9999980000000"
                        token_uri:
                          format: uri
                          description: URI for this token's metadata JSON
                          type: string
                          example: ipfs://ipfs/Qmf9yDYuPTrp8NRUFf8xxDd5Ud24Dx9uYMwMn8o8G2cWPW/12200.json
                        description:
                          description: Description
                          type: string
                          example: Heavy hitters, all-stars and legends of the game join forces to create
                            a collection of unique varsity jackets
                        image_uri:
                          format: uri
                          description: Cached image URL
                          type: string
                          example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                        image_thumbnail_uri:
                          format: uri
                          description: Cached image URL
                          type: string
                          example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                        image_canonical_uri:
                          format: uri
                          description: Original image URL
                          type: string
                          example: ipfs://ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                        tx_id:
                          type: string
                          example: 0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0
                        sender_address:
                          type: string
                          example: ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA
                        asset_identifier:
                          description: Clarity asset identifier
                          type: string
                          example: SPZA22A4D15RKH5G8XDGQ7BPC20Q5JNMH0VQKSR6.token-ststx-earn-v1::stSTXearn
                        contract_principal:
                          type: string
                          example: SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.miamicoin-token-v2
  /metadata/v1/ft/{principal}:
    get:
      operationId: getFtMetadata
      summary: Fungible Token Metadata
      tags:
        - Tokens
      description: Retrieves metadata for a SIP-010 Fungible Token
      parameters:
        - schema:
            title: Localization
            type: string
          examples:
            es-MX:
              value: es-MX
            jp:
              value: jp
          in: query
          name: locale
          required: false
          description: Metadata localization to retrieve
        - schema:
            pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
            title: Fungible Token Contract Principal
            type: string
          example: SP32XCD69XPS3GKDEXAQ29PJRDSD5AR643GNEEBXZ.fari-token
          in: path
          name: principal
          required: true
          description: Principal for the contract which owns the SIP-010 token
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                title: Ft Metadata Response
                type: object
                required:
                  - tx_id
                  - sender_address
                  - asset_identifier
                properties:
                  name:
                    description: Token name
                    type: string
                    example: Wrapped USD
                  symbol:
                    description: Token symbol
                    type: string
                    example: xUSD
                  decimals:
                    description: Number of decimal places clients should use to format this token's
                      amounts
                    type: integer
                    example: 8
                  total_supply:
                    description: Current circulating supply as reported by its contract. Clients
                      should format this amount with the correct number of
                      `decimals` before displaying to users
                    type: string
                    example: "9999980000000"
                  token_uri:
                    format: uri
                    description: URI for this token's metadata JSON
                    type: string
                    example: ipfs://ipfs/Qmf9yDYuPTrp8NRUFf8xxDd5Ud24Dx9uYMwMn8o8G2cWPW/12200.json
                  description:
                    description: Description
                    type: string
                    example: Heavy hitters, all-stars and legends of the game join forces to create
                      a collection of unique varsity jackets
                  image_uri:
                    format: uri
                    description: Cached image URL
                    type: string
                    example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                  image_thumbnail_uri:
                    format: uri
                    description: Cached image URL
                    type: string
                    example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                  image_canonical_uri:
                    format: uri
                    description: Original image URL
                    type: string
                    example: ipfs://ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                  tx_id:
                    description: ID for the transaction that deployed this token
                    type: string
                    example: "0x5642ca7d68976b6b2a2055689d9a57de26d67f0dd8b016d1b0d94cb634454cdd"
                  sender_address:
                    description: Deployer address
                    type: string
                    example: SPZA22A4D15RKH5G8XDGQ7BPC20Q5JNMH0VQKSR6
                  asset_identifier:
                    description: Clarity asset identifier
                    type: string
                    example: SPZA22A4D15RKH5G8XDGQ7BPC20Q5JNMH0VQKSR6.token-ststx-earn-v1::stSTXearn
                  metadata:
                    title: Metadata
                    type: object
                    required:
                      - sip
                    properties:
                      sip:
                        type: integer
                        example: 16
                      name:
                        type: string
                        example: "Satoshi's Team #12200"
                      description:
                        description: Description
                        type: string
                        example: Heavy hitters, all-stars and legends of the game join forces to create
                          a collection of unique varsity jackets
                      image:
                        format: uri
                        description: Original image URL
                        type: string
                        example: ipfs://ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      cached_image:
                        format: uri
                        description: Cached image URL
                        type: string
                        example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      cached_thumbnail_image:
                        format: uri
                        description: Cached image URL
                        type: string
                        example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      attributes:
                        type: array
                        items:
                          title: Metadata Attribute
                          type: object
                          required:
                            - trait_type
                            - value
                          properties:
                            trait_type:
                              type: string
                              example: Background
                            display_type:
                              type: string
                              example: string
                            value:
                              title: Metadata Value
                              example: value
                      properties:
                        title: Metadata Properties
                        type: object
                        additionalProperties:
                          title: Metadata Value
                          examples:
                            - value
                        example:
                          collection: Foo Collection
                          total_supply: "10000"
                      localization:
                        title: Metadata Localization
                        type: object
                        required:
                          - uri
                          - default
                          - locales
                        properties:
                          uri:
                            format: uri
                            type: string
                            example: http://token.com/metadata?hl={locale}
                          default:
                            type: string
                            example: en
                          locales:
                            type: array
                            items:
                              type: string
                            example:
                              - en
                              - jp
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                title: Not Found Error Response
                anyOf:
                  - title: Token Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Token not found
                  - title: Contract Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Contract not found
        "422":
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                anyOf:
                  - title: Token Metadata Fetch In Progress Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Token metadata fetch in progress
                  - title: Locale Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Locale not found
                  - type: object
                    required:
                      - error
                      - message
                    properties:
                      error:
                        type: string
                        enum:
                          - Token error
                      message:
                        type: string
  /metadata/v1/nft/{principal}/{token_id}:
    get:
      operationId: getNftMetadata
      summary: Non-Fungible Token Metadata
      tags:
        - Tokens
      description: Retrieves metadata for a SIP-009 Non-Fungible Token
      parameters:
        - schema:
            title: Localization
            type: string
          examples:
            es-MX:
              value: es-MX
            jp:
              value: jp
          in: query
          name: locale
          required: false
          description: Metadata localization to retrieve
        - schema:
            pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
            title: Non-Fungible Token Contract Principal
            type: string
          example: SP497E7RX3233ATBS2AB9G4WTHB63X5PBSP5VGAQ.boomboxes-cycle-12
          in: path
          name: principal
          required: true
          description: SIP-009 compliant smart contract principal
        - schema:
            title: Token ID
            type: integer
          example: "35"
          in: path
          name: token_id
          required: true
          description: Token ID to retrieve
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                title: Nft Metadata Response
                type: object
                properties:
                  token_uri:
                    format: uri
                    description: URI for this token's metadata JSON
                    type: string
                    example: ipfs://ipfs/Qmf9yDYuPTrp8NRUFf8xxDd5Ud24Dx9uYMwMn8o8G2cWPW/12200.json
                  metadata:
                    title: Metadata
                    type: object
                    required:
                      - sip
                    properties:
                      sip:
                        type: integer
                        example: 16
                      name:
                        type: string
                        example: "Satoshi's Team #12200"
                      description:
                        description: Description
                        type: string
                        example: Heavy hitters, all-stars and legends of the game join forces to create
                          a collection of unique varsity jackets
                      image:
                        format: uri
                        description: Original image URL
                        type: string
                        example: ipfs://ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      cached_image:
                        format: uri
                        description: Cached image URL
                        type: string
                        example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      cached_thumbnail_image:
                        format: uri
                        description: Cached image URL
                        type: string
                        example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      attributes:
                        type: array
                        items:
                          title: Metadata Attribute
                          type: object
                          required:
                            - trait_type
                            - value
                          properties:
                            trait_type:
                              type: string
                              example: Background
                            display_type:
                              type: string
                              example: string
                            value:
                              title: Metadata Value
                              example: value
                      properties:
                        title: Metadata Properties
                        type: object
                        additionalProperties:
                          title: Metadata Value
                          examples:
                            - value
                        example:
                          collection: Foo Collection
                          total_supply: "10000"
                      localization:
                        title: Metadata Localization
                        type: object
                        required:
                          - uri
                          - default
                          - locales
                        properties:
                          uri:
                            format: uri
                            type: string
                            example: http://token.com/metadata?hl={locale}
                          default:
                            type: string
                            example: en
                          locales:
                            type: array
                            items:
                              type: string
                            example:
                              - en
                              - jp
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                title: Not Found Error Response
                anyOf:
                  - title: Token Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Token not found
                  - title: Contract Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Contract not found
        "422":
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                anyOf:
                  - title: Token Metadata Fetch In Progress Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Token metadata fetch in progress
                  - title: Locale Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Locale not found
                  - type: object
                    required:
                      - error
                      - message
                    properties:
                      error:
                        type: string
                        enum:
                          - Token error
                      message:
                        type: string
  /metadata/v1/sft/{principal}/{token_id}:
    get:
      operationId: getSftMetadata
      summary: Semi-Fungible Token Metadata
      tags:
        - Tokens
      description: Retrieves metadata for a SIP-013 Semi-Fungible Token
      parameters:
        - schema:
            title: Localization
            type: string
          examples:
            es-MX:
              value: es-MX
            jp:
              value: jp
          in: query
          name: locale
          required: false
          description: Metadata localization to retrieve
        - schema:
            pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
            title: Semi-Fungible Token Contract Principal
            type: string
          example: SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.key-alex-autoalex-v1
          in: path
          name: principal
          required: true
          description: SIP-013 compliant smart contract principal
        - schema:
            title: Token ID
            type: integer
          example: "35"
          in: path
          name: token_id
          required: true
          description: Token ID to retrieve
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                title: Sft Metadata Response
                type: object
                properties:
                  token_uri:
                    format: uri
                    description: URI for this token's metadata JSON
                    type: string
                    example: ipfs://ipfs/Qmf9yDYuPTrp8NRUFf8xxDd5Ud24Dx9uYMwMn8o8G2cWPW/12200.json
                  decimals:
                    type: integer
                    example: 6
                  total_supply:
                    type: string
                    example: "250"
                  metadata:
                    title: Metadata
                    type: object
                    required:
                      - sip
                    properties:
                      sip:
                        type: integer
                        example: 16
                      name:
                        type: string
                        example: "Satoshi's Team #12200"
                      description:
                        description: Description
                        type: string
                        example: Heavy hitters, all-stars and legends of the game join forces to create
                          a collection of unique varsity jackets
                      image:
                        format: uri
                        description: Original image URL
                        type: string
                        example: ipfs://ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      cached_image:
                        format: uri
                        description: Cached image URL
                        type: string
                        example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      cached_thumbnail_image:
                        format: uri
                        description: Cached image URL
                        type: string
                        example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                      attributes:
                        type: array
                        items:
                          title: Metadata Attribute
                          type: object
                          required:
                            - trait_type
                            - value
                          properties:
                            trait_type:
                              type: string
                              example: Background
                            display_type:
                              type: string
                              example: string
                            value:
                              title: Metadata Value
                              example: value
                      properties:
                        title: Metadata Properties
                        type: object
                        additionalProperties:
                          title: Metadata Value
                          examples:
                            - value
                        example:
                          collection: Foo Collection
                          total_supply: "10000"
                      localization:
                        title: Metadata Localization
                        type: object
                        required:
                          - uri
                          - default
                          - locales
                        properties:
                          uri:
                            format: uri
                            type: string
                            example: http://token.com/metadata?hl={locale}
                          default:
                            type: string
                            example: en
                          locales:
                            type: array
                            items:
                              type: string
                            example:
                              - en
                              - jp
        "404":
          description: Default Response
          content:
            application/json:
              schema:
                title: Not Found Error Response
                anyOf:
                  - title: Token Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Token not found
                  - title: Contract Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Contract not found
        "422":
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                anyOf:
                  - title: Token Metadata Fetch In Progress Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Token metadata fetch in progress
                  - title: Locale Not Found Response
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: string
                        enum:
                          - Locale not found
                  - type: object
                    required:
                      - error
                      - message
                    properties:
                      error:
                        type: string
                        enum:
                          - Token error
                      message:
                        type: string
  /metadata/v1/search:
    get:
      operationId: searchTokens
      summary: Search Tokens
      tags:
        - Tokens
      description: Retrieves metadata for multiple tokens in a single request. Accepts
        up to 50 contract identifiers.
      parameters:
        - schema:
            minItems: 1
            maxItems: 50
            title: Contract Identifiers
            type: array
            items:
              pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}(:\d+)?$
              title: Contract Identifier
              description: "Format: PRINCIPAL or PRINCIPAL:TOKEN_NUMBER"
              examples:
                - SP32XCD69XPS3GKDEXAQ29PJRDSD5AR643GNEEBXZ.fari-token
                - SP497E7RX3233ATBS2AB9G4WTHB63X5PBSP5VGAQ.boomboxes-cycle-12:120
              type: string
          in: query
          name: contract
          required: true
          description: "Contract identifiers to search for. Format: PRINCIPAL or
            PRINCIPAL:TOKEN_NUMBER. Defaults token_number to 1 when omitted."
        - schema:
            title: Localization
            type: string
          examples:
            es-MX:
              value: es-MX
            jp:
              value: jp
          in: query
          name: locale
          required: false
          description: Metadata localization to retrieve
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                title: Search Response
                type: array
                items:
                  title: Search Result Item
                  type: object
                  required:
                    - contract_id
                    - token_number
                    - token_type
                    - tx_id
                    - sender_address
                  properties:
                    contract_id:
                      description: Contract principal
                      type: string
                      example: SP32XCD69XPS3GKDEXAQ29PJRDSD5AR643GNEEBXZ.fari-token
                    token_number:
                      description: Token number
                      type: integer
                      example: 1
                    token_type:
                      description: Token type (ft, nft, sft)
                      type: string
                      example: ft
                    name:
                      type: string
                      example: Wrapped USD
                    symbol:
                      type: string
                      example: xUSD
                    decimals:
                      type: integer
                      example: 8
                    total_supply:
                      type: string
                      example: "9999980000000"
                    token_uri:
                      format: uri
                      description: URI for this token's metadata JSON
                      type: string
                      example: ipfs://ipfs/Qmf9yDYuPTrp8NRUFf8xxDd5Ud24Dx9uYMwMn8o8G2cWPW/12200.json
                    description:
                      description: Description
                      type: string
                      example: Heavy hitters, all-stars and legends of the game join forces to create
                        a collection of unique varsity jackets
                    image_uri:
                      format: uri
                      description: Cached image URL
                      type: string
                      example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                    image_thumbnail_uri:
                      format: uri
                      description: Cached image URL
                      type: string
                      example: https://ipfs.io/ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                    image_canonical_uri:
                      format: uri
                      description: Original image URL
                      type: string
                      example: ipfs://ipfs/QmZMqhh2ztwuZ3Y8PyEp2z5auyH3TCm3nnr5ZfjjgDjd5q/12199.png
                    tx_id:
                      description: Transaction ID of the contract deployment
                      type: string
                      example: "0x5642ca7d68976b6b2a2055689d9a57de26d67f0dd8b016d1b0d94cb634454cdd"
                    sender_address:
                      description: Deployer address
                      type: string
                      example: SPZA22A4D15RKH5G8XDGQ7BPC20Q5JNMH0VQKSR6
  /metadata/v1/:
    get:
      operationId: getApiStatus
      summary: API Status
      tags:
        - Status
      description: Displays the status of the API
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                title: Api Status Response
                type: object
                required:
                  - server_version
                  - status
                  - chain_tip
                properties:
                  server_version:
                    type: string
                    example: token-metadata-api v0.0.1 (master:a1b2c3)
                  status:
                    type: string
                    example: ready
                  chain_tip:
                    anyOf:
                      - type: object
                        required:
                          - block_height
                          - index_block_hash
                        properties:
                          block_height:
                            examples:
                              - 163541
                            type: integer
                          index_block_hash:
                            examples:
                              - "0x1234567890abcdef1234567890abcdef1234567890ab\
                                cdef"
                            type: string
                      - type: "null"
servers:
  - url: https://api.hiro.so/
    description: mainnet
  - url: https://api.testnet.hiro.so/
    description: testnet
tags:
  - name: Tokens
    description: Token metadata endpoints
  - name: Status
    description: Service status endpoints
externalDocs:
  url: https://github.com/hirosystems/token-metadata-api
  description: Source Repository