openapi: 3.2.0
info:
  description: API for Aeternity Middleware
  title: Aeternity Middleware Aex9 API
  version: 1.108.2
servers:
- url: https://mainnet.aeternity.io/mdw/v3
  description: Mainnet middleware
- url: https://testnet.aeternity.io/mdw/v3
  description: Testnet middleware
tags:
- name: Aex9
paths:
  /aex9:
    get:
      deprecated: false
      description: Get AEX9 tokens sorted by creation time, name or symbol.
      operationId: GetSortedAex9Tokens
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/DirectionParam'
      - description: meta info field used on sorting
        in: query
        name: by
        required: false
        schema:
          type: string
          enum:
          - creation
          - name
          - symbol
      - description: Sorts by name or symbol prefix, this is decided by the 'by' field. If it's name, it will sort by name prefix, if it's symbol, it will sort by symbol prefix.
        in: query
        name: prefix
        required: false
        schema:
          type: string
          example: AA
      - description: Gets AEX9 tokens with exact name or symbol, this is decided by the 'by' field. If it's name, it will get tokens with exact name, if it's symbol, it will get tokens with exact symbol.
        in: query
        name: exact
        required: false
        schema:
          type: string
          example: AA
      responses:
        '200':
          description: Returns paginated AEX-9 tokens
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Aex9Response'
                - $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Aex9
      summary: Get sorted aex9 tokens
      x-summary-source: derived
  /aex9/count:
    get:
      deprecated: false
      description: Get AEX9 tokens count.
      operationId: GetAex9TokensCount
      responses:
        '200':
          description: Returns the number of AEX9 contracts created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: integer
      tags:
      - Aex9
      summary: Get aex9 tokens count
      x-summary-source: derived
  /aex9/{contractId}/balances:
    get:
      deprecated: false
      description: Get AEX9 balances on a contract.
      operationId: GetAex9ContractBalances
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/DirectionParam'
      - description: Contract id
        in: path
        name: contractId
        required: true
        schema:
          $ref: '#/components/schemas/ContractAddress'
      - description: Order by
        in: query
        name: by
        required: false
        schema:
          type: string
          example: amount
      - description: Block hash
        in: query
        name: block_hash
        required: false
        schema:
          $ref: '#/components/schemas/MicroBlockHash'
      responses:
        '200':
          description: Returns paginated contract balances
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Aex9ContractBalanceResponse'
                - $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Aex9
      summary: Get aex9 contract balances
      x-summary-source: derived
  /aex9/{contractId}/balances/{accountId}:
    get:
      deprecated: false
      description: Get AEX9 balance for an account on a contract.
      operationId: GetAex9ContractAccountBalance
      parameters:
      - description: Contract id
        in: path
        name: contractId
        required: true
        schema:
          $ref: '#/components/schemas/ContractAddress'
      - description: Account id
        in: path
        name: accountId
        required: true
        schema:
          $ref: '#/components/schemas/AccountAddress'
      - description: Block hash
        in: query
        name: hash
        required: false
        schema:
          $ref: '#/components/schemas/MicroBlockHash'
      responses:
        '200':
          description: Returns a the balance of an account on a contract
          content:
            application/json:
              schema:
                type: object
                required:
                - account
                - amount
                - contract
                properties:
                  account:
                    description: The account present on a AEX9
                    $ref: '#/components/schemas/AccountAddress'
                  amount:
                    description: The amount of AEX9 token
                    type: integer
                    example: 4050000000000
                  contract:
                    description: The contract id of given token
                    $ref: '#/components/schemas/ContractAddress'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Aex9
      summary: Get aex9 contract account balance
      x-summary-source: derived
  /aex9/{contractId}/balances/{accountId}/history:
    get:
      deprecated: false
      description: Get AEX9 account balance on a contract throughout all heights when changed.
      operationId: GetAex9ContractAccountBalanceHistory
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ScopeParam'
      - $ref: '#/components/parameters/DirectionParam'
      - description: Contract id
        in: path
        name: contractId
        required: true
        schema:
          $ref: '#/components/schemas/ContractAddress'
      - description: Account id
        in: path
        name: accountId
        required: true
        schema:
          $ref: '#/components/schemas/AccountAddress'
      responses:
        '200':
          description: Account balance history on a token contract
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        required:
                        - account
                        - amount
                        - contract
                        - height
                        properties:
                          account:
                            description: The account present on a AEX9
                            $ref: '#/components/schemas/AccountAddress'
                          amount:
                            description: The amount of AEX9 token
                            type: integer
                            example: 4050000000000
                          contract:
                            description: The contract id of given token
                            $ref: '#/components/schemas/ContractAddress'
                          height:
                            description: The block height, indicating a state of a balance for that block height
                            type: integer
                            example: 618127
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Aex9
      summary: Get aex9 contract account balance history
      x-summary-source: derived
  /aex9/{id}:
    get:
      deprecated: false
      description: Get AEX9 creation and meta_info information by contract id.
      operationId: GetAex9ByContract
      parameters:
      - description: The contract id
        in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/ContractAddress'
      responses:
        '200':
          description: Returns AEX-9 information by contract id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Aex9Response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Aex9
      summary: Get aex9 by contract
      x-summary-source: derived
components:
  schemas:
    TransactionHash:
      description: Transaction hash
      type: string
      example: th_2Zfo2ALfRkKQxEaUj3HhcUGyMrTqYpDMgr2u15fPanYD1d55kz
      pattern: ^th_\w{38,50}$
    Aex9ContractBalanceResponse:
      description: Response Schema for AEX9 contract balances responses
      example:
        account_id: ak_2MHJv6JcdcfpNvu4wRDZXWzq8QSxGbhUfhMLR7vUPzRFYsDFw6
        amount: 4050000000000
        contract_id: ct_RDRJC5EySx4TcLtGRWYrXfNgyWzEDzssThJYPd9kdLeS5ECaA
        block_hash: kh_bkyFuxj3W9yY8Tmuiq3KSCVHaTP3vMzHt4pZ6y1QcQEzyAf5i
        height: 618127
        last_tx_hash: th_KTTTudTgSAZrHJQVwW4AF6XD1ksQbpyHXWfgmL2kSGvNk14CU,
        last_log_idx: 1
      properties:
        account_id:
          description: The wallet pubkey
          $ref: '#/components/schemas/AccountAddress'
        amount:
          description: The balance amount
          type: integer
        block_hash:
          description: The block hash, indicating a state of a balance for that block
          type: integer
        contract_id:
          description: The contract id of given token
          type: integer
        height:
          description: The block height, indicating a state of a balance for that block height
          type: integer
        last_tx_hash:
          description: The hash of the last transaction that changed the balance
          $ref: '#/components/schemas/TransactionHash'
        last_log_idx:
          description: The index of the event log that changed the balance
          type: integer
      required:
      - account_id
      - amount
      - block_hash
      - contract_id
      - height
      - last_tx_hash
      - last_log_idx
      title: Response for AEX-9 contract balances
      type: object
    MicroBlockHash:
      description: Micro block hash
      type: string
      example: mh_2Zfo2ALfRkKQxEaUj3HhcUGyMrTqYpDMgr2u15fPanYD1d55kz
      pattern: ^mh_\w{38,50}$
    PaginatedResponse:
      type: object
      properties:
        next:
          type:
          - string
          - 'null'
          example: /blocks?cursor=123
        prev:
          type:
          - string
          - 'null'
          example: /blocks?cursor=234
      required:
      - next
      - prev
    Aex9Response:
      description: Response Schema for AEX9 contract
      example:
        contract_id: ct_2TZsPKT5wyahqFrzp8YX7DfXQapQ4Qk65yn3sHbifU9Db9hoav
        contract_tx_hash: th_rbFNrRDpn6finytCEmHAExtBnRxt14yckvuCWRmXxsRpypHxt
        initial_supply: 1e+28
        event_supply: 0
        decimals: 18
        extensions:
        - mintable
        - burnable
        holders: 12
        name: testnetAE
        symbol: TTAE
        invalid: false
      properties:
        contract_id:
          description: Id of the contract of the AEX9 tokens
          $ref: '#/components/schemas/ContractAddress'
        contract_tx_hash:
          description: Transaction hash of the contract creation
          $ref: '#/components/schemas/TransactionHash'
        initial_supply:
          description: Token supply right after contract's creation
          type: integer
        event_supply:
          description: Token supply updated on event basis (Mint, Burn, Swap)
          type: integer
        decimals:
          description: The number of decimals for AEX9 token
          type: integer
        extensions:
          description: Extensions implemented by the contract
          type: array
          items:
            type: string
        holders:
          description: Count of accounts having balance (nil when contract is not complaint)
          type: integer
        name:
          description: Name of AEX9 token
          type: string
        symbol:
          description: Symbol of AEX9 token
          type: string
        invalid:
          description: True if the contract is invalid
          type: boolean
      required:
      - contract_id
      - contract_tx_hash
      - decimals
      - symbol
      - name
      - holders
      - initial_supply
      - event_supply
      - invalid
      title: Aex9Response
      type: object
    ErrorResponse:
      description: Error response from the API
      type: object
      example:
        error: 'invalid id: th_2Twp3pJeVuwQ7cMSdPQRfpAUWwdMiwx6coVMpRaNSuzFRnDZF'
      properties:
        error:
          description: The message of the error raised
          type: string
      required:
      - error
      title: Error response
    AccountAddress:
      description: Account address
      type: string
      example: ak_psy8tRXPzGxh6975H7K6XQcMFVsdrxJMt7YkzMY8oUTevutzw
      pattern: ^ak_\w{38,50}$
    ContractAddress:
      description: Contract address
      type: string
      example: ct_2t7TnocFw7oCYSS7g2yGutZMpGEJta6dq2DTX38SmuqmwtN6Ch
      pattern: ^ct_\w{38,50}$
  parameters:
    DirectionParam:
      in: query
      name: direction
      description: Sorts results in forwards or backwards direction
      schema:
        type: string
        enum:
        - forward
        - backward
    ScopeParam:
      in: query
      name: scope
      description: Scopes results in a generation range
      schema:
        type: string
        pattern: (gen):\d+(-\d+)?
    LimitParam:
      in: query
      name: limit
      description: Limit paginated resources (max 100)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10