swagger.yaml

openapi: 3.0.0
info:
  title: Cardano Wallet Backend API
  version: 2021.4.28
  license:
    name: Apache-2.0
    url: https://raw.githubusercontent.com/input-output-hk/cardano-wallet/master/LICENSE
  description: |
    <p align="right"><img style="position: relative; top: -10em; margin-bottom: -12em;" width="20%" src="https://cardanodocs.com/img/cardano.png"></img></p>
externalDocs:
  description: Need more? Click here to access our API guide and walkthrough.
  url: https://github.com/input-output-hk/cardano-wallet/wiki

servers:
  - url: https://localhost:8090/v2/

#############################################################################
#                                                                           #
#                                 FIELDS                                    #
#                                                                           #
#############################################################################

x-date: &date
  type: string
  format: iso-8601-date-and-time
  example: 2019-02-27T14:46:45Z

x-slotNumber: &slotNumber
  type: integer
  description: The zero-based slot index within an epoch.
  minimum: 0
  example: 1337

x-stakePoolsNumber: &stakePoolsNumber
  type: integer
  minimum: 0
  example: 100

x-numberOfSeconds: &numberOfSeconds
  type: object
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: number
      minimum: 0.0
      example: 10.0
    unit:
      type: string
      enum: ["second"]

x-epochNumber: &epochNumber
  type: integer
  description: An epoch is a time period which is divided into slots.
  minimum: 0
  example: 14

x-epochInfo: &epochInfo
  type: object
  required:
    - epoch_number
    - epoch_start_time
  properties:
    epoch_number: *epochNumber
    epoch_start_time: *date

x-blockId: &blockId
  description: The hash of genesis block
  type: string
  format: hex
  maxLength: 64
  minLength: 64
  example: 3c07030e36bfffe67e2e2ec09e5293d384637cd2f004356ef320f3fe6c52041a

x-absoluteSlot: &absoluteSlot
  type: integer
  description: The 0-based slot index starting from genesis of the blockchain.
  minimum: 0
  example: 8086

x-numberOfSlots: &numberOfSlots
  type: object
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: integer
      minimum: 0
      example: 42000
    unit:
      type: string
      enum: ["slot"]

x-numberOfBlocks: &numberOfBlocks
  type: object
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: integer
      minimum: 0
      example: 1337
    unit:
      type: string
      enum:
        - block
      example: "block"

x-blockReference: &blockReference
  description: A reference to a particular time slot, and the block height at that point.
  type: object
  required:
    - absolute_slot_number
    - slot_number
    - epoch_number
    - time
    - height
  properties:
    absolute_slot_number: *absoluteSlot
    slot_number: *slotNumber
    epoch_number: *epochNumber
    time: *date
    height: *numberOfBlocks

x-slotId: &slotId
  description: A slot identifier, given by epoch number and local slot index.
  type: object
  required:
    - epoch_number
    - slot_number
  properties:
    epoch_number: *epochNumber
    slot_number: *slotNumber

x-slotReference: &slotReference
  description: A reference to a particular time slot.
  type: object
  required:
    - absolute_slot_number
    - slot_number
    - epoch_number
    - time
  properties:
    absolute_slot_number: *absoluteSlot
    epoch_number: *epochNumber
    slot_number: *slotNumber
    time: *date

x-genesisBlock: &genesisBlock
  description: A reference to a particular block.
  type: object
  required:
    - slot_number
    - epoch_number
  properties:
    slot_number:
      <<: *slotNumber
      maximum: 0
      example: 0
    epoch_number:
      <<: *epochNumber
      maximum: 0
      example: 0

x-percentage: &percentage
  type: object
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: number
      minimum: 0
      maximum: 100
      example: 42
    unit:
      type: string
      enum:
        - percent

x-microseconds: &microseconds
  type: object
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: number
      example: 42
    unit:
      type: string
      enum:
        - microsecond

x-syncProgress: &syncProgress
  type: object
  required:
    - status
  properties:
    status:
      type: string
      enum:
        - ready
        - syncing
        - not_responding
    progress:
      <<: *percentage
      description: |
        <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
        <strong>if:</strong> status == syncing
        </span><br/>
  example:
    status: ready

x-syncClockProgress: &syncClockProgress
  type: object
  required:
    - status
  properties:
    status:
      type: string
      enum:
        - unavailable
        - pending
        - available
    offset:
      <<: *microseconds
      description: |
        <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
        <strong>if:</strong> status == available
        </span><br/>
  example:
    status: pending

x-amount: &amount
  description: Coins, in Lovelace. Only relates to 'Ada'. Refer to `assets` for multi-assets wallets instead.
  type: object
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: integer
      minimum: 0
      example: 42000000
    unit:
      type: string
      enum:
        - lovelace

x-stakeAddress: &stakeAddress
  type: string
  format: bech32
  example: stake1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2x

x-addressId: &addressId
  type: string
  format: base58|bech32
  example: addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g

x-addressState: &addressState
  type: string
  enum:
    - used
    - unused

x-stakePoolId: &stakePoolId
  type: string
  format: hex|bech32
  example: pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm
  description: A unique identifier for the pool.

x-walletAccountPubkey: &walletAccountPubkey
  description: An extended account public key (public key + chain code)
  type: string
  format: hex
  minLength: 128
  maxLength: 128
  example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1

x-cosigner: &cosigner
  type: string
  pattern: "^(cosigner#)[0-9]+$"

x-cosigners: &cosigners
  description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#"
  type: object
  additionalProperties: *walletAccountPubkey
  # Note: propertyNames pattern not supported in current OpenAPI version.
  # propertyNames:
  #   pattern: '^(cosigner#)[0-9]+$'
  example:
    { "cosigner#0": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1"
    , "cosigner#3": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db2" }

x-walletId: &walletId
  description: A unique identifier for the wallet
  type: string
  format: hex
  maxLength: 40
  minLength: 40
  example: 2512a00e9653fe49a44a5886202e24d77eeb998f

x-walletDiscovery: &walletDiscovery
  description: Mechanism used for discovering addresses.
  type: string
  enum:
    - random
    - sequential
  example: sequential

x-walletName: &walletName
  type: string
  maxLength: 255
  minLength: 1
  example: Alan's Wallet

x-poolMetadataSource: &poolMetadataSource
  description: |
    Pool metadata source. This sets the metadata fetching strategy.

    Possible values are
      * none -> no fetching
      * direct -> direct fetching
      * uri -> use SMASH server
  type: string
  pattern: '^(none|direct|https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?)$'
  example: https://smash.cardano-mainnet.iohk.io/

x-credentialPubKey: &credentialPubKey
  description: A public key (public key without chain code) for credential - 32 bytes
  type: string
  format: bech32
  pattern: "^((addr_vk)|(stake_vk))1[0-9a-z]*$"
  example:
    - stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d
    - addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2

x-validationLevel: &validationLevel
  description: |
    Script validation level. Required validation sifts off scripts that would not
    be accepted by the ledger. Recommended level filters out scripts that do not pass
    required validation and additionally when:
      * 'all' is non-empty
      * there are redundant timelocks in a given level
      * there are no duplicated verification keys in a given level
      * 'at_least' coeffcient is positive
      * 'all', 'any' are non-empty and `'at_least' has no less elements in the list
         than the coeffcient after timelocks are filtered out.

  type: string
  enum:
    - required
    - recommended

x-anyAddress: &anyAddress
  description: A Shelley address representing either enterprise, reward account or delegating address
  type: string
  format: bech32
  pattern: "^((addr)|(stake)|(addr_test)|(stake_test))1[0-9a-z]*$"
  example:
    - stake17xt2z3pa7etaxp7jurdg0m8jhsmtp4r2z56pd3a5q3jhxycdxzmx9
    - addr1wy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5taclc6dnd8e
    - addr1xy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5tacluk59zrmajh6vra9cx6slk090pkkr2x59f5zmrmgpr9wvfs37hjk4

x-ScriptValue: &ScriptValue
  oneOf:
    - title: Key Hash
      description: Leaf value for a script designating a required verification key hash.
      type: string
      format: bech32
      pattern: "^(script_vkh)1[0-9a-z]*$"

    - title: All
      type: object
      required:
        - all
      properties:
        all:
          description: Script primitive for which all signing keys corresponding to all list elements' verification keys are expected to make the script valid.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ScriptValue"

    - title: Any
      type: object
      required:
        - any
      properties:
        any:
          description: Script primitive for which a signing key corresponding to any of the list elements' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ScriptValue"

    - title: Some
      type: object
      required:
        - some
      properties:
        some:
          description: Script primitive for which at least a given number of signing keys corresponding to the list elements' verification keys are expected to make the script valid.
          type: object
          required:
            - at_least
            - from
          properties:
            at_least:
              type: integer
              minimum: 1
              maximum: 255
            from:
              type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/ScriptValue"

    - title: Active from slot
      type: object
      required:
        - active_from
      properties:
        active_from:
          description: Transaction is only valid starting at the specified slot number (`≥ active_from`).
          type: integer
          minimum: 0

    - title: Active until slot
      type: object
      required:
        - active_until
      properties:
        active_until:
          description: Transaction is only valid before the specified slot number (`< active_until`).
          type: integer
          minimum: 0

x-script: &script
  <<: *ScriptValue

x-ScriptTemplateValue: &ScriptTemplateValue
  oneOf:
    - title: Cosigner
      description: Leaf value for a script designating a cosigner co-sharing the script.
      type: string
      pattern: "^(cosigner#)[0-9]*$"

    - title: All
      type: object
      required:
        - all
      properties:
        all:
          description: Script primitive for which all signing keys corresponding to all list cosigners' verification keys are expected to make the script valid.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ScriptTemplateValue"

    - title: Any
      type: object
      required:
        - any
      properties:
        any:
          description: Script primitive for which a signing key corresponding to any of the list cosigners' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ScriptTemplateValue"

    - title: Some
      type: object
      required:
        - some
      properties:
        some:
          description: Script primitive for which at least a given number of signing keys corresponding to the list cosigners' verification keys are expected to make the script valid.
          type: object
          required:
            - at_least
            - from
          properties:
            at_least:
              type: integer
              minimum: 1
              maximum: 255
            from:
              type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/ScriptTemplateValue"

    - title: Active from slot
      type: object
      required:
        - active_from
      properties:
        active_from:
          description: Transaction is only valid starting at the specified slot number (`≥ active_from`).
          type: integer
          minimum: 0

    - title: Active until slot
      type: object
      required:
        - active_until
      properties:
        active_until:
          description: Transaction is only valid before the specified slot number (`< active_until`).
          type: integer
          minimum: 0

x-scriptTemplate: &scriptTemplate
  type: object
  required:
    - cosigners
    - template
  properties:
    cosigners: *cosigners
    template: *ScriptTemplateValue

x-CredentialValue: &CredentialValue
  nullable: false
  oneOf:
    - <<: *credentialPubKey
      title: public key
    - <<: *script
      title: script
  example:
    any:
    - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt36ms

    - all:
      - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt36ms
      - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt37ms

    - any:
      - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt36ms
      - all:
        - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt36ms
        - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt37ms

    - some:
        at_least: 2
        from:
        - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt37ms
        - script_vkh18srsxr3khll7vl3w9mqfu55n6wzxxlxj7qzr2mhnyreluzt38ms

x-settings: &settings
  description: Settings
  type: object
  required:
    - pool_metadata_source
  properties:
    pool_metadata_source:
      <<: *poolMetadataSource
      description: |
        Select stake pool metadata fetching strategy:
          - `none` - metadata is not fetched at all,
          - `direct` - metadata is fetched directly URLs registered on chain,
          - `uri` - metadata is fetched from an external Stake-Pool Metadata Aggregation Server (SMASH)

        After update existing metadata will be dropped forcing it to re-sync automatically with the new setting.

x-assetName: &assetName
  type: string
  description: |
    The asset on-chain type which acts as a sub-identifier within a
    policy. Although we call it "asset name", the value needn't be
    text, and it could even be empty.

    For policies with a single fungible asset item, asset name is
    typically an empty string.

    This value can be up to 32 bytes of arbitrary data (which is 64
    hexadecimal digits).
  format: hex
  maxLength: 64
  example: ""

x-assetPolicyId: &assetPolicyId
  type: string
  description: |
    A unique identifier of the asset's monetary policy. The policy
    controls how assets of this kind are created and destroyed.

    The contents are the blake2b-224 hash of the monetary policy
    script, encoded in hexadecimal.
  format: hex
  minLength: 56
  maxLength: 56
  example: 65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b

x-assetFingerprint: &assetFingerprint
  type: string
  description: |
    A user-facing short fingerprint which combines the `policy_id` and `asset_name`
    to allow for an easier human comparison of assets. Note that it is generally
    **not okay** to use this fingerprint as a unique identifier for it is not collision
    resistant. Yet within the context of a single wallet, it makes for a (rather)
    short user-facing comparison mean.
  pattern: "^(asset)1[0-9a-z]*$"
  maxLength: 44
  minLength: 44
  example: asset1rjklcrnsdzqp65wjgrg55sy9723kw09mlgvlc3

x-assetMetadataName: &assetMetadataName
  type: string
  maxLength: 50
  minLength: 1
  description: |
    A human-readable name for the asset, intended for display in user
    interfaces.
  example: SwaggerCoin

x-assetMetadataTicker: &assetMetadataTicker
  type: string
  maxLength: 5
  minLength: 2
  description: |
    An optional human-readable very short name or acronym for the
    asset, intended for display in user interfaces. If `ticker` is not
    present, then `name` will be used, but it might be truncated to
    fit within the available space.
  example: SWAG

x-assetMetadataDescription: &assetMetadataDescription
  description: |
    A human-readable description for the asset. Good for display in
    user interfaces.
  type: string
  maxLength: 500

x-assetMetadataUnit: &assetMetadataUnit
  type: object
  description: |
    Defines a larger unit for the asset, in the same way Ada is the
    larger unit of Lovelace.
  required:
    - decimals
    - name
  additionalProperties: false
  properties:
    decimals:
      type: integer
      description: |
        The number of digits after the decimal point.
      minimum: 1
      maximum: 19
    name:
      type: string
      minLength: 1
      maxLength: 30
      description: |
        The human-readable name for the larger unit of the asset. Used
        for display in user interfaces.
  example:
    name: API
    decimals: 3

x-assetMetadataUrl: &assetMetadataUrl
  description: |
    A URL to the policy's owner(s) or the entity website in charge of the asset.
  type: string
  format: uri
  pattern: "^https://.+"
  maxLength: 250

x-assetMetadataLogo: &assetMetadataLogo
  description: |
    A base64-encoded `image/png` for displaying the asset. The end image can be expected
    to be smaller than 64KB.
  type: string
  format: base64
  maxLength: 87400

x-assetMetadata: &assetMetadata
  title: Native Assets Metadata
  description: |
    In the Mary era of Cardano, UTxO may contain native assets. These
    assets are represented on-chain by opaque identifiers which are
    meaningless to end-users. Therefore, user-facing metadata
    regarding each token must be stored off-chain, in a metadata
    registry.

    Token creators may publish metadata into the registry and client
    applications can consume these metadata for display to end
    users. This will work in a similar way to how it is done for stake
    pool metadata.
  type: object
  additionalProperties: false
  required:
    - name
    - description
  properties:
    name: *assetMetadataName
    description: *assetMetadataDescription
    ticker: *assetMetadataTicker
    unit: *assetMetadataUnit
    url: *assetMetadataUrl
    logo: *assetMetadataLogo

x-walletMnemonicSentence: &walletMnemonicSentence
  description: A list of mnemonic words
  type: array
  minItems: 15
  maxItems: 24
  items:
    type: string
    format: bip-0039-mnemonic-word{english}
  example: ["squirrel", "material", "silly", "twice", "direct", "slush", "pistol", "razor", "become", "junk", "kingdom", "flee", "squirrel", "silly", "twice"]

x-walletSecondFactor: &walletSecondFactor
  description: An optional passphrase used to encrypt the mnemonic sentence.
  type: array
  minItems: 9
  maxItems: 12
  items:
    type: string
    format: bip-0039-mnemonic-word{english}
  example: ["squirrel", "material", "silly", "twice", "direct", "slush", "pistol", "razor", "become"]

x-walletPassphrase: &walletPassphrase
  description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds)
  type: string
  minLength: 10
  maxLength: 255
  example: Secure Passphrase

x-keyExtended: &keyExtended
  description: Determines whether extended (with chain code) or normal (without chain code) key is requested
  type: boolean

x-lenientPassphrase: &lenientPassphrase
  description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds)
  type: string
  minLength: 0
  maxLength: 255
  example: Secure Passphrase

x-walletPassphraseHash: &walletPassphraseHash
  description: |
    A hash of master passphrase. The hash should be an output of a Scrypt function with the following parameters:
    - logN = 14
    - r = 8
    - p = 1
  type: string
  format: hex
  example: 31347c387c317c574342652b796362417576356c2b4258676a344a314c6343675375414c2f5653393661364e576a2b7550766655513d3d7c2f376738486c59723174734e394f6e4e753253302b6a65515a6b5437316b45414941366a515867386539493d

x-walletEncryptedRootPrivateKey: &walletEncryptedRootPrivateKey
  description: |
    A root private key, encrypted using a given passphrase. The underlying key should contain:
    - A private key
    - A chain code
    - A public key
  type: string
  format: hex
  minLength: 256
  maxLength: 256

x-walletAddressPoolGap: &walletAddressPoolGap
  description: |
    Number of consecutive unused addresses allowed.

    **IMPORTANT DISCLAIMER:** Using values other than `20` automatically makes your wallet invalid with regards to BIP-44 address discovery. It means that you **will not** be able to fully restore
    your wallet in a different software which is strictly following BIP-44.

    Beside, using large gaps is **not recommended** as it may induce important performance degradations. Use at your own risks.

  type: integer
  minimum: 10
  maximum: 100000
  example: 20
  default: 20

x-walletState: &walletState
  <<: *syncProgress
  description: Whether a wallet is ready to use or still syncing

x-walletBalance: &walletBalance
  description: Wallet current Ada balance(s).
  type: object
  required:
    - available
    - reward
    - total
  properties:
    available:
      <<: *amount
      description: Available Ada UTxO balance (funds that can be spent without condition).
    reward:
      <<: *amount
      description: The Ada balance of the reward account for this wallet.
    total:
      <<: *amount
      description: Total Ada balance (available balance plus pending change and reward balance).

x-assetQuantity: &assetQuantity
  type: integer
  description: |
    Number of assets for the given `policy_id` and `asset_name`.
  minimum: 0

x-walletAsset: &walletAsset
  description: |
    An asset on the Cardano blockchain. An asset is uniquely identified by
    its `policy_id` and `asset_name` (together, these form the _asset id_).

    Two assets with the same `asset_name` and `policy_id` are
    interchangeable. Yet, different assets with a same `policy_id` but
    different `asset_name` are treated as separate assets, as are two
    assets with the same `asset_name` but different `policy_id`.
  type: object
  required:
    - policy_id
    - asset_name
    - quantity
  properties:
    policy_id: *assetPolicyId
    asset_name: *assetName
    quantity: *assetQuantity

x-walletAssets: &walletAssets
  description: A flat list of assets.
  type: array
  items: *walletAsset

x-assetMint: &assetMint
  type: object
  required:
    - policy_id
    - asset_name
    - quantity
  properties:
    policy_id: *assetPolicyId
    asset_name: *assetName
    fingerprint: *assetFingerprint
    quantity:
      type: integer
      description: |
        Positive values mean creation and negative values mean
        destruction.

x-walletAssetsBalance: &walletAssetsBalance
  description: |
    Current non-Ada asset holdings of the wallet.

    The amount of assets available to spend may be less than the total
    unspent assets due to transaction change amounts which are yet to
    be fully confirmed (pending).
  type: object
  required:
    - available
    - total
  properties:
    available:
      <<: *walletAssets
      description: |
        Available UTxO asset balances (funds that can be spent without
        condition).
    total:
      <<: *walletAssets
      description: |
        Total asset balances (available balances plus pending change balances).

x-byronWalletBalance: &byronWalletBalance
  description: Byron wallet's current balance(s)
  type: object
  required:
    - available
    - total
  properties:
    available:
      <<: *amount
      description: Available balance (funds that can be spent)
    total:
      <<: *amount
      description: Total balance (available balance plus pending change)

x-walletPassphraseInfo :: &walletPassphraseInfo
  description: Information about the wallet's passphrase
  type: object
  required:
    - last_updated_at
  properties:
    last_updated_at: *date

x-transactionId: &transactionId
  description: A unique identifier for this transaction
  type: string
  format: hex
  maxLength: 64
  minLength: 64
  example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1

x-transactionInsertedAt: &transactionInsertedAt
  description: |
    <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
    <strong>if:</strong> status == in_ledger
    </span><br/>
    Absolute time at which the transaction was inserted in a block.
  <<: *blockReference

x-transactionExpiresAt: &transactionExpiresAt
  description: |
    <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
    <strong>if:</strong> status == pending OR status == expired
    </span><br/>
    Absolute time and slot at which the pending transaction TTL (time to live) will lapse.
  <<: *slotReference

x-transactionPendingSince: &transactionPendingSince
  description: |
    <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
    <strong>if:</strong> status == pending
    </span><br/>
    The point in time at which a transaction became pending.
  <<: *blockReference

x-transactionDepth: &transactionDepth
  description: |
    <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
    <strong>if:</strong> status == in_ledger
    </span><br/>
    Current depth of the transaction in the local chain
  <<: *numberOfBlocks

x-transactionDirection: &transactionDirection
  type: string
  enum:
    - outgoing
    - incoming

x-addresses: &addresses
  description: A list of addresses
  type: array
  minItems: 1
  items: *addressId

x-transactionInputs: &transactionInputs
  description: |
    A list of transaction inputs.

    `assets` and `address` are always present for `outgoing`
    transactions but generally absent for `incoming`
    transactions. This information is present on the Cardano explorer,
    but is not tracked by the wallet.
  type: array
  minItems: 0
  items:
    type: object
    required:
      - id
      - index
    properties:
      address: *addressId
      amount: *amount
      assets: *walletAssets
      id: *transactionId
      index:
        type: integer
        minimum: 0

x-transactionOutputs: &transactionOutputs
  description: A list of target outputs
  type: array
  minItems: 0
  items:
    type: object
    required:
      - address
      - amount
    properties:
      address: *addressId
      amount: *amount
      assets: *walletAssets

x-delegationAction: &delegationAction
  description: |
    A delegation action.

    Pool id is only required for "join".
  type: object
  required:
    - action
  properties:
    action:
      type: string
      enum: ["quit", "join"]
    pool: *stakePoolId

x-rewardAccountPath: &rewardAccountPath
  type: array
  minItems: 5
  maxItems: 5
  items:
    type: string

x-certificate: &certificate
  description: |
    A delegation certificate

    Only for 'join_pool' the 'pool' property is required.
  type: object
  required:
    - certificate_type
    - reward_account_path
  properties:
    certificate_type:
      type: string
      enum: ["join_pool", "quit_pool", "register_reward_account"]
    pool:
      <<: *stakePoolId
    reward_account_path:
      <<: *rewardAccountPath

x-transactionRedemptionRequest: &transactionRedemptionRequest
  <<: *walletMnemonicSentence
  description: |
    When provided, attempts to withdraw rewards from the default stake address corresponding to the given mnemonic.

    Should the rewards be null or too small to be worth withdrawing (i.e. the cost of adding them into the transaction
    is more than their own intrinsic value), the server will reject the request with a `withdrawal_not_worth` error.

    withdrawal field    | reward balance | result
    ---                 | ---            | ---
    any recovery phrase | too small      | x Error 403 `withdrawal_not_worth`
    any recovery phrase | big enough     | ✓ withdrawal generated

x-transactionWithdrawalRequestSelf: &transactionWithdrawalRequestSelf
  type: string
  enum: ["self"]
  description: |
    When provided, instruments the server to automatically withdraw rewards from the source wallet when they are deemed
    sufficient (i.e. they contribute to the balance for at least as much as they cost).

    As a consequence, the resulting transaction may or may not have a withdrawal object. Summarizing:

    withdrawal field | reward balance | result
    ---              | ---            | ---
    `null`           | too small      | ✓ no withdrawals generated
    `null`           | big enough     | ✓ no withdrawals generated
    `"self"`         | too small      | ✓ no withdrawals generated
    `"self"`         | big enough     | ✓ withdrawal generated

x-transactionWithdrawals: &transactionWithdrawals
  description: A list of withdrawals from stake addresses.
  type: array
  minItems: 0
  items:
    type: object
    additionalProperties: false
    required:
      - stake_address
      - amount
    properties:
      stake_address: *stakeAddress
      amount: *amount

x-transactionMint: &transactionMint
  description: |
    <p>status: <strong>⚠ under development</strong></p>

    _This field is not implemented yet, and will always be empty._

    Assets minted (created) or unminted (destroyed)

    This amount contributes to the total transaction value.

    Positive values denote creation of assets and negative values
    denote the reverse.
  type: array
  minItems: 0
  items: *assetMint

x-derivationSegment: &derivationSegment
  description: |
    An individual segment within a derivation path.
    Indexes without `H` suffix are called `Soft`.
    Indexes with `H` suffix are called `Hardened`.
  type: string
  example: 1852H

x-derivationPath: &derivationPath
  description: A path for deriving a child key from a parent key.
  type: array
  minItems: 1
  items: *derivationSegment

x-transactionChange: &transactionChange
  description: A list of transaction change outputs.
  type: array
  minItems: 0
  items:
    type: object
    required:
      - address
      - amount
      - derivation_path
    properties:
      address: *addressId
      amount: *amount
      assets: *walletAssets
      derivation_path: *derivationPath

x-transactionResolvedInputs: &transactionResolvedInputs
  description: A list of transaction inputs
  type: array
  minItems: 1
  items:
    type: object
    required:
      - id
      - index
      - address
      - amount
      - derivation_path
    properties:
      address: *addressId
      amount: *amount
      assets: *walletAssets
      id: *transactionId
      derivation_path: *derivationPath
      index:
        type: integer
        minimum: 0

x-transactionResolvedWithdrawals: &transactionResolvedWithdrawals
  description: A list of withdrawals from stake addresses.
  type: array
  minItems: 0
  items:
    type: object
    additionalProperties: false
    required:
      - stake_address
      - derivation_path
      - amount
    properties:
      stake_address: *stakeAddress
      derivation_path: *derivationPath
      amount: *amount

x-signedTransactionBlob: &signedTransactionBlob
  description: Signed transaction message binary blob.
  type: string
  format: binary

x-transactionStatus: &transactionStatus
  description: |
    Current transaction status.

      ```
             *---------*          *-----------*
             |         |---------->  EXPIRED  |
             |         |  (ttl)   *-----------*
      -------> PENDING |
             |         <----------------*
             |         |                |
             *---------*            (rollback)
                  |                     |
             (in ledger)          *-----------*
                  |               |           |
                  *---------------> IN_LEDGER |
                                  |           |
                                  *-----------*
      ```
  type: string
  enum:
    - pending
    - in_ledger
    - expired

x-transactionSerializedMetadata: &transactionSerializedMetadata
  type: string
  format: base64
  description: Transaction metadata, serialized according to the expected on-chain binary format, base64-encoded.

x-transactionMetadata: &transactionMetadata
  description: |
    **⚠️ WARNING ⚠️**

    _Please note that metadata provided in a transaction will be
    stored on the blockchain forever. Make sure not to include any sensitive data,
    in particular personally identifiable information (PII)._

    Extra application data attached to the transaction.

    Cardano allows users and developers to embed their own
    authenticated metadata when submitting transactions. Metadata can
    be expressed as a JSON object with some restrictions:

    1. All top-level keys must be integers between `0` and `2^64 - 1`.

    2. Each metadata value is tagged with its type.

    3. Strings must be at most 64 bytes when UTF-8 encoded.

    4. Bytestrings are hex-encoded, with a maximum length of 64 bytes.

    Metadata aren't stored as JSON on the Cardano blockchain but are
    instead stored using a compact binary encoding (CBOR).

    The binary encoding of metadata values supports three simple types:

    * Integers in the range `-(2^64 - 1)` to `2^64 - 1`
    * Strings (UTF-8 encoded)
    * Bytestrings

    And two compound types:

    * Lists of metadata values
    * Mappings from metadata values to metadata values

    It is possible to transform any JSON object into this schema.

    However, if your application uses floating point values, they will
    need to be converted somehow, according to your
    requirements. Likewise for `null` or `bool` values. When reading
    metadata from chain, be aware that integers may exceed the
    javascript numeric range, and may need special "bigint" parsing.

  type: object
  nullable: true
  additionalProperties:
    $ref: "#/components/schemas/TransactionMetadataValue"
  # Note: propertyNames pattern not supported in current OpenAPI version.
  # propertyNames:
  #   pattern: '^[0-9]+$'
  example:
    0: { "string": "cardano" }
    1: { "int": 14 }
    2: { "bytes": "2512a00e9653fe49a44a5886202e24d77eeb998f" }
    3: { "list": [ { "int": 14 }, { "int": 42 }, { "string": "1337" } ] }
    4: { "map": [{ "k": { "string": "key" }, "v": { "string": "value" }}, { "k": { "int": 14 }, "v": { "int": 42 } }] }

x-transactionTTL: &transactionTTL
  description: |
    The TTL (time to live) is the time period in which the transaction
    will be accepted into node mempools.

    After the TTL has lapsed, the transaction is considered
    expired. At this point, nodes will give up on broadcasting the
    transaction, and the wallet will release the funds allocated to
    the transaction so they can be used for other payments.

    The TTL should be long enough that the transaction has time to be
    propagated through the network and confirmed, but short enough so
    that - in the event of failures - UTxO are returned to the wallet
    in a timely manner.

    The TTL value is given in seconds. It will be converted to a slot
    number internally.

    If the TTL is not provided for a payment, a reasonable default
    value will be used.

  <<: *numberOfSeconds

x-stakePoolApparentPerformance: &stakePoolApparentPerformance
  description: |
    Apparent performance of the stake pool over past epochs. This indicator is computed
    using data available to the server. In particular, the server can't reliably know the
    stake distribution of past epochs without being during those epochs. The performance
    are therefore an average measure that is more accurate for servers that are online
    often.

    The performance is a float with double-precision which is _typically_ within `0` and `1`:

      - `0` means that a pool is not performing well.
      - `1` means that a pool is performing _as expected_.
      - above `1` means the pool is performing beyond expectations.

    Pools that are lucky enough to win most of their slots early in the epoch will tend to look
    like they're over-performing for a while. Having a wallet regularly connected to the network
    would harmonize the performance and give better results.

  type: number
  minimum: 0
  example: 0.5053763440860215


x-stakePoolMetadata: &stakePoolMetadata
  description: |
    Information about the stake pool.
  type: object
  required:
    - ticker
    - name
    - homepage
  additionalProperties: false
  properties:
    ticker:
      type: string
      minLength: 3
      maxLength: 5
      example: IOHK
    name:
      type: string
      minLength: 1
      maxLength: 50
    description:
      type: string
      maxLength: 255
    homepage:
      type: string
      format: uri
      example: https://iohk.io

x-stakePoolRetirement: &stakePoolRetirement
  <<: *epochInfo
  description: |
      The epoch in which a stake pool retires.

      May be omitted if the wallet hasn't yet found a retirement certificate
      for this stake pool.

x-stakePoolPledge: &stakePoolPledge
  <<: *amount
  description: |
      Minimal stake amount that a stake pool is willing to honor.

      May be omitted if the wallet hasn't found the pool's registration cerificate yet.

x-stakePoolCost: &stakePoolCost
  <<: *amount
  description: |
      Estimated cost set by the pool operator when registering his pool.
      This fixed cost is taken from each reward earned by the pool before splitting rewards between stakeholders.

      May be omitted if the wallet hasn't found the pool's registration cerificate yet.

x-stakePoolMargin: &stakePoolMargin
  <<: *percentage
  description: |
      Variable margin on the total reward given to an operator before splitting rewards between stakeholders.

      May be omitted if the wallet hasn't found the pool's registration cerificate yet.

x-stakePoolSaturation: &stakePoolSaturation
  type: number
  minimum: 0
  description: |
    Saturation-level of the pool based on the desired number of pools aimed by the network.
    A value above `1` indicates that the pool is saturated.

    The `non_myopic_member_rewards` take oversaturation into account, as specified by the [specs](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec).

    The saturation is based on the live `relative_stake`. The saturation at the end of epoch e,
    will affect the rewards paid out at the end of epoch e+3.

  example: 0.74

x-non-myopic-member-rewards: &nonMyopicMemberRewards
  <<: *amount
  description: |
    The rewards the wallet can expect to receive at the end of an epoch, in the long term, if delegating to
    this pool.

    For more details, see the
    [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec)
    document.

x-stakePoolMetrics: &stakePoolMetrics
  type: object
  required:
    - relative_stake
    - non_myopic_member_rewards
    - produced_blocks
    - saturation
  properties:
    non_myopic_member_rewards: *nonMyopicMemberRewards
    relative_stake:
      <<: *percentage
      description: |
        The live pool stake relative to the *total* stake.

        For more details, see the section "Relative Stake: Active vs Total" in
        [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec).
    saturation: *stakePoolSaturation
    produced_blocks:
      <<: *numberOfBlocks
      description: Number of blocks produced by a given stake pool in its lifetime.

x-stakePoolFlag: &stakePoolFlag
  type: string
  enum:
  - delisted

x-stakePoolFlags: &stakePoolFlags
  type: array
  description: |
    Various flags applicable to stake pools. Possible flags:

    | flag     | description                                                                                                      |
    | ---      | ---                                                                                                              |
    | delisted | The pool is marked as delisted on a configured SMASH server; metadata for this pool have therefore been dropped. |
  items: *stakePoolFlag

x-networkInformationSyncProgress: &networkInformationSyncProgress
  <<: *syncProgress
  description: |
    Estimated synchronization progress of the node with the underlying network. Note that this may
    change quite arbitrarily as the node may switch to shorter or longer chain forks.

x-networkClockSyncProgress: &networkClockSyncProgress
  <<: *syncClockProgress
  description: |
    The status progress of syncing local ntp client aiming to get ntp offset.

x-networkInformationNtpStatus: &networkInformationNtpStatus
  type: object
  description: |
    [Network Time Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) information of the server.

    **Important:** This piece of information only makes sense when the server runs on the same host machine as the node.
  required:
    - status
  properties:
    status:
      type: string
      enum:
        - available
        - unavailable
        - pending
    offset:
      type: object
      description: |
        <span style="position: relative; left: 35px; top: -21px; vertical-align: middle; background-color: rgba(142, 142, 220, 0.05); color: rgba(50, 50, 159, 0.9); margin: 0 5px; padding: 0 5px; border: 1px solid rgba(50, 50, 159, 0.1); line-height: 20px; font-size: 13px; border-radius: 2px;">
        <strong>if:</strong> status == available
        </span><br/>
        Drift offset of the local clock.
      required:
        - quantity
        - unit
      properties:
        quantity:
          type: integer
          example: 14
        unit:
          type: string
          enum:
            - microsecond

x-networkInformationNodeTip: &networkInformationNodeTip
  <<: *blockReference
  description: Underlying node's tip

x-networkInformationProtocolUpdate: &networkInformationProtocolUpdate
  type: string
  description: |
    Whether protocol updates have been submitted and accepted by the network.
  enum:
    - up_to_date
    - update_available

x-delegationStatus: &delegationStatus
  type: string
  enum:
    - not_delegating
    - delegating

x-delegationTarget: &delegationTarget
  <<: *stakePoolId
  description: A unique Stake-Pool identifier (present only if status = `delegating`)

x-addressIndex: &addressIndex
  type: number
  minimum: 0
  # 2 ^ 32 - 1, whole range (soft and hard) for random addresses:
  maximum: 4294967295
  description: |
    An address derivation index.

x-gCStatus :: &gCStatus

x-deposits: &deposits
  description: A list of deposits associated with a transaction.
  type: array
  minItems: 0
  items: *amount

x-minimumCoins: &minimumCoins
  description: |
    A list of minimum coin values that each output in a payment must satisfy. The values themselves depends on two things:

      - (a) Some updatable protocol parameters fixed by the network.
      - (b) The nature of the outputs (i.e. the kind of assets it includes).

    The list is a direct 1:1 mapping of the requested outputs. Said differently, it has the **same number of items** and **items
    are ordered in the same way** as **requested outputs** are ordered. In the case where there's no explicitly requested outputs (e.g.
    when calculating fee for delegation), this list is empty.

    For example, an output containing only `Ada` may require to be of at least `1 Ada`. An output containing only an hypothetical `AppleCoin`
    may require to also carry a minimum of `1.2 Ada`. Note that no matter what, a minimum coin value is always given in Lovelace / Ada.

    > ℹ️ This mechanism is used by the protocol to protect against flooding of the network with worthless assets. By requiring a minimum coin value to every
    UTxO, they are given an intrinsic value indexed itself on the value of Ada.
  type: array
  minItems: 0
  items: *amount

#############################################################################
#                                                                           #
#                              DEFINITIONS                                  #
#                                                                           #
#############################################################################

components:
  schemas:
    ApiAddress: &ApiAddress
      type: object
      required:
        - id
        - state
        - derivation_path
      properties:
        id: *addressId
        state: *addressState
        derivation_path: *derivationPath

    ApiAddressInspect: &ApiAddressInspect
        type: object
        required:
        - address_style
        - stake_reference
        properties:
          address_style:
            type: string
            enum:
            - Shelley
            - Icarus
            - Byron
          stake_reference:
            type: string
            enum:
            - none
            - by value
            - by pointer
          network_tag:
            description: Can be null for 'Icarus' and 'Byron' styles.
            type: integer
            minimum: 0
          spending_key_hash:
            type: string
            format: base16
            minLength: 56
            maxLength: 56
          spending_key_bech32:
            type: string
            format: bech32
          stake_key_hash:
            type: string
            format: base16
            minLength: 56
            maxLength: 56
          stake_key_bech32:
            type: string
            format: bech32
          script_hash:
            type: string
            format: base16
            minLength: 64
            maxLength: 64
          script_hash_bech32:
            type: string
            format: bech32
          pointer:
            type: object
            additionalProperties: false
            required:
            - slot_num
            - transaction_index
            - output_index
            properties:
              slot_num:
                type: integer
                minimum: 0
              transaction_index:
                type: integer
                minimum: 0
              output_index:
                type: integer
                minimum: 0
          address_root:
            description: Only for 'Icarus' and 'Byron' styles.
            type: string
            format: base16
          derivation_path:
            description: Only for 'Byron' style.
            type: string
            format: base16

    ApiNetworkTip: &ApiNetworkTip
      <<: *slotReference
      description: The time slot corresponding the network tip.

    ApiEra: &ApiEra
      type: string
      enum:
        - byron
        - shelley
        - allegra
        - mary

    ApiNetworkInformation: &ApiNetworkInformation
      type: object
      required:
        - sync_progress
        - node_tip
        - node_era
      properties:
        sync_progress: *networkInformationSyncProgress
        node_tip: *networkInformationNodeTip
        network_tip: *ApiNetworkTip
        next_epoch: *epochInfo
        node_era: *ApiEra

    ApiNetworkClock: &ApiNetworkClock
      <<: *networkInformationNtpStatus

    nullableEpochInfo: &nullableEpochInfo
      <<: *epochInfo
      nullable: True

    ApiEraInfo: &ApiEraInfo
      type: object
      properties:
        byron: *nullableEpochInfo
        shelley: *nullableEpochInfo
        allegra: *nullableEpochInfo
        mary: *nullableEpochInfo
      description: |

        If and when each era started or will start.

        The object is keyed by era names. The values either describe the epoch boundary
        when the era starts (can be in the future or in the past), or are null if not yet
        confirmed on-chain.

        If you need to know the current era, see the `node_era` field of
        `GET /network/information`.

        > Due to complications with our current tooling, we cannot mark the era names
        > as required, but the keys are in fact always present.

    ApiNetworkParameters: &ApiNetworkParameters
      type: object
      required:
        - genesis_block_hash
        - blockchain_start_time
        - slot_length
        - epoch_length
        - security_parameter
        - active_slot_coefficient
        - decentralization_level
        - desired_pool_number
        - minimum_utxo_value
        - eras
      properties:
        genesis_block_hash: *blockId
        blockchain_start_time: *date
        slot_length: *numberOfSeconds
        epoch_length: *numberOfSlots
        security_parameter: *numberOfBlocks
        active_slot_coefficient: *percentage
        decentralization_level: *percentage
        desired_pool_number: *stakePoolsNumber
        minimum_utxo_value: *amount
        eras: *ApiEraInfo

    ApiSelectCoinsPayments: &ApiSelectCoinsPayments
      type: object
      required:
        - payments
      properties:
        payments: *transactionOutputs
        withdrawal: *transactionWithdrawalRequestSelf
        metadata: *transactionMetadata

    ApiSelectCoinsRedemption: &ApiSelectCoinsRedemption
      type: object
      required:
        - payments
        - withdrawal
      properties:
        payments: *transactionOutputs
        withdrawal: *transactionRedemptionRequest
        metadata: *transactionMetadata

    ApiSelectCoinsAction: &ApiSelectCoinsAction
      type: object
      required:
        - delegation_action
      properties:
        delegation_action: *delegationAction

    ApiSelectCoinsData: &ApiSelectCoinsData
      type: object
      oneOf:
        - title: Normal payment
          <<: *ApiSelectCoinsPayments
        - title: Delegation
          <<: *ApiSelectCoinsAction
        - title: Reward redemption
          <<: *ApiSelectCoinsRedemption

    ApiByronSelectCoinsData: &ApiByronSelectCoinsData
      type: object
      required:
        - payments
      properties:
        payments: *transactionOutputs

    ApiCoinSelection: &ApiCoinSelection
      type: object
      required:
        - inputs
        - outputs
        - change
      properties:
        inputs: *transactionResolvedInputs
        outputs: *transactionOutputs
        change: *transactionChange
        withdrawals: *transactionResolvedWithdrawals
        certificates:
          type: array
          items: *certificate
        deposits: *deposits
        metadata: *transactionSerializedMetadata

    ApiGCStatus: &ApiGCStatus
      type: object
      description: |
        Gives an indication if metadata GC checking for delisted pools
        has run and if so, when.

        Possible values are:
          - not_applicable -> we're currently not querying a SMASH server for metadata
          - not_started -> the GC hasn't started yet, try again in a short while
          - restarting -> the GC thread is currently restarting, try again in short while
          - has_run -> the GC has run successfully

        When 'status' is 'restarting' or 'has_run' then the field 'last_run'
        is set to the last GC time in UTC.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - not_applicable
            - not_started
            - restarting
            - has_run
        last_run: *date

    ApiMaintenanceActionPostData: &ApiMaintenanceActionPostData
      type: object
      required:
        - maintenance_action
      description: |
        The maintenance action to carry out, current values are
          - gc_stake_pools -> trigger looking up delisted pools from the remote SMASH server
      properties:
        maintenance_action:
          type: string
          enum: ['gc_stake_pools']

    ApiMaintenanceAction: &ApiMaintenanceAction
      type: object
      required:
      - gc_stake_pools
      properties:
        gc_stake_pools: *ApiGCStatus

    ApiStakePool: &ApiStakePool
      type: object
      required:
        - id
        - metrics
        - cost
        - margin
        - pledge
        - flags
      properties:
        id: *stakePoolId
        metrics: *stakePoolMetrics
        cost: *stakePoolCost
        margin: *stakePoolMargin
        pledge: *stakePoolPledge
        metadata: *stakePoolMetadata
        retirement: *stakePoolRetirement
        flags: *stakePoolFlags

    ApiFee: &ApiFee
      type: object
      required:
        - estimated_min
        - estimated_max
        - minimum_coins
        - deposit
      properties:
        estimated_min: *amount
        estimated_max: *amount
        minimum_coins: *minimumCoins
        deposit: *amount

    ApiPutAddressesData: &ApiPutAddressesData
      type: object
      required:
        - addresses
      properties:
        addresses:
          <<: *addresses
          description: The imported addresses.

    ApiVerificationKey: &ApiVerificationKey
      type: string
      format: bech32
      pattern: "^((addr_vk)|(stake_vk)|(script_vk))1[0-9a-z]*$"

    ApiAccountKey: &ApiAccountKey
      type: string
      format: bech32
      pattern: "^((acct_xvk)|(acct_vk))1[0-9a-z]*$"

    ApiTxId: &ApiTxId
      type: object
      required:
        - id
      properties:
        id: *transactionId

    ApiTransaction: &ApiTransaction
      type: object
      required:
        - id
        - amount
        - fee
        - deposit
        - direction
        - inputs
        - outputs
        - withdrawals
        - mint
        - status
      properties:
        id: *transactionId
        amount:
          <<: *amount
          description: |
            An amount of Ada spent or received, from the perspective of the wallet.

            That is, for outgoing transaction, it represents the amount of Ada consumed
            as inputs, minus the amount of Ada spent as fees, as deposits or to addresses
            which do not belong to the wallet.

            For incoming transaction, it represents the total amount of Ada received to
            addresses that belong to the wallet.
        fee: *amount
        deposit: *amount
        inserted_at: *transactionInsertedAt
        expires_at: *transactionExpiresAt
        pending_since: *transactionPendingSince
        depth: *transactionDepth
        direction: *transactionDirection
        inputs: *transactionInputs
        outputs: *transactionOutputs
        withdrawals: *transactionWithdrawals
        mint: *transactionMint
        status: *transactionStatus
        metadata: *transactionMetadata

    ApiWalletDelegationNext: &ApiWalletDelegationNext
      type: object
      description: Next delegation status becomes active at the start of the second epoch after the corresponding delegation certificate was discovered. The exact moment is specified by changes_at
      required:
        - status
        - changes_at
      properties:
        status: *delegationStatus
        target: *delegationTarget
        changes_at: *epochInfo
      example:
        status: not_delegating
        changes_at:
          epoch_number: 14
          epoch_start_time: 2020-01-22T10:06:39.037Z

    ApiWalletDelegation: &ApiWalletDelegation
      description: Delegation settings
      type: object
      required:
        - active
        - next
      properties:
        active:
          type: object
          description: Currently active delegation status.
          required:
            - status
          properties:
            status: *delegationStatus
            target: *delegationTarget
          example:
            status: delegating
            target: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1
        next:
          type: array
          items: *ApiWalletDelegationNext

    ApiWallet: &ApiWallet
      type: object
      required:
        - id
        - address_pool_gap
        - balance
        - assets
        - delegation
        - name
        - state
        - tip
      properties:
        id: *walletId
        address_pool_gap: *walletAddressPoolGap
        balance: *walletBalance
        assets: *walletAssetsBalance
        delegation: *ApiWalletDelegation
        name: *walletName
        passphrase: *walletPassphraseInfo
        state: *walletState
        tip: *blockReference

    ApiByronWallet: &ApiByronWallet
      type: object
      required:
        - id
        - balance
        - assets
        - discovery
        - name
        - state
        - tip
      properties:
        id: *walletId
        balance: *byronWalletBalance
        assets: *walletAssetsBalance
        discovery: *walletDiscovery
        name: *walletName
        passphrase: *walletPassphraseInfo
        state: *walletState
        tip: *blockReference

    ApiWalletPostData: &ApiWalletPostData
      type: object
      description: Restore from root private key
      required:
        - name
        - mnemonic_sentence
        - passphrase
      properties:
        name: *walletName
        mnemonic_sentence: *walletMnemonicSentence
        mnemonic_second_factor: *walletSecondFactor
        passphrase: *walletPassphrase
        address_pool_gap: *walletAddressPoolGap

    ApiAccountPostData: &ApiAccountPostData
      type: object
      description: Restore from account public key
      required:
        - name
        - account_public_key
      properties:
        name: *walletName
        account_public_key: *walletAccountPubkey
        address_pool_gap: *walletAddressPoolGap

    ApiWalletOrAccountPostData: &ApiWalletOrAccountPostData
      type: object
      oneOf:
        - <<: *ApiWalletPostData
          title: shelley
        - <<: *ApiAccountPostData
          title: shelley (from xpub)

    ApiActiveSharedWallet: &ApiActiveSharedWallet
      type: object
      required:
        - id
        - name
        - account_index
        - address_pool_gap
        - payment_script_template
        - balance
        - assets
        - delegation
        - state
        - tip
      properties:
        id: *walletId
        name: *walletName
        account_index: *derivationSegment
        address_pool_gap: *walletAddressPoolGap
        passphrase: *walletPassphraseInfo
        payment_script_template: *scriptTemplate
        delegation_script_template: *scriptTemplate
        balance: *walletBalance
        assets: *walletAssetsBalance
        delegation: *ApiWalletDelegation
        state: *walletState
        tip: *blockReference

    ApiPendingSharedWallet: &ApiPendingSharedWallet
      type: object
      required:
        - id
        - name
        - account_index
        - address_pool_gap
        - payment_script_template
      properties:
        id: *walletId
        name: *walletName
        account_index: *derivationSegment
        address_pool_gap: *walletAddressPoolGap
        payment_script_template: *scriptTemplate
        delegation_script_template: *scriptTemplate

    ApiSharedWallet: &ApiSharedWallet
      type: object
      oneOf:
        - title: Pending shared wallet (collecting account public keys for each co-signer)
          <<: *ApiPendingSharedWallet
        - title: Active shared wallet (account public keys for each co-signers is collected)
          <<: *ApiActiveSharedWallet

    ApiSharedWalletPostDataFromMnemonics: &ApiSharedWalletPostDataFromMnemonics
      type: object
      required:
        - name
        - mnemonic_sentence
        - passphrase
        - account_index
        - payment_script_template
      properties:
        name: *walletName
        mnemonic_sentence: *walletMnemonicSentence
        mnemonic_second_factor: *walletSecondFactor
        passphrase: *walletPassphrase
        account_index: *derivationSegment
        payment_script_template: *scriptTemplate
        delegation_script_template: *scriptTemplate

    ApiSharedWalletPostDataFromAccountPubX: &ApiSharedWalletPostDataFromAccountPubX
      type: object
      required:
        - name
        - account_public_key
        - account_index
        - payment_script_template
      properties:
        name: *walletName
        account_public_key: *walletAccountPubkey
        account_index: *derivationSegment
        payment_script_template: *scriptTemplate
        delegation_script_template: *scriptTemplate

    ApiSharedWalletPostData: &ApiSharedWalletPostData
      type: object
      oneOf:
        - title: Create shared wallet from mnemonics
          <<: *ApiSharedWalletPostDataFromMnemonics
        - title: Create shared wallet from account public key
          <<: *ApiSharedWalletPostDataFromAccountPubX

    ApiSharedWalletPatchData: &ApiSharedWalletPatchData
      <<: *cosigners

    ApiAsset: &ApiAsset
      type: object
      required:
        - policy_id
        - fingerprint
        - asset_name
      properties:
        policy_id: *assetPolicyId
        asset_name: *assetName
        fingerprint: *assetFingerprint
        metadata: *assetMetadata

    ApiWalletMigrationBalance: &ApiWalletMigrationBalance
      type: object
      required:
        - ada
        - assets
      properties:
        ada: *amount
        assets: *walletAssets

    ApiWalletMigrationPlan: &ApiWalletMigrationPlan
      type: object
      required:
        - selections
        - total_fee
        - balance_leftover
        - balance_selected
      properties:
        selections:
          type: array
          items: *ApiCoinSelection
          description: |
            The complete set of selections required for a migration.

            Each selection is the basis for a single transaction.

            The ordering of selections within the list is not significant.
            After conversion into transactions, the transactions can be
            broadcast to the network in any order to perform the migration.
        total_fee:
          <<: *amount
          description: |
            The total amount to be paid in fees for a migration.

            This is the total sum of the fees of the individual selections.
        balance_leftover:
          <<: *ApiWalletMigrationBalance
          description: |
            The total balance of assets that **cannot** be migrated.

            The **ada** component of this balance is the total sum of all dust
            ada entries in the UTxO set. An ada entry is considered to be dust
            if its value is not large enough to pay for the marginal cost of
            including it in a transaction.

            The **assets** component of this balance is the total sum of all
            non-ada assets that cannot currently be migrated. Tokens of a
            non-ada asset cannot be migrated if there is insufficient ada
            available to pay for their inclusion in a transaction.
        balance_selected:
          <<: *ApiWalletMigrationBalance
          description: |
            The total balance of assets that **can** be migrated.

    ApiWalletPassphrase: &ApiWalletPassphrase
      type: object
      required:
        - passphrase
      properties:
        passphrase:
          <<: *lenientPassphrase
          description: The source Byron wallet's master passphrase.

    ApiWalletMigrationPlanPostData: &ApiWalletMigrationPlanPostData
      type: object
      required:
        - addresses
      properties:
        addresses:
          <<: *addresses
          description: The recipient addresses.

    ApiByronWalletMigrationPostData: &ApiByronWalletMigrationPostData
      type: object
      required:
        - passphrase
        - addresses
      properties:
        passphrase:
          <<: *lenientPassphrase
          description: The wallet's master passphrase.
        addresses:
          <<: *addresses
          description: The recipient addresses.

    ApiShelleyWalletMigrationPostData: &ApiShelleyWalletMigrationPostData
      type: object
      required:
        - passphrase
        - addresses
      properties:
        passphrase:
          <<: *walletPassphrase
          description: The wallet's master passphrase.
        addresses:
          <<: *addresses
          description: The recipient addresses.

    ApiWalletUTxOsStatistics: &ApiWalletUTxOsStatistics
      type: object
      required:
        - total
        - scale
        - distribution
      properties:
        total: *amount
        scale:
          type: string
          enum:
            - log10
        distribution:
          type: object
          additionalProperties:
            type: integer
      example:
        total:
          quantity: 42000000
          unit: lovelace
        scale: log10
        distribution:
          10: 1
          100: 0
          1000: 8
          10000: 14
          100000: 32
          1000000: 3
          10000000: 0
          100000000: 12
          1000000000: 0
          10000000000: 0
          100000000000: 0
          1000000000000: 0
          10000000000000: 0
          100000000000000: 0
          1000000000000000: 0
          10000000000000000: 0
          45000000000000000: 0

    ApiWalletSignData: &ApiWalletSignData
        type: object
        required:
          - passphrase
          - metadata
        properties:
          passphrase: *lenientPassphrase
          metadata: *transactionMetadata

    ApiScript: &ApiScript
      <<: *script

    ApiPubKey: &ApiPubKey
      <<: *credentialPubKey

    AnyAddress: &AnyAddress
      type: object
      required:
        - address
      properties:
        address: *anyAddress

    ApiCredential: &ApiCredential
      <<: *CredentialValue

    ApiAddressData: &ApiAddressData
      type: object
      nullable: false
      properties:
        payment: *ApiCredential
        stake:
          <<: *ApiCredential
          example: stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d
        validation: *validationLevel

    ApiByronWalletRandomPostData: &ApiByronWalletRandomPostData
      type: object
      required:
        - name
        - mnemonic_sentence
        - passphrase
      properties:
        style:
          type: string
          enum: ["random"]
        name: *walletName
        passphrase: *walletPassphrase
        mnemonic_sentence:
          <<: *walletMnemonicSentence
          minItems: 12
          maxItems: 24

    ApiByronWalletRandomXPrvPostData: &ApiByronWalletRandomXPrvPostData
      type: object
      description: patate
      required:
        - name
        - encrypted_root_private_key
        - passphrase_hash
      properties:
        style:
          type: string
          enum: ["random"]
        name: *walletName
        encrypted_root_private_key:
          <<: *walletEncryptedRootPrivateKey
          deprecated: true

        passphrase_hash:
          <<: *walletPassphraseHash
          deprecated: true

    ApiByronWalletIcarusPostData: &ApiByronWalletIcarusPostData
      type: object
      required:
        - name
        - mnemonic_sentence
        - passphrase
      properties:
        style:
          type: string
          enum: ["icarus"]
        name: *walletName
        passphrase: *walletPassphrase
        mnemonic_sentence:
          <<: *walletMnemonicSentence
          minItems: 12
          maxItems: 24

    ApiByronWalletTrezorPostData: &ApiByronWalletTrezorPostData
      type: object
      required:
        - name
        - mnemonic_sentence
        - passphrase
      properties:
        style:
          type: string
          enum: ["trezor"]
        name: *walletName
        passphrase: *walletPassphrase
        mnemonic_sentence:
          <<: *walletMnemonicSentence
          minItems: 12
          maxItems: 24

    ApiByronWalletLedgerPostData: &ApiByronWalletLedgerPostData
      type: object
      required:
        - name
        - mnemonic_sentence
        - passphrase
      properties:
        style:
          type: string
          enum: ["ledger"]
        name: *walletName
        passphrase: *walletPassphrase
        mnemonic_sentence:
          <<: *walletMnemonicSentence
          minItems: 12
          maxItems: 24

    ApiWalletPutData: &ApiWalletPutData
      type: object
      properties:
        name: *walletName

    ApiPostAccountKeyData: &ApiPostAccountKeyData
      type: object
      required:
        - passphrase
        - extended
      properties:
        passphrase: *walletPassphrase
        extended: *keyExtended

    ApiSettingsPutData: &ApiSettingsPutData
      type: object
      properties:
        settings: *settings

    ApiSmashServer: &ApiSmashServer
      type: string
      pattern: '^https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?$'
      example: https://smash.cardano-mainnet.iohk.io/
      description: A base SMASH uri without endpoint path.

    ApiHealthCheck: &ApiHealthCheck
      type: object
      required:
        - health
      properties:
        health:
          type: string
          enum: ["available", "unavailable", "unreachable", "no_smash_configured"]
      description: |
        The status of the SMASH server. Possible values are:

        health                  | description
        ---                     | ---
        `"available"`           | server is awaiting your requests
        `"unavailable"`         | server is running, but currently unavailable, try again in a short time
        `"unreachable"`         | server could not be reached or didn't return a health status
        `"no_smash_configured"` | SMASH is currently not configured, adjust the Settings first

    ApiWalletPutPassphraseData: &ApiWalletPutPassphraseData
      type: object
      required:
        - old_passphrase
        - new_passphrase
      properties:
        old_passphrase:
          <<: *walletPassphrase
          description: The current passphrase.
        new_passphrase:
          <<: *walletPassphrase
          description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds).

    ApiByronWalletPutPassphraseData: &ApiByronWalletPutPassphraseData
      type: object
      required:
        - new_passphrase
      properties:
        old_passphrase:
          <<: *lenientPassphrase
          description: The current passphrase if present.
        new_passphrase:
          <<: *walletPassphrase
          description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds).

    ApiPostTransactionDataByron: &ApiPostTransactionDataByron
      type: object
      required:
        - payments
        - passphrase
      properties:
        payments: *transactionOutputs
        passphrase:
          <<: *lenientPassphrase
          description: The wallet's master passphrase.

    ApiPostTransactionData: &ApiPostTransactionData
      type: object
      required:
        - payments
        - passphrase
      properties:
        passphrase:
          <<: *lenientPassphrase
          description: The wallet's master passphrase.
        payments: *transactionOutputs
        withdrawal: *transactionWithdrawalRequestSelf
        metadata: *transactionMetadata
        time_to_live: *transactionTTL

    ApiPostRedemptionData: &ApiPostRedemptionData
      type: object
      required:
        - payments
        - passphrase
        - withdrawal
      properties:
        passphrase:
          <<: *lenientPassphrase
          description: The wallet's master passphrase.
        payments: *transactionOutputs
        withdrawal: *transactionRedemptionRequest

    ApiPostTransactionFeeDataByron: &ApiPostTransactionFeeDataByron
      type: object
      required:
        - payments
      properties:
        payments: *transactionOutputs

    ApiPostTransactionFeeData: &ApiPostTransactionFeeData
      type: object
      required:
        - payments
      properties:
        payments: *transactionOutputs
        withdrawal: *transactionWithdrawalRequestSelf
        metadata: *transactionMetadata
        time_to_live: *transactionTTL

    ApiPostRedemptionFeeData: &ApiPostRedemptionFeeData
      type: object
      required:
        - payments
        - withdrawal
      properties:
        payments: *transactionOutputs
        withdrawal: *transactionRedemptionRequest

    ApiPostRandomAddressData: &ApiPostRandomAddressData
      type: object
      required:
        - passphrase
      properties:
        passphrase: *lenientPassphrase
        address_index: *addressIndex

    CredentialValue: *CredentialValue

    ScriptValue: *ScriptValue

    ScriptTemplateValue: *ScriptTemplateValue

    # https://github.com/input-output-hk/cardano-ledger-specs/blob/8d836e61bb88bda4a6a5c00694735928390067a1/shelley/chain-and-ledger/executable-spec/src/Shelley/Spec/Ledger/MetaData.hs#L48-L65
    TransactionMetadataValue: &TransactionMetadataValue
      oneOf:
        - title: String
          type: object
          required:
            - string
          properties:
            string:
              type: string
              maxLength: 64

        - title: Int
          type: object
          required:
            - int
          properties:
            int:
              type: integer

        - title: ByteString
          type: object
          required:
            - bytes
          properties:
            bytes:
              type: string
              pattern: "^[0-9a-fA-F]*$"
              maxLength: 128

        - title: List
          type: object
          required:
            - list
          properties:
            list:
              type: array
              items:
                $ref: "#/components/schemas/TransactionMetadataValue"

        - title: Map
          type: object
          required:
            - map
          properties:
            map:
              type: array
              items:
                type: object
                properties:
                  k:
                    $ref: "#/components/schemas/TransactionMetadataValue"
                  v:
                    $ref: "#/components/schemas/TransactionMetadataValue"

    ApiGetSettings: &ApiGetSettings
      type: object
      required:
        - pool_metadata_source
      properties:
        pool_metadata_source: *poolMetadataSource

    SomeByronWalletPostData: &SomeByronWalletPostData
      oneOf:
        - <<: *ApiByronWalletRandomPostData
          title: random
        - <<: *ApiByronWalletIcarusPostData
          title: icarus
        - <<: *ApiByronWalletTrezorPostData
          title: trezor
        - <<: *ApiByronWalletLedgerPostData
          title: ledger
        - <<: *ApiAccountPostData
          title: icarus/trezor/ledger (from xpub)
        - <<: *ApiByronWalletRandomXPrvPostData
          title: random (from xprv)


#############################################################################
#                                                                           #
#                               PARAMETERS                                  #
#                                                                           #
#############################################################################

x-parametersWalletId: &parametersWalletId
  in: path
  name: walletId
  required: true
  schema:
    type: string
    format: hex
    maxLength: 40
    minLength: 40

x-parametersIntendedStakeAmount: &parametersIntendedStakeAmount
  in: query
  name: stake
  required: true
  schema:
    type: integer
    minimum: 0
    maximum: 45_000_000_000_000_000 # 45 B ada (in Lovelace)
  description: |
    The stake the user intends to delegate in Lovelace. Required.

x-parametersTransactionId: &parametersTransactionId
  in: path
  name: transactionId
  required: true
  schema:
    type: string
    format: hex
    maxLength: 64
    minLength: 64

x-parametersStakePoolId: &parametersStakePoolId
  in: path
  name: stakePoolId
  required: true
  schema:
    type: string
    format: hex|bech32

x-parametersAddressId:  &parametersAddressId
  in: path
  name: addressId
  required: true
  schema:
    type: string
    format: base58
    example: DdzFFzCqrhtCNjPk5Lei7E1FxnoqMoAYtJ8VjAWbFmDb614nNBWBwv3kt6QHJa59cGezzf6piMWsbK7sWRB5sv325QqWdRuusMqqLdMt

x-parametersRole: &parametersRole
  in: path
  name: role
  required: true
  schema:
    type: string
    enum:
    - utxo_external
    - utxo_internal
    - mutable_account
    - multisig_script

x-parametersDerivationSegment: &parametersDerivationSegment
  in: path
  name: index
  required: true
  schema: *derivationSegment

x-parametersStartDate: &parametersStartDate
  in: query
  name: start
  description: |
    An optional start time in ISO 8601 date-and-time format. Basic and
    extended formats are both accepted. Times can be local (with a
    timezone offset) or UTC.

    If both a start time and an end time are specified, then the start
    time must not be later than the end time.

    Example: `2008-08-08T08:08:08Z`
  schema:
    type: string
    format: ISO 8601

x-parametersEndDate: &parametersEndDate
  in: query
  name: end
  description: |
    An optional end time in ISO 8601 date-and-time format. Basic and
    extended formats are both accepted. Times can be local (with a
    timezone offset) or UTC.

    If both a start time and an end time are specified, then the start
    time must not be later than the end time.

    Example: `2008-08-08T08:08:08Z`
  schema:
    type: string
    format: ISO 8601

x-parametersSortOrder: &parametersSortOrder
  in: query
  name: order
  description: An optional sort order.
  schema:
    type: string
    enum:
      - ascending
      - descending
    default: descending

x-parametersAddressState: &parametersAddressState
  in: query
  name: state
  description: An optional filter on the address state.
  schema:
    type: string
    enum:
      - used
      - unused

x-parametersForceNtpCheck: &parametersForceNtpCheck
  in: query
  name: forceNtpCheck
  allowEmptyValue: true
  description: |
    NTP checks are cached for short duration to avoid sending too many queries to the central NTP servers. In some cases however, a client may want to force a new check.

    When this flag is set, the request **will block** until NTP server responds or will timeout after a while without any answer from the NTP server.
  schema:
    type: boolean

x-parametersMinWithdrawal: &parametersMinWithdrawal
  in: query
  name: minWithdrawal
  description: |
    Returns only transactions that have at least one withdrawal above the given amount.
    This is particularly useful when set to `1` in order to list the withdrawal history of a wallet.
  schema:
    type: integer
    minimum: 1

x-parametersPolicyId: &parametersPolicyId
  in: path
  name: policyId
  required: true
  schema:
    type: string
    format: hex
    maxLength: 56
    minLength: 56

x-parametersAssetName: &parametersAssetName
  in: path
  name: assetName
  required: true
  schema:
    type: string
    format: hex
    maxLength: 64

#############################################################################
#                                                                           #
#                                RESPONSES                                  #
#                                                                           #
#############################################################################

x-responsesErr: &responsesErr
  type: object
  required:
    - message
    - code
  properties:
    message:
      type: string
      description: A descriptive error message.
    code:
      type: string
      description: A specific error code for this error, more precise than HTTP ones.
      example: an_error_code

x-errNotFound: &errNotFound
  <<: *responsesErr
  title: not_found
  properties:
    message:
      type: string
      description: A descriptive error message.
    code:
      type: string
      enum: ['not_found']

x-errSoftDerivationRequired: &errSoftDerivationRequired
  <<: *responsesErr
  title: not_found
  properties:
    message:
      type: string
      description: A descriptive error message.
    code:
      type: string
      enum: ['soft_derivation_required']

x-errHardenedDerivationRequired: &errHardenedDerivationRequired
  <<: *responsesErr
  title: not_found
  properties:
    message:
      type: string
      description: A descriptive error message.
    code:
      type: string
      enum: ['hardened_derivation_required']

x-errNoSuchWallet: &errNoSuchWallet
  <<: *responsesErr
  title: no_such_wallet
  properties:
    message:
      type: string
      description: |
        May occur when a given walletId does not match with any known
        wallets (because it has been deleted, or has never existed).
    code:
      type: string
      enum: ['no_such_wallet']

x-errNoSuchTransaction: &errNoSuchTransaction
  <<: *responsesErr
  title: no_such_transaction
  properties:
    message:
      type: string
      description: May occur when a given transactionId does not match with any known transactions.
    code:
      type: string
      enum: ['no_such_transaction']

x-errTransactionAlreadyInLedger: &errTransactionAlreadyInLedger
  <<: *responsesErr
  title: transaction_already_in_ledger
  properties:
    message:
      type: string
      description: Occurs when attempting to delete a transaction which is neither pending nor expired.
    code:
      type: string
      enum: ['transaction_already_in_ledger']

x-errWalletAlreadyExists: &errWalletAlreadyExists
  <<: *responsesErr
  title: wallet_already_exists
  properties:
    message:
      type: string
      description: May occur when a otherwise valid request would yield a wallet that already exists.
    code:
      type: string
      enum: ['wallet_already_exists']

x-errNoRootKey: &errNoRootKey
  <<: *responsesErr
  title: no_root_key
  properties:
    message:
      type: string
      description: May occur when an action require a signing key but the wallet has only access to verification keys.
    code:
      type: string
      enum: ['no_root_key']

x-errWrongEncryptionPassphrase: &errWrongEncryptionPassphrase
  <<: *responsesErr
  title: wrong_encryption_passphrase
  properties:
    message:
      type: string
      description: May occur when the given spending passphrase is wrong.
    code:
      type: string
      enum: ['wrong_encryption_passphrase']

x-errMalformedTxPayload: &errMalformedTxPayload
  <<: *responsesErr
  title: malformed_tx_payload
  properties:
    message:
      type: string
      description: May occur when submitting a malformed serialized transaction.
    code:
      type: string
      enum: ['malformed_tx_payload']

# TODO: Map this error to the place it belongs.
x-errKeyNotFoundForAddress: &errKeyNotFoundForAddress
  <<: *responsesErr
  title: key_not_found_for_address
  properties:
    message:
      type: string
      description: Should never happen unless the server screwed up and has lost track of previously known addresses.
    code:
      type: string
      enum: ['key_not_found_for_address']

x-errNotEnoughMoney: &errNotEnoughMoney
  <<: *responsesErr
  title: not_enough_money
  properties:
    message:
      type: string
      description: May occur when there's not enough money in the wallet to cover a requested payment.
    code:
      type: string
      enum: ['not_enough_money']

x-errTransactionIsTooBig: &errTransactionIsTooBig
  <<: *responsesErr
  title: transaction_is_too_big
  properties:
    message:
      type: string
      description: May occur when the wallet can't cover for all requested outputs without making the transaction too large.
    code:
      type: string
      enum: ['transaction_is_too_big']

x-errInputsDepleted: &errInputsDepleted
  <<: *responsesErr
  title: inputs_depleted
  properties:
    message:
      type: string
      description: May occur when there's enough money to pay for a payment, but not enough UTxO to allow for paying each output independently.
    code:
      type: string
      enum: ['inputs_depleted']

x-errCannotCoverFee: &errCannotCoverFee
  <<: *responsesErr
  title: cannot_cover_fee
  properties:
    message:
      type: string
      description: May occur when a transaction can't be balanced for fees.
    code:
      type: string
      enum: ['cannot_cover_fee']

x-errInvalidCoinSelection: &errInvalidCoinSelection
  <<: *responsesErr
  title: invalid_coin_selection
  properties:
    message:
      type: string
      description: Should never happen unless the server screwed up with the creation of a coin selection.
    code:
      type: string
      enum: ['invalid_coin_selection']

x-errOutputTokenBundleSizeExceedsLimit: &errOutputTokenBundleSizeExceedsLimit
  <<: *responsesErr
  title: output_token_bundle_size_exceeds_limit
  properties:
    message:
      type: string
      description: |
        Returned when a user-specified transaction output contains a token
        bundle whose serialized length exceeds the limit supported by the
        protocol.
    code:
      type: string
      enum: ['output_token_bundle_size_exceeds_limit']

x-errOutputTokenQuantityExceedsLimit: &errOutputTokenQuantityExceedsLimit
  <<: *responsesErr
  title: output_token_quantity_exceeds_limit
  properties:
    message:
      type: string
      description: |
        Returned when a user-specified transaction output contains, for some
        asset, a token quantity that exceeds the limit supported by the
        protocol.
    code:
      type: string
      enum: ['output_token_quantity_exceeds_limit']

x-errSharedWalletNotPending: &errSharedWalletNotPending
  <<: *responsesErr
  title: shared_wallet_not_pending
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to add cosigner key to a shared wallet
        that is active, not pending anymore.
    code:
      type: string
      enum: ['shared_wallet_not_pending']

x-errSharedWalletNoDelegationTemplate: &errSharedWalletNoDelegationTemplate
  <<: *responsesErr
  title: shared_wallet_no_delegation_template
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to add cosigner key to a shared wallet
        for delegation, but the shared wallet misses the delegation template.
    code:
      type: string
      enum: ['shared_wallet_no_delegation_template']

x-errSharedWalletKeyAlreadyExists: &errSharedWalletKeyAlreadyExists
  <<: *responsesErr
  title: shared_wallet_key_already_exists
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to add cosigner key to a shared wallet
        but the same key is already present in a given template.
    code:
      type: string
      enum: ['shared_wallet_key_already_exists']

x-errSharedWalletNoSuchCosigner: &errSharedWalletNoSuchCosigner
  <<: *responsesErr
  title: shared_wallet_no_such_cosigner
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to add cosigner key to a shared wallet
        in script template that misses the cosigner.
    code:
      type: string
      enum: ['shared_wallet_no_such_cosigner']

x-errSharedWalletCannotUpdateKey: &errSharedWalletCannotUpdateKey
  <<: *responsesErr
  title: shared_wallet_cannot_update_key
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to update cosigner key that contains a key of a shared wallet.
        Only other cosigner keys can be updated.
    code:
      type: string
      enum: ['shared_wallet_cannot_update_key']

x-errSharedWalletCreateNotAllowed: &errSharedWalletCreateNotAllowed
  <<: *responsesErr
  title: shared_wallet_create_not_allowed
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to create a shared wallet with missing wallet's
        account key in all the script templates.
    code:
      type: string
      enum: ['shared_wallet_create_not_allowed']

# TODO: Map this error to the place it belongs.
x-errNetworkUnreachable: &errNetworkUnreachable
  <<: *responsesErr
  title: network_unreachable
  properties:
    message:
      type: string
      description: May occur when the connection with the node is lost or not responding.
    code:
      type: string
      enum: ['network_unreachable']

# TODO: Map this error to the place it belongs.
x-errNetworkMisconfigured: &errNetworkMisconfigured
  <<: *responsesErr
  title: network_misconfigured
  properties:
    message:
      type: string
      description: May occur when trying to connect to a wrong network (e.g. testnet instead of mainnet).
    code:
      type: string
      enum: ['network_misconfigured']

# TODO: Map this error to the place it belongs.
x-errNetworkQueryFailed: &errNetworkQueryFailed
  <<: *responsesErr
  title: network_query_failed
  properties:
    message:
      type: string
      description: Occurs when a ledger query fails in an unexpected manner.
    code:
      type: string
      enum: ['network_query_failed']

x-errCreatedInvalidTransaction: &errCreatedInvalidTransaction
  <<: *responsesErr
  title: created_invalid_transaction
  properties:
    message:
      type: string
      description: Should never happen unless the server screwed up with the creation of transaction.
    code:
      type: string
      enum: ['created_invalid_transaction']

x-errRejectedByCoreNode: &errRejectedByCoreNode
  <<: *responsesErr
  title: rejected_by_core_node
  properties:
    message:
      type: string
      description: Should never happen unless the server screwed up with the creation of transaction.
    code:
      type: string
      enum: ['rejected_by_core_node']

x-errBadRequest: &errBadRequest
  <<: *responsesErr
  title: bad_request
  properties:
    message:
      type: string
      description: |
        May occur when a request is not well-formed; that is, it fails to parse
        successfully. This could be the case when some required parameters
        are missing or, when malformed values are provided.
    code:
      type: string
      enum: ['bad_request']

x-errMethodNotAllowed: &errMethodNotAllowed
  <<: *responsesErr
  title: method_not_allowed
  properties:
    message:
      type: string
      description: May occur when sending a request on a wrong endpoint.
    code:
      type: string
      enum: ['method_not_allowed']

x-errNotAcceptable: &errNotAcceptable
  <<: *responsesErr
  title: not_acceptable
  properties:
    message:
      type: string
      description: May occur when providing an invalid 'Accept' header.
    code:
      type: string
      enum: ['not_acceptable']

x-errUnsupportedMediaType: &errUnsupportedMediaType
  <<: *responsesErr
  title: unsupported_media_type
  properties:
    message:
      type: string
      description: May occur when providing an invalid 'Content-Type' header.
    code:
      type: string
      enum: ['unsupported_media_type']

# TODO: Map this error to the place it belongs.
x-errUnexpectedError: &errUnexpectedError
  <<: *responsesErr
  title: unexpected_error
  properties:
    message:
      type: string
      description: Should never occur, unless the server screwed up badly.
    code:
      type: string
      enum: ['unexpected_error']

x-errStartTimeLaterThanEndTime: &errStartTimeLaterThanEndTime
  <<: *responsesErr
  title: start_time_later_than_end_time
  properties:
    message:
      type: string
      description: May occur when a provided time-range is unsound.
    code:
      type: string
      enum: ['start_time_later_than_end_time']

# TODO: Map this error to the place it belongs.
x-errUnableToDetermineCurrentEpoch: &errUnableToDetermineCurrentEpoch
  <<: *responsesErr
  title: unable_to_determine_current_epoch
  properties:
    message:
      type: string
      description: May occur under rare circumstances if the underlying node isn't enough synced with the network.
    code:
      type: string
      enum: ['unable_to_determine_current_epoch']

# TODO: Map this error to the place it belongs.
x-errNotSynced: &errNotSynced
  <<: *responsesErr
  title: not_synced
  properties:
    message:
      type: string
      description: May occur under rare circumstances if the underlying node isn't enough synced with the network.
    code:
      type: string
      enum: ['not_synced']

# TODO: Map this error to the place it belongs.
x-errNothingToMigrate: &errNothingToMigrate
  <<: *responsesErr
  title: nothing_to_migrate
  properties:
    message:
      type: string
      description: May occur when trying to migrate a wallet that is empty or full of dust.
    code:
      type: string
      enum: ['nothing_to_migrate']

x-errNoSuchPool: &errNoSuchPool
  <<: *responsesErr
  title: no_such_pool
  properties:
    message:
      type: string
      description: May occur when a given poolId does not match any known pool.
    code:
      type: string
      enum: ['no_such_pool']

x-errPoolAlreadyJoined: &errPoolAlreadyJoined
  <<: *responsesErr
  title: pool_already_joined
  properties:
    message:
      type: string
      description: May occur when a given poolId matches the current delegation preferences of the wallet's account.
    code:
      type: string
      enum: ['pool_already_joined']

x-errNotDelegatingTo: &errNotDelegatingTo
  <<: *responsesErr
  title: not_delegating_to
  properties:
    message:
      type: string
      description: May occur when trying to quit a pool on an account that isn't delegating.
    code:
      type: string
      enum: ['not_delegating_to']

# TODO: Map this error to the place it belongs.
x-errNotImplemented: &errNotImplemented
  <<: *responsesErr
  title: not_implemented
  properties:
    message:
      type: string
      description: May occur when reaching an endpoint under construction.
    code:
      type: string
      enum: ['not_implemented']

# TODO: Map this error to the place it belongs.
x-errWalletNotResponding: &errWalletNotResponding
  <<: *responsesErr
  title: wallet_not_responding
  properties:
    message:
      type: string
      description: Should never occur unless something really wrong happened causing a background worker to die.
    code:
      type: string
      enum: ['wallet_not_responding']

# TODO: Map this error to the place it belongs.
x-errAddressAlreadyExists: &errAddressAlreadyExists
  <<: *responsesErr
  title: address_already_exists
  properties:
    message:
      type: string
      description: May occur when trying to import an address that is already known of the wallet's account.
    code:
      type: string
      enum: ['address_already_exists']

x-errInvalidWalletType: &errInvalidWalletType
  <<: *responsesErr
  title: invalid_wallet_type
  properties:
    message:
      type: string
      description: May occur when trying to perform an operation not supported by this type of wallet.
    code:
      type: string
      enum: ['invalid_wallet_type']

x-errQueryParamMissing: &errQueryParamMissing
  <<: *responsesErr
  title: query_param_missing
  properties:
    message:
      type: string
      description: May occur when an endpoint requires the presence of a query parameter that is missing.
    code:
      type: string
      enum: ['query_param_missing']

x-errNonNullRewards: &errNonNullRewards
  <<: *responsesErr
  title: non_null_rewards
  properties:
    message:
      type: string
      description: May occur when trying to unregister a stake key that still has rewards attached to it.
    code:
      type: string
      enum: ['non_null_rewards']

x-errUtxoTooSmall: &errUtxoTooSmall
  <<: *responsesErr
  title: utxo_too_small
  properties:
    message:
      type: string
      description: May occur when a requested output is below the minimum utxo value.
    code:
      type: string
      enum: ['utxo_too_small']

x-errMinWithdrawalWrong: &errMinWithdrawalWrong
  <<: *responsesErr
  title: min_withdrawal_wrong
  properties:
    message:
      type: string
      description: May occur when trying to withdraw less than the minimal UTxO value.
    code:
      type: string
      enum: ['min_withdrawal_wrong']

x-errAlreadyWithdrawing: &errAlreadyWithdrawing
  <<: *responsesErr
  title: already_withdrawing
  properties:
    message:
      type: string
      description: May occur when submitting a withdrawal while another withdrawal is pending.
    code:
      type: string
      enum: ['already_withdrawing']

# TODO: Map this error to the place it belongs.
x-errWithdrawalNotWorth: &errWithdrawalNotWorth
  <<: *responsesErr
  title: withdrawal_not_worth
  properties:
    message:
      type: string
      description: May occur when withdrawing an amount would cost more than the withdrawn value.
    code:
      type: string
      enum: ['withdrawal_not_worth']

# TODO: Map this error to the place it belongs.
x-errPastHorizon: &errPastHorizon
  <<: *responsesErr
  title: past_horizon
  properties:
    message:
      type: string
      description: May occur in rare cases when converting slot to time can't be done, typically near hard-forks.
    code:
      type: string
      enum: ['past_horizon']

# TODO: Map this error to the place it belongs.
x-errUnableToAssignInputOutput: &errUnableToAssignInputOutput
  <<: *responsesErr
  title: unable_to_assign_input_output
  properties:
    message:
      type: string
      description: Should never occur unless the server screwed up with a coin selection.
    code:
      type: string
      enum: ['unable_to_assign_input_output']

x-errAssetNotPresent: &errAssetNotPresent
  <<: *responsesErr
  title: asset_not_present
  properties:
    message:
      type: string
      description: |
        Occurs when requesting information about an asset which is not
        involved in any transaction related to the wallet.
    code:
      type: string
      enum: ['asset_not_present']

x-responsesErr400: &responsesErr400
  400:
    description: Bad Request
    content:
      application/json:
        schema: *errBadRequest

x-responsesErr403: &responsesErr403
  403:
    description: Forbidden
    content:
      application/json:
        schema: *responsesErr

x-responsesErr404: &responsesErr404
  404:
    description: Not Found
    content:
      application/json:
        schema: *responsesErr

x-responsesErr406: &responsesErr406
  406:
    description: Not Acceptable
    content:
      application/json:
        schema: *errNotAcceptable

x-responsesErr409: &responsesErr409
  409:
    description: Conflict
    content:
      application/json:
        schema: *responsesErr

x-responsesErr410: &responsesErr410
  410:
    description: Gone
    content:
      application/json:
    schema: *responsesErr

x-responsesErr415: &responsesErr415
  415:
    description: Unsupported Media Type
    content:
      application/json:
        schema: *responsesErr

x-responsesErr423: &responsesErr423
  423:
    description: Locked
    content:
      application/json:
        schema: *responsesErr

x-responsesErr404WalletNotFound: &responsesErr404WalletNotFound
  404:
    description: Not Found
    content:
      application/json:
        schema: *errNoSuchWallet

x-responsesErr409WalletAlreadyExists: &responsesErr409WalletAlreadyExists
  409:
    description: Conflict
    content:
      application/json:
        schema: *errWalletAlreadyExists

x-responsesErr415UnsupportedMediaType: &responsesErr415UnsupportedMediaType
  415:
    description: Unsupported Media Type
    content:
      application/json:
        schema: *errUnsupportedMediaType

x-responsesListWallets: &responsesListWallets
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema:
          type: array
          items: *ApiWallet

x-responsesErr404AssetNotPresent: &responsesErr404AssetNotPresent
  404:
    description: Not Found
    content:
      application/json:
        schema: *errAssetNotPresent

x-responsesListAssets: &responsesListAssets
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema:
          type: array
          items: *ApiAsset

x-responsesGetAsset: &responsesGetAsset
  <<: *responsesErr404AssetNotPresent
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiAsset

x-responsesListByronWallets: &responsesListByronWallets
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema:
          type: array
          items: *ApiByronWallet

x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiWalletUTxOsStatistics

x-responsesPostWallet: &responsesPostWallet
  <<: *responsesErr400
  <<: *responsesErr406
  <<: *responsesErr409WalletAlreadyExists
  <<: *responsesErr415UnsupportedMediaType
  201:
    description: Created
    content:
      application/json:
        schema: *ApiWallet

x-responsesPostSharedWallet: &responsesPostSharedWallet
  <<: *responsesErr400
  <<: *responsesErr406
  <<: *responsesErr409WalletAlreadyExists
  <<: *responsesErr415UnsupportedMediaType
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errSharedWalletCreateNotAllowed
  201:
    description: Created
    content:
      application/json:
        schema: *ApiSharedWallet

x-responsesPostByronWallet: &responsesPostByronWallet
  <<: *responsesErr400
  <<: *responsesErr406
  <<: *responsesErr409
  <<: *responsesErr415
  201:
    description: Created
    content:
      application/json:
        schema: *ApiByronWallet

x-responsesGetWallet: &responsesGetWallet
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiWallet

x-responsesGetByronWallet: &responsesGetByronWallet
  <<: *responsesErr404
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiByronWallet

x-responsesGetSharedWallet: &responsesGetSharedWallet
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiSharedWallet

x-responsesPatchSharedWallet: &responsesPatchSharedWallet
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errSharedWalletKeyAlreadyExists
            - <<: *errSharedWalletNoDelegationTemplate
            - <<: *errSharedWalletNotPending
            - <<: *errSharedWalletNoSuchCosigner
            - <<: *errSharedWalletCannotUpdateKey
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiSharedWallet

x-responsesCreateWalletMigrationPlan: &responsesCreateWalletMigrationPlan
  403:
    description: Forbidden
    content:
      application/json:
        schema: *errNothingToMigrate
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiWalletMigrationPlan

x-responsesMigrateWallet: &responsesMigrateWallet
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errNothingToMigrate
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema:
          type: array
          items: *ApiTransaction
          minItems: 1

x-responsesDeleteWallet: &responsesDeleteWallet
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  204:
    description: No Content

x-responsesForceResyncWallet: &responsesForceResyncWallet
  <<: *responsesErr400
  <<: *responsesErr403
  <<: *responsesErr404
  <<: *responsesErr406
  <<: *responsesErr415
  204:
    description: No Content

x-responsesPutWallet: &responsesPutWallet
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiWallet

x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase
  <<: *responsesErr400
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  204:
    description: No Content

x-responsesSelectCoins: &responsesSelectCoins
  <<: *responsesErr400
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errAlreadyWithdrawing
            - <<: *errUtxoTooSmall
            - <<: *errNotEnoughMoney
            - <<: *errCannotCoverFee
            - <<: *errInputsDepleted
            - <<: *errInvalidCoinSelection
            - <<: *errOutputTokenQuantityExceedsLimit
            - <<: *errOutputTokenBundleSizeExceedsLimit
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  200:
    description: OK
    content:
      application/json:
        schema: *ApiCoinSelection

x-responsesDeleteTransaction: &responsesDeleteTransaction
  403:
    description: Forbidden
    content:
      application/json:
        schema: *errTransactionAlreadyInLedger
  404:
    description: Not Found
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errNoSuchWallet
            - <<: *errNoSuchTransaction
  <<: *responsesErr406
  204:
    description: No Content

x-responsesListTransactions: &responsesListTransactions
  400:
    description: Bad Request
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errMinWithdrawalWrong
            - <<: *errStartTimeLaterThanEndTime
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    headers:
      Content-Range:
        schema:
          type: string
          format: inserted-at {range-start}-{range-end}/{total}
    content:
      application/json:
        schema:
          type: array
          items: *ApiTransaction

x-responsesGetTransaction: &responsesGetTransaction
  404:
    description: Not Found
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errNoSuchWallet
            - <<: *errNoSuchTransaction
  <<: *responsesErr406
  200:
    description: OK
    content:
      application/json:
        schema: *ApiTransaction

x-responsesPostTransaction: &responsesPostTransaction
  400:
    description: Bad Request
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errBadRequest
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errInvalidWalletType
            - <<: *errAlreadyWithdrawing
            - <<: *errUtxoTooSmall
            - <<: *errCannotCoverFee
            - <<: *errNotEnoughMoney
            - <<: *errTransactionIsTooBig
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiTransaction

x-responsesPostExternalTransaction: &responsesPostExternalTransaction
  <<: *responsesErr400
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiTxId

x-responsesPostAnyAddress: &responsesPostAnyAddress
  <<: *responsesErr400
  <<: *responsesErr406
  <<: *responsesErr415
  202:
    description: Accepted
    content:
      application/json:
        schema: *AnyAddress

x-responsesPostTransactionFee: &responsesPostTransactionFee
  400:
    description: Bad Request
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errBadRequest
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errInvalidWalletType
            - <<: *errAlreadyWithdrawing
            - <<: *errUtxoTooSmall
            - <<: *errCannotCoverFee
            - <<: *errNotEnoughMoney
            - <<: *errInputsDepleted
            - <<: *errInvalidCoinSelection
            - <<: *errOutputTokenQuantityExceedsLimit
            - <<: *errOutputTokenBundleSizeExceedsLimit
            - <<: *errTransactionIsTooBig
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiFee

x-responsesGetDelegationFee: &responsesGetDelegationFee
  403:
    description: Forbidden
    content:
      application/json:
        schema: *errCannotCoverFee
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiFee

x-responsesListAddresses: &responsesListAddresses
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema:
          type: array
          items: *ApiAddress

x-responsesGetKey: &responsesGetKey
  <<: *responsesErr400
  <<: *responsesErr404
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiVerificationKey

x-responsesPostAccountKey: &responsesPostAccountKey
  <<: *responsesErr400
  <<: *responsesErr406
  <<: *responsesErr415
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiAccountKey

x-responsesListStakePools: &responsesListStakePools
  400:
    description: Bad Request
    content:
      application/json:
        schema: *errQueryParamMissing
  200:
    description: Ok
    content:
      application/json:
        schema:
          type: array
          items: *ApiStakePool

x-responsesPostMaintenanceAction: &responsesPostMaintenanceAction
  <<: *responsesErr404
  204:
    description: No Content

x-responsesGetMaintenanceAction: &responsesGetMaintenanceAction
  200:
    description: Ok
    content:
      application/json:
        schema:
          <<: *ApiMaintenanceAction

x-responsesJoinStakePool: &responsesJoinStakePool
  <<: *responsesErr400
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errCannotCoverFee
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
            - <<: *errPoolAlreadyJoined
  404:
    description: Not Found
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errNoSuchWallet
            - <<: *errNoSuchPool
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiTransaction

x-responsesQuitStakePool: &responsesQuitStakePool
  <<: *responsesErr400
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errCannotCoverFee
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
            - <<: *errNotDelegatingTo
            - <<: *errNonNullRewards
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiTransaction

x-responsesGetNetworkInformation: &responsesGetNetworkInformation
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiNetworkInformation

x-responsesGetNetworkClock: &responsesGetNetworkClock
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiNetworkClock

x-responsesGetNetworkParameters: &responsesGetNetworkParameters
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiNetworkParameters

x-responsesPostRandomAddress: &responsesPostRandomAddress
  <<: *responsesErr400
  <<: *responsesErr403
  <<: *responsesErr406
  <<: *responsesErr415
  201:
    description: Created
    content:
      application/json:
        schema: *ApiAddress

x-responsesPutRandomAddress: &responsesPutRandomAddress
  <<: *responsesErr400
  <<: *responsesErr403
  204:
    description: No Content

x-responsesPutRandomAddresses: &responsesPutRandomAddresses
  <<: *responsesErr400
  <<: *responsesErr403
  204:
    description: No Content

x-responsesInspectAddress: &responsesInspectAddress
  <<: *responsesErr400
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiAddressInspect

x-responsesPutSettings: &responsesPutSettings
  <<: *responsesErr400
  <<: *responsesErr415UnsupportedMediaType
  204:
    description: No Content

x-responsesGetSettings: &responsesGetSettings
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiGetSettings

x-responsesPostSignatures: &responsesPostSignatures
    <<: *responsesErr400
    <<: *responsesErr406
    <<: *responsesErr415
    200:
      description: OK
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary

x-responsesGetSmashHealth: &responsesGetSmashHealth
  <<: *responsesErr400
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiHealthCheck


#############################################################################
#                                                                           #
#                                  PATHS                                    #
#                                                                           #
#############################################################################

x-tagGroups:
  - name: Shelley (Sequential)
    tags:
    - Wallets
    - Assets
    - Addresses
    - Coin Selections
    - Transactions
    - Migrations
    - Stake Pools
    - Keys

  - name: Byron (Random)
    tags:
    - Byron Wallets
    - Byron Assets
    - Byron Addresses
    - Byron Coin Selections
    - Byron Transactions
    - Byron Migrations

  - name: Shelley (Shared Wallets)
    tags:
    - Shared Wallets

  - name: Miscellaneous
    tags:
    - Utils
    - Network
    - Proxy
    - Settings
    - Experimental

paths:
  /wallets/{walletId}/signatures/{role}/{index}:
      post:
        operationId: signMetadata
        tags: ["Experimental"]
        summary: Sign Metadata
        description: |
          <p align="right">status: <strong>experimental</strong></p>

          **⚠️ WARNING ⚠️**

          This endpoint is experimental and for internal use in the Catalyst project. This
          functionality will be refined in the forthcoming future and the interface is likely
          to change in **NON-BACKWARD COMPATIBLE WAYS**.

          <b>Note:</b> Only `Soft` indexes are supported by this endpoint.
        parameters:
          - *parametersWalletId
          - *parametersRole
          - *parametersDerivationSegment
        requestBody:
          required: true
          content:
            application/json:
              schema: *ApiWalletSignData
        responses: *responsesPostSignatures

  /wallets:
    post:
      operationId: postWallet
      tags: ["Wallets"]
      summary: Create / Restore
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Create and restore a wallet from a mnemonic sentence or account public key.
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletOrAccountPostData
      responses: *responsesPostWallet

    get:
      operationId: listWallets
      tags: ["Wallets"]
      summary: List
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return a list of known wallets, ordered from oldest to newest.
      responses: *responsesListWallets

  /wallets/{walletId}/assets:
    get:
      operationId: listAssets
      tags: ["Assets"]
      summary: List Assets
      description: |
        List all assets associated with the wallet, and their metadata
        if known.

        An asset is _associated_ with a wallet if it is involved in a
        transaction of the wallet.
      parameters:
        - *parametersWalletId
      responses: *responsesListAssets

  /wallets/{walletId}/assets/{policyId}/{assetName}:
    get:
      operationId: getAsset
      tags: ["Assets"]
      summary: Get Asset
      description: |
        Fetch a single asset from its `policy_id` and `asset_name`,
        with its metadata if any.

        The asset must be associated with the wallet.
      parameters:
        - *parametersWalletId
        - *parametersPolicyId
        - *parametersAssetName
      responses: *responsesGetAsset

  /wallets/{walletId}/assets/{policyId}:
    get:
      operationId: getAssetDefault
      tags: ["Assets"]
      summary: Get Asset (empty name)
      description: |
        Fetch the the asset from `policy_id` with an empty name.

        The asset must be associated with the wallet.
      parameters:
        - *parametersWalletId
        - *parametersPolicyId
      responses: *responsesGetAsset

  /wallets/{walletId}/statistics/utxos:
    get:
      operationId: getUTxOsStatistics
      tags: ["Wallets"]
      summary: UTxO Statistics
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return the UTxOs distribution across the whole wallet, in the form of a histogram.

        ```
             │
         100 ─
             │
             │                                 ┌───┐
          10 ─                         ┌───┐   │   │                   ┌───┐
             │                 ┌───┐   │   │   │   │                   │   │
             │                 │   │   │   │   │   │   ┌───┐           │   │
           1 ─ ┌───┐           │   │   │   │   │   │   │   │           │   │
             │ │   │           │   │   │   │   │   │   │   │           │   │
             │ │   │ │       │ │   │ │ │   │ ╷ │   │ ╷ │   │ ╷       ╷ │   │
             └─┘   └─│───────│─┘   └─│─┘   └─│─┘   └─│─┘   └─│───────│─┘   └────
                   10μ₳    100μ₳   1000μ₳   0.1₳    1₳      10₳     100₳
        ```
      parameters:
        - *parametersWalletId
      responses: *responsesGetUTxOsStatistics

  /wallets/{walletId}:
    get:
      operationId: getWallet
      tags: ["Wallets"]
      summary: Get
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      responses: *responsesGetWallet

    delete:
      operationId: deleteWallet
      tags: ["Wallets"]
      summary: Delete
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      responses: *responsesDeleteWallet

    put:
      operationId: putWallet
      tags: ["Wallets"]
      summary: Update Metadata
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletPutData
      responses: *responsesPutWallet

  /wallets/{walletId}/passphrase:
    put:
      operationId: putWalletPassphrase
      tags: ["Wallets"]
      summary: Update Passphrase
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletPutPassphraseData
      responses: *responsesPutWalletPassphrase

  /wallets/{walletId}/payment-fees:
    post:
      operationId: postTransactionFee
      tags: ["Transactions"]
      summary: Estimate Fee
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Estimate fee for the transaction. The estimate is made by
        assembling multiple transactions and analyzing the
        distribution of their fees. The estimated_max is the highest
        fee observed, and the estimated_min is the fee which is lower
        than at least 90% of the fees observed.

      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - <<: *ApiPostTransactionFeeData
                  title: "payment"
                - <<: *ApiPostRedemptionFeeData
                  title: "redemption"
      responses: *responsesPostTransactionFee

  /wallets/{walletId}/transactions:
    post:
      operationId: postTransaction
      tags: ["Transactions"]
      summary: Create
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Create and send transaction from the wallet.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - <<: *ApiPostTransactionData
                  title: "payment"
                - <<: *ApiPostRedemptionData
                  title: "redemption"
      responses: *responsesPostTransaction

    get:
      operationId: listTransactions
      tags: ["Transactions"]
      summary: List
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Lists all incoming and outgoing wallet's transactions.
      parameters:
        - *parametersWalletId
        - *parametersStartDate
        - *parametersEndDate
        - *parametersSortOrder
        - *parametersMinWithdrawal
      responses: *responsesListTransactions

  /wallets/{walletId}/transactions/{transactionId}:
    get:
      operationId: getTransaction
      tags: ["Transactions"]
      summary: Get
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Get transaction by id.
      parameters:
        - *parametersWalletId
        - *parametersTransactionId
      responses: *responsesGetTransaction

    delete:
      operationId: deleteTransaction
      tags: ["Transactions"]
      summary: Forget
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Forget pending transaction. Importantly, a transaction, when sent,
        cannot be cancelled. One can only request forgetting about it
        in order to try spending (concurrently) the same UTxO in another
        transaction. But, the transaction may still show up later in a block
        and therefore, appear in the wallet.
      parameters:
        - *parametersWalletId
        - *parametersTransactionId
      responses: *responsesDeleteTransaction

  /wallets/{walletId}/addresses:
    get:
      operationId: listAddresses
      tags: ["Addresses"]
      summary: List
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return a list of known addresses, ordered from newest to oldest
      parameters:
        - *parametersWalletId
        - *parametersAddressState
      responses: *responsesListAddresses

  /wallets/{walletId}/keys/{index}:
    post:
      operationId: postAccountKey
      tags: ["Keys"]
      summary: Create
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Retrieve account public key from the wallet.

        <b>Note:</b> Only `Hard` indexes are supported by this endpoint.
      parameters:
        - *parametersWalletId
        - *parametersDerivationSegment
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiPostAccountKeyData
      responses: *responsesPostAccountKey

  /wallets/{walletId}/keys/{role}/{index}:
    get:
      operationId: getWalletKey
      tags: ["Keys"]
      summary: Get Public Key
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Return a public key for a given role and derivation index.

        <b>Note:</b> Only `Soft` indexes are supported by this endpoint.
      parameters:
        - *parametersWalletId
        - *parametersRole
        - *parametersDerivationSegment
      responses: *responsesGetKey

  /stake-pools:
    get:
      operationId: listStakePools
      tags: ["Stake Pools"]
      summary: List
      description: |
        <p align="right">status: <strong>stable</strong></p>

        List all known stake pools ordered by descending `non_myopic_member_rewards`.
        The `non_myopic_member_rewards` — and thus the ordering — depends on the `?stake` query
        parameter.

        Some pools _may_ also have metadata attached to them.
      parameters:
        - *parametersIntendedStakeAmount
      responses: *responsesListStakePools

  /stake-pools/maintenance-actions:
    get:
      operationId: getMaintenanceActions
      tags: ["Stake Pools"]
      summary: View maintenance actions
      description: |
        Returns the current status of the stake pools maintenance actions.
      responses: *responsesGetMaintenanceAction

    post:
      operationId: postMaintenanceAction
      tags: ["Stake Pools"]
      summary: Trigger Maintenance actions
      description: |
        Performs maintenance actions on stake pools, such
        as triggering metadata garbage collection.

        Actions may not be instantaneous.
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiMaintenanceActionPostData
      responses: *responsesPostMaintenanceAction

  /wallets/{walletId}/delegation-fees:
    get:
      operationId: getDelegationFee
      tags: ["Stake Pools"]

      summary: Estimate Fee
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Estimate fee for joining or leaving a stake pool. Note that it is an
        estimation because a delegation induces a transaction for which coins
        have to be selected randomly within the wallet. Because of this randomness,
        fees can only be estimated.
      parameters:
        - *parametersWalletId
      responses: *responsesGetDelegationFee

  /stake-pools/*/wallets/{walletId}:
    delete:
      operationId: quitStakePool
      tags: ["Stake Pools"]
      summary: Quit
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Stop delegating completely. The wallet's stake will become inactive.

        > ⚠️  Disclaimer ⚠️
        >
        > This endpoint historically use to take a stake pool id as a path parameter.
        > However, retiring from delegation is ubiquitous and not tight to a particular
        > stake pool. For backward-compatibility reasons, sending stake pool ids as path
        > parameter will still be accepted by the server but new integrations are
        > encouraged to provide a placeholder asterisk `*` instead.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletPassphrase
      responses: *responsesQuitStakePool

  /stake-pools/{stakePoolId}/wallets/{walletId}:
    put:
      operationId: joinStakePool
      tags: ["Stake Pools"]
      summary: Join
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Delegate all (current and future) addresses from the given wallet to the given stake pool.

        <strong>Note:</strong> Bech32-encoded stake pool identifiers can vary in length.

      parameters:
        - *parametersStakePoolId
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletPassphrase
      responses: *responsesJoinStakePool

  /wallets/{walletId}/coin-selections/random:
    post:
      operationId: selectCoins
      tags: ["Coin Selections"]
      summary: Random
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Select coins to cover the given set of payments.

        Uses the <a href="https://iohk.io/blog/self-organisation-in-coin-selection/">
        Random-Improve coin selection algorithm</a>.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSelectCoinsData
      responses: *responsesSelectCoins

  /wallets/{walletId}/migrations:
    post:
      operationId: migrateShelleyWallet
      tags: ["Migrations"]
      summary: Migrate
      description: |
        <p align="right">status: <strong>disabled</strong></p>
        <strong>⚠️IMPORTANT⚠️</strong> This endpoint has been temporarily disabled with the introduction of multi-assets UTxO. It will be enabled again soon.

        <hr/>
        Migrate the UTxO balance of this wallet to the given set of addresses.

        This operation will attempt to transfer as much of the wallet's balance
        as possible to the given set of addresses, by creating and submitting
        as many transactions as may be necessary to migrate the entire balance.

        In order to minimize the total transaction fee required, UTxO entries
        are coalesced together to the greatest extent possible in the resulting
        transactions. No attempt is made to preserve the wallet's UTxO
        distribution.

        This operation is performed on a best-effort basis. If there is
        insufficient ada available to pay for the entire UTxO set to be
        migrated, then only a subset of the wallet's UTxO set will be migrated.

        A typical use of this operation would be to move all funds from an old
        wallet to a new wallet, by providing addresses that belong to the new
        wallet.
      parameters:
        - <<: *parametersWalletId
          name: walletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiShelleyWalletMigrationPostData
      responses: *responsesMigrateWallet

  /wallets/{walletId}/migrations/plan:
    post:
      operationId: createShelleyWalletMigrationPlan
      tags: ["Migrations"]
      summary: Create a migration plan
      description: |
        <p align="right">status: <strong>disabled</strong></p>
        <strong>⚠️IMPORTANT⚠️</strong> This endpoint has been temporarily disabled with the introduction of multi-assets UTxO. It will be enabled again soon.

        <hr/>
        Generate a plan for migrating the UTxO balance of this wallet to
        another wallet, without executing the plan.

        This operation generates a plan that transfers as much of the wallet's
        balance as possible, by creating as many selections as may be necessary
        to migrate the entire balance.  Each selection created is the basis for
        a transaction.

        In order to minimize the total transaction fee required, UTxO entries
        are coalesced together to the greatest extent possible in the resulting
        selections. No attempt is made to preserve the wallet's UTxO
        distribution.

        The plan is generated on a best-effort basis. If there is insufficient
        ada available to pay for the entire UTxO set to be migrated, then only
        a subset of the wallet's UTxO set will be included in the resultant
        plan.
      parameters:
        - <<: *parametersWalletId
          name: walletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletMigrationPlanPostData
      responses: *responsesCreateWalletMigrationPlan

  /byron-wallets:
    post:
      operationId: postByronWallet
      tags: ["Byron Wallets"]
      summary: Restore
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Restore a Byron wallet from a mnemonic sentence or encrypted root private key (deprecated).

          **⚠️ WARNING ⚠️**

          The construction of random wallet in itself is **deprecated**, in particular the restoration from an encrypted root private key.
          These endpoints exist to ease migrations from legacy software such as `cardano-sl` but should be avoided by new applications.
      requestBody:
        required: true
        content:
          application/json:
            schema: *SomeByronWalletPostData
      responses: *responsesPostByronWallet

    get:
      operationId: listByronWallets
      tags: ["Byron Wallets"]
      summary: List
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return a list of known Byron wallets, ordered from oldest to newest.
      responses: *responsesListByronWallets

  /byron-wallets/{walletId}/assets:
    get:
      operationId: listByronAssets
      tags: ["Byron Assets"]
      summary: List Assets
      description: |
        List all assets associated with the wallet, and their metadata
        if known.

        An asset is _associated_ with a wallet if it is involved in a
        transaction of the wallet.
      parameters:
        - *parametersWalletId
      responses: *responsesListAssets

  /byron-wallets/{walletId}/assets/{policyId}/{assetName}:
    get:
      operationId: getByronAsset
      tags: ["Byron Assets"]
      summary: Get Asset
      description: |
        Fetch a single asset from its `policy_id` and `asset_name`,
        with its metadata if any.

        The asset must be associated with the wallet.
      parameters:
        - *parametersWalletId
        - *parametersPolicyId
        - *parametersAssetName
      responses: *responsesGetAsset

  /byron-wallets/{walletId}/assets/{policyId}:
    get:
      operationId: getByronAssetDefault
      tags: ["Byron Assets"]
      summary: Get Asset (empty name)
      description: |
        Fetch the the asset from `policy_id` with an empty name.

        The asset must be associated with the wallet.
      parameters:
        - *parametersWalletId
        - *parametersPolicyId
      responses: *responsesGetAsset

  /byron-wallets/{walletId}/statistics/utxos:
    get:
      operationId: getByronUTxOsStatistics
      tags: ["Byron Wallets"]
      summary: UTxO Statistics
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return the UTxOs distribution across the whole wallet, in the form of a histogram.

        ```
             │
         100 ─
             │
             │                                 ┌───┐
          10 ─                         ┌───┐   │   │                   ┌───┐
             │                 ┌───┐   │   │   │   │                   │   │
             │                 │   │   │   │   │   │   ┌───┐           │   │
           1 ─ ┌───┐           │   │   │   │   │   │   │   │           │   │
             │ │   │           │   │   │   │   │   │   │   │           │   │
             │ │   │ │       │ │   │ │ │   │ ╷ │   │ ╷ │   │ ╷       ╷ │   │
             └─┘   └─│───────│─┘   └─│─┘   └─│─┘   └─│─┘   └─│───────│─┘   └────
                   10μ₳    100μ₳   1000μ₳   0.1₳    1₳      10₳     100₳
        ```
      parameters:
        - *parametersWalletId
      responses: *responsesGetUTxOsStatistics

  /byron-wallets/{walletId}:
    get:
      operationId: getByronWallet
      tags: ["Byron Wallets"]
      summary: Get
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return information about a Byron wallet.
      parameters:
        - *parametersWalletId
      responses: *responsesGetByronWallet

    delete:
      operationId: deleteByronWallet
      tags: ["Byron Wallets"]
      summary: Delete
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Delete a Byron wallet.
      parameters:
        - *parametersWalletId
      responses: *responsesDeleteWallet

    put:
      operationId: putByronWallet
      tags: ["Byron Wallets"]
      summary: Update Metadata
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletPutData
      responses: *responsesPutWallet

  /byron-wallets/{walletId}/passphrase:
    put:
      operationId: putByronWalletPassphrase
      tags: ["Byron Wallets"]
      summary: Update Passphrase
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiByronWalletPutPassphraseData
      responses: *responsesPutWalletPassphrase

  /byron-wallets/{walletId}/addresses:
      post:
        operationId: createAddress
        tags: ["Byron Addresses"]
        summary: Create Address
        description: |
          <p align="right">status: <strong>stable</strong></p>

          ⚠️  This endpoint is available for `random` wallets only. Any
          attempt to call this endpoint on another type of wallet will result in
          a `403 Forbidden` error from the server.
        parameters:
          - *parametersWalletId
        requestBody:
          required: true
          content:
            application/json:
              schema: *ApiPostRandomAddressData
        responses: *responsesPostRandomAddress

      get:
        operationId: listByronAddresses
        tags: ["Byron Addresses"]
        summary: List
        description: |
          <p align="right">status: <strong>stable</strong></p>

          Return a list of known addresses, ordered from newest to oldest for sequential wallets.
          Arbitrarily ordered for random wallets.
        parameters:
          - *parametersWalletId
          - *parametersAddressState
        responses: *responsesListAddresses

      put:
        operationId: importAddresses
        tags: ["Byron Addresses"]
        summary: Import Addresses
        description: |
          <p align="right">status: <strong>stable</strong></p>

          ⚠️  This endpoint is available for `random` wallets only. Any
          attempt to call this endpoint on another type of wallet will result in
          a `403 Forbidden` error from the server.
        parameters:
          - *parametersWalletId
        requestBody:
          required: true
          content:
            application/json:
              schema: *ApiPutAddressesData
        responses: *responsesPutRandomAddresses

  /byron-wallets/{walletId}/addresses/{addressId}:
      put:
        operationId: importAddress
        tags: ["Byron Addresses"]
        summary: Import Address
        description: |
          <p align="right">status: <strong>stable</strong></p>

          ⚠️  This endpoint is available for `random` wallets only. Any
          attempt to call this endpoint on another type of wallet will result in
          a `403 Forbidden` error from the server.
        parameters:
          - *parametersWalletId
          - *parametersAddressId
        responses: *responsesPutRandomAddress

  /byron-wallets/{walletId}/payment-fees:
    post:
      operationId: postByronTransactionFee
      tags: ["Byron Transactions"]
      summary: Estimate Fee
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Estimate fee for the transaction.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiPostTransactionFeeDataByron
      responses: *responsesPostTransactionFee

  /byron-wallets/{walletId}/transactions:
    post:
      operationId: postByronTransaction
      tags: ["Byron Transactions"]
      summary: Create
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Create and send transaction from the wallet.
      parameters:
        - *parametersWalletId
      requestBody:
          required: true
          content:
            application/json:
              schema: *ApiPostTransactionDataByron
      responses: *responsesPostTransaction

    get:
      operationId: listByronTransactions
      tags: ["Byron Transactions"]
      summary: List
      description: |
        <p align="right">status: <strong>stable</strong></p>

        List all incoming and outgoing transactions for the given wallet.
      parameters:
        - *parametersWalletId
        - *parametersStartDate
        - *parametersEndDate
        - *parametersSortOrder
      responses: *responsesListTransactions

  /byron-wallets/{walletId}/transactions/{transactionId}:
    get:
      operationId: getByronTransaction
      tags: ["Byron Transactions"]
      summary: Get
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Get transaction by id.
      parameters:
        - *parametersWalletId
        - *parametersTransactionId
      responses: *responsesGetTransaction

    delete:
      operationId: deleteByronTransaction
      tags: ["Byron Transactions"]
      summary: Forget
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Forget pending Byron transaction. Importantly, a transaction, when sent,
        cannot be cancelled. One can only request forgetting about it
        in order to try spending (concurrently) the same UTxO in another
        transaction. But, the transaction may still show up later in a block
        and therefore, appear in the wallet.
      parameters:
        - *parametersWalletId
        - *parametersTransactionId
      responses: *responsesDeleteTransaction

  /byron-wallets/{walletId}/coin-selections/random:
    post:
      operationId: byronSelectCoins
      tags: ["Byron Coin Selections"]
      summary: Random
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Select coins to cover the given set of payments.

        Uses the <a href="https://iohk.io/blog/self-organisation-in-coin-selection/">
        Random-Improve coin selection algorithm</a>.

        <b>Note: </b> Not supported for Byron random wallets.

      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiByronSelectCoinsData
      responses: *responsesSelectCoins

  /byron-wallets/{walletId}/migrations:
    post:
      operationId: migrateByronWallet
      tags: ["Byron Migrations"]
      summary: Migrate
      description: |
        <p align="right">status: <strong>disabled</strong></p>
        <strong>⚠️IMPORTANT⚠️</strong> This endpoint has been temporarily disabled with the introduction of multi-assets UTxO. It will be enabled again soon.

        <hr/>
        Migrate the UTxO balance of this wallet to the given set of addresses.

        This operation will attempt to transfer as much of the wallet's balance
        as possible to the given set of addresses, by creating and submitting
        as many transactions as may be necessary to migrate the entire balance.

        In order to minimize the total transaction fee required, UTxO entries
        are coalesced together to the greatest extent possible in the resulting
        transactions. No attempt is made to preserve the wallet's UTxO
        distribution.

        This operation is performed on a best-effort basis. If there is
        insufficient ada available to pay for the entire UTxO set to be
        migrated, then only a subset of the wallet's UTxO set will be migrated.

        A typical use of this operation would be to move all funds from an old
        wallet to a new wallet, by providing addresses that belong to the new
        wallet.
      parameters:
        - <<: *parametersWalletId
          name: walletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiByronWalletMigrationPostData
      responses: *responsesMigrateWallet

  /byron-wallets/{walletId}/migrations/plan:
    post:
      operationId: createByronWalletMigrationPlan
      tags: ["Byron Migrations"]
      summary: Create a migration plan
      description: |
        <p align="right">status: <strong>disabled</strong></p>
        <strong>⚠️IMPORTANT⚠️</strong> This endpoint has been temporarily disabled with the introduction of multi-assets UTxO. It will be enabled again soon.

        <hr/>
        Generate a plan for migrating the UTxO balance of this wallet to
        another wallet, without executing the plan.

        This operation generates a plan that transfers as much of the wallet's
        balance as possible, by creating as many selections as may be necessary
        to migrate the entire balance.  Each selection created is the basis for
        a transaction.

        In order to minimize the total transaction fee required, UTxO entries
        are coalesced together to the greatest extent possible in the resulting
        selections. No attempt is made to preserve the wallet's UTxO
        distribution.

        The plan is generated on a best-effort basis. If there is insufficient
        ada available to pay for the entire UTxO set to be migrated, then only
        a subset of the wallet's UTxO set will be included in the resultant
        plan.
      parameters:
        - <<: *parametersWalletId
          name: walletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiWalletMigrationPlanPostData
      responses: *responsesCreateWalletMigrationPlan

  /network/information:
    get:
      operationId: getNetworkInformation
      tags: ["Network"]
      summary: Information
      description: |
        <p align="right">status: <strong>stable</strong></p>
      responses: *responsesGetNetworkInformation

  /network/clock:
    get:
      operationId: getNetworkClock
      tags: ["Network"]
      summary: Clock
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - <<: *parametersForceNtpCheck
          name: forceNtpCheck
      responses: *responsesGetNetworkClock

  /network/parameters:
    get:
      operationId: getNetworkParameters
      tags: ["Network"]
      summary: Parameters
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Returns the set of network parameters for the current epoch.
      responses: *responsesGetNetworkParameters

  /proxy/transactions:
    post:
      operationId: postExternalTransaction
      tags: ["Proxy"]
      summary: Submit External Transaction
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Submits a transaction that was created and signed outside of cardano-wallet.

        NOTE: Unlike the postTransaction endpoint, there are no
        guarantees that a transaction accepted by this endpoint will
        actually be included in the chain. It's up to the caller to
        retry submission until the transaction is confirmed.
      requestBody:
        content:
          application/octet-stream:
            schema: *signedTransactionBlob
      responses: *responsesPostExternalTransaction

  /addresses/{addressId}:
    get:
      operationId: inspectAddress
      tags: ["Addresses"]
      summary: Inspect Address
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Give useful information about the structure of a given address.
      parameters:
        - *parametersAddressId
      responses: *responsesInspectAddress

  /addresses:
    post:
      operationId: postAnyAddress
      tags: ["Addresses"]
      summary: Construct Address
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Construct any address by specyfying credential for payment or delegation.

        In Cardano, Addresses are made of three parts:

        ```
        *---------*---------*-----------*
        | NETWORK | PAYMENT | DELEGATION |
        *---------*---------*-----------*
        ```

        The `NETWORK` part allows for distinguishing addresses between different networks like the mainnet or the testnet. It is implicitly
        handled by the server without you having to worry about it. The `PAYMENT` and `DELEGATION` parts however can be constructed similarly, using
        either:

        - A public key
        - A script

        The script itself is either constructed out of a public key, one of two timelocks, or one of the three following primitives:

        - all
        - any
        - some

        The timelock can determine validity as respect to the slot. `active_from slot` means the script is valid from the specified slot
        and onward. `active_until slot` means the script is valid until (not included) the specified slot.

        Each of which contains one or more script(s) that can be either keys or primitives, and so on. Schematically:

        ```
                                           ┏─────────┓
        SCRIPT = ──┬───────────────────────┤ pub key ├─────────────────────┬──
                   │                       ┗─────────┛                     │
                   │                       ┏──────────────────┓            │
                   ├───────────────────────┤ ACTIVE_FROM slot ├──── ───────┤
                   │                       ┗──────────────────┛            │
                   │                       ┏───────────────────┓           │
                   ├───────────────────────┤ ACTIVE_UNTIL slot ├───────────┤
                   │                       ┗───────────────────┛           │
                   │                                                       │
                   │  ╭─────╮   ╭────────╮                                 │
                   ├──┤ ALL ├───┤ SCRIPT ├─┬───────────────────────────────┤
                   │  ╰─────╯ ^ ╰────────╯ │                               │
                   │          │   ╭───╮    │                               │
                   │          └───┤ , ├────┘                               │
                   │              ╰───╯                                    │
                   │  ╭─────╮   ╭────────╮                                 │
                   ├──┤ ANY ├───┤ SCRIPT ├─┬───────────────────────────────┤
                   │  ╰─────╯ ^ ╰────────╯ │                               │
                   │          │   ╭───╮    │                               │
                   │          └───┤ , ├────┘                               │
                   │              ╰───╯                                    │
                   │  ╭──────╮ ╭──────────╮ ┏───┓ ╭──────╮   ╭────────╮    │
                   └──┤ SOME ├─┤ AT_LEAST ├─┤ n ├─┤ FROM ├───┤ SCRIPT ├─┬──┘
                      ╰──────╯ ╰──────────╯ ┗───┛ ╰──────╯ ^ ╰────────╯ │
                                                           │   ╭───╮    │
                                                           └───┤ , ├────┘
                                                               ╰───╯
        ```

      requestBody:
        content:
          application/json:
            schema: *ApiAddressData
      responses: *responsesPostAnyAddress

  /settings:
    put:
      operationId: putSettings
      tags: ["Settings"]
      summary: Update settings
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Overwrite current settings.
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSettingsPutData
      responses: *responsesPutSettings

    get:
      operationId: getSettings
      tags: ["Settings"]
      summary: Get settings
      description: |
        <p align="right">status: <strong>stable</strong></p>

        Return the current settings.
      responses: *responsesGetSettings

  /smash/health:
    get:
      operationId: getCurrentSmashHealth
      tags: ["Utils"]
      summary: Current SMASH health
      description: |
        Get health status of the currently active SMASH server.
      parameters:
        - in: query
          name: url
          schema: *ApiSmashServer
          required: false
          description: check this url for health instead of the currently configured one
      responses: *responsesGetSmashHealth

  /shared-wallets:
    post:
      operationId: postSharedWallet
      tags: ["Shared Wallets"]
      summary: Create
      description: |
        <p align="right">status: <strong>⚠ under development</strong></p>

        Create a shared wallet from an account public key, its index and script templates.
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSharedWalletPostData
      responses: *responsesPostSharedWallet

  /shared-wallets/{walletId}:
    get:
      operationId: getSharedWallet
      tags: ["Shared Wallets"]
      summary: Get
      description: |
        <p align="right">status: <strong>⚠ under development</strong></p>
      parameters:
        - *parametersWalletId
      responses: *responsesGetSharedWallet

    delete:
      operationId: deleteSharedWallet
      tags: ["Shared Wallets"]
      summary: Delete
      description: |
        <p align="right">status: <strong>stable</strong></p>
      parameters:
        - *parametersWalletId
      responses: *responsesDeleteWallet

  /shared-wallets/{walletId}/payment-script-template:
    patch:
      operationId: patchSharedWalletInPayment
      tags: ["Shared Wallets"]
      summary: Update Payment
      description: |
        <p align="right">status: <strong>⚠ under development</strong></p>
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSharedWalletPatchData
      responses: *responsesPatchSharedWallet

  /shared-wallets/{walletId}/delegation-script-template:
    patch:
      operationId: patchSharedWalletInDelegation
      tags: ["Shared Wallets"]
      summary: Update Delegation
      description: |
        <p align="right">status: <strong>⚠ under development</strong></p>
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSharedWalletPatchData
      responses: *responsesPatchSharedWallet