openapi: 3.0.0
info:
  title: token metadata service
  description: |
    Implemented by token registries for the purpose of serving metadata about
    their tokens and the standards supported by the registry.
  version: 1.2.0
paths:
  /registry/metadata/v1/info:
    get:
      summary: "GET /registry/metadata/v1/info"
      operationId: getRegistryInfo
      description: |
        Get information about the registry.
        The response includes the standards supported by the registry.
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRegistryInfoResponse'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /registry/metadata/v1/instruments:
    get:
      summary: "GET /registry/metadata/v1/instruments"
      operationId: listInstruments
      description: List all instruments managed by this instrument admin.
      parameters:
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 25
          description: Number of instruments per page.
        - name: pageToken
          in: query
          required: false
          schema:
            type: string
          description: The `nextPageToken` received from the response for the previous page.
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInstrumentsResponse'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /registry/metadata/v1/instruments/{instrumentId}:
    get:
      summary: "GET /registry/metadata/v1/instruments/:instrumentId"
      operationId: getInstrument
      description: Retrieve an instrument's metadata.
      parameters:
        - name: instrumentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instrument'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '400':
      description: bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '404':
      description: not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '409':
      description: conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    GetRegistryInfoResponse:
      type: object
      properties:
        adminId:
          description: The Daml party representing the registry app
          type: string
        supportedApis:
          description: The token standard APIs supported by the registry. Note that this only includes the registry-wide APIs. Use the instrument lookup endpoints to see which APIs are supported for a given instrument
          $ref: '#/components/schemas/SupportedApis'
      required:
        - adminId
        - supportedApis
    Instrument:
      type: object
      properties:
        id:
          description: The unique identifier assigned by the admin to the instrument.
          type: string
        name:
          description: The display name for the instrument recommended by the instrument admin. This is not necessarily unique.
          type: string
        symbol:
          description: The symbol for the instrument recommended by the instrument admin. This is not necessarily unique.
          type: string
        totalSupply:
          description: Decimal encoded current total supply of the instrument.
          type: string
        totalSupplyAsOf:
          description: The timestamp when the total supply was last computed.
          type: string
          format: date-time
        decimals:
          description: |
            The number of decimal places used by the instrument.

            Must be a number between 0 and 10, as the Daml interfaces represent holding amounts as
            `Decimal` values, which use 10 decimal places and are precise for 38 digits.
            Setting this to 0 means that the instrument can only be held in whole units.

            This number SHOULD be used for display purposes in a wallet to decide how many
            decimal places to show and accept when displaying or entering amounts.
          type: integer
          format: int8
          default: 10
        paused:
          description: |
            Indicates whether the instrument is currently paused. A paused instrument cannot be
            transferred or allocated.
          type: boolean
          default: false
        pauseInfo:
          $ref: '#/components/schemas/PauseInfo'
        supportedApis:
          $ref: '#/components/schemas/SupportedApis'
        showAccountInputFields:
          description: |
            Informs wallets whether the instrument supports non-basic accounts
            and the wallet should thus show input fields for both the account
            provider and the account id in input forms for transfers and allocations.

            Note that wallets should always show non-null account providers and
            account ids when displaying transfers and allocations.

            This property is deprecated in favor of the more fine-grained
            `accountInputFieldsToShow` property.
          type: boolean
          default: false
          deprecated: true
        accountInputFieldsToShow:
          description: |
            Fine-grained control for account input field display in wallets.

            If set, then wallets should only display the specified input
            field(s) in transfer and allocation input forms
            *independently* of the `showAccountInputFields` property.

            Note that wallets should always show non-null account providers and
            account ids when displaying transfers and allocations.
          $ref: '#/components/schemas/AccountInputFieldsToShow'
      required:
        - id
        - name
        - symbol
        - decimals
        - supportedApis
    ListInstrumentsResponse:
      type: object
      properties:
        instruments:
          type: array
          items:
            $ref: '#/components/schemas/Instrument'
        nextPageToken:
          type: string
          description: The token for the next page of results, to be used as the lastInstrumentId for the next page.
      required:
        - instruments
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    SupportedApis:
      description: |
        Map from token standard API name to the minor version of the API supported, e.g.,
        splice-api-token-metadata-v1 -> 1 where the `1` corresponds to the minor version.
      type: object
      additionalProperties:
        type: integer
        format: int32
    PauseInfo:
      description: |
        Additional information about the instrument pause state.
      type: object
      properties:
        reason:
          description: |
            Why the instrument is paused.
          type: string
        until:
          description: |
            Timestamp (exclusive) until which the instrument is paused, if known.
          type: string
          format: date-time
    AccountInputFieldsToShow:
      description: |
        Which account input field(s) wallets should show in forms.
      type: array
      items:
        $ref: '#/components/schemas/AccountInputFieldToShow'
      uniqueItems: true
    AccountInputFieldToShow:
      description: |
        Which single account input field wallets should show in forms.
      type: string
      enum:
        - provider
        - accountId