swagger.yaml

openapi: 3.0.0
info:
  title: Cardano Wallet Backend API
  version: v2021-12-15
  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://input-output-hk.github.io/cardano-wallet/

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
  description: |
    A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes
    which represents an address on the Cardano blockchain.
    Sequences in Base58 encoding are expected to be legacy Byron addresses,
    whereas sequences in Bech32 encoding correspond to current Shelley addresses.

    For more details, see
    [CIP-0019 — Cardano addresses](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0019)
    .

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

x-txType: &txType
  type: string
  pattern: "^Tx AlonzoEra$"

x-txDescription: &txDescription
  description: A description of transaction
  type: string
  minLength: 0
  maxLength: 256
  example: "Asset minting transaction"

x-txInNode: &txInNode
  type: string
  pattern: "^[0-9abcdef]+#[0-9]+$"
  minLength: 66
  maxLength: 68
  example: 2f8cd2ef706e5500307636b8477198ee2f204c4181b53c507f46d195140493cb#1

x-dataHash: &dataHash
  type: string
  format: hex
  minLength: 64
  maxLength: 64
  example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756

x-stakePoolMetadataUrl: &stakePoolMetadataUrl
  description: |
    A URL to the stake pool's website.
  type: string
  format: uri
  pattern: "^https://.+"
  maxLength: 250

x-stakePoolMetadataHash: &stakePoolMetadataHash
  type: string
  format: hex
  minLength: 64
  maxLength: 64
  example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756

x-stakePoolOwner: &stakePoolOwner
  type: string
  format: bech32
  pattern: "^(ed25519_pk)1[0-9a-z]*$"

x-adaQuantity: &adaQuantity
  type: integer
  minimum: 0
  maximum: 45000000000000000

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

x-assetValueNode: &assetValueNode
  description:
     Map of asset values along with their quantities.
     assetName in field name is expected (max lenght 64-character hex-encoded text)
  type: object
  additionalProperties: *assetQuantity
  # Note: propertyNames pattern not supported in current OpenAPI version.
  # propertyNames:
  #   pattern: '^(assetName)$'
  example:
    - {"asset1": 12, "asset2": 33}

x-valueNode: &valueNode
  nullable: false
  oneOf:
    - <<: *adaQuantity
      title: ada coin
    - <<: *assetValueNode
      title: asset value

x-valueNodes: &valueNodes
  description:
     Map of values along with their quantities. Can be lovelace or asset.
     In the former case 'lovelace' name is expected.
     In the latter case assetPolicyId name is expected (56-character hex-encoded text)
  type: object
  additionalProperties: *valueNode
  # Note: propertyNames pattern not supported in current OpenAPI version.
  # propertyNames:
  #   pattern: '^(lovelace)|(assetPolicyId)$'
  example:
    - {"lovelace": 1423}
    - {"lovelace": 1423, "7191ae0e1286891fe5c027a5dc041b7401689938e18e14ec83cf74fb": {"asset1": 12, "asset2": 33}}

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

x-walletAccountXPubkey: &walletAccountXPubkey
  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: *walletAccountXPubkey
  # Note: propertyNames pattern not supported in current OpenAPI version.
  # propertyNames:
  #   pattern: '^(cosigner#)[0-9]+$'
  example:
    - {"cosigner#0": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1"}

x-self: &self
  type: string
  enum:
    - self

x-accountPubkeyOrSelf: &accountPubkeyOrSelf
  nullable: false
  oneOf:
    - <<: *walletAccountXPubkey
      title: public key
    - <<: *self
      title: self

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

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: "^((addr_shared_vkh)|(stake_shared_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-scriptTemplateEntry: &scriptTemplateEntry
  type: object
  required:
    - cosigners
    - template
  properties:
    cosigners: *cosignersEntry
    template: *ScriptTemplateValue

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

    - stake_shared_vkh1nqc00hvlc6cq0sfhretk0rmzw8dywmusp8retuqnnxzajtzhjg5

    - all:
      - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq
      - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp

    - any:
      - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq
      - all:
        - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq
        - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp

    - some:
        at_least: 2
        from:
        - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq
        - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp

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-assetMetadataDecimals: &assetMetadataDecimals
  type: integer
  description: |
    Defines a scaling factor for the asset of 10<sup>-n</sup>. The
    decimals value _n_ is therefore the number of digits after the
    decimal point for quantities of this token.

    It is up to API clients to use this metadata field to decimalize
    asset quantities before displaying to users. The wallet backend
    will always return unscaled token quantities as whole numbers.
  minimum: 0
  maximum: 255
  example: 2

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
    decimals: *assetMetadataDecimals
    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: string
  enum:
    - extended
    - non_extended

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.

    **IMPORTANT DISCLAIMER 2:** There is no way to `import` addresses generated outside (e.g. using cardano-addresses) into the wallet.
    Wallet only discovers transactions on its used and unused addresses that are within its currently seen `address_pool_gap`.
    Transactions on addresses that "belong" to the wallet but happen to be beyond its `address_pool_gap` will not be visible to the wallet.
    This is a technical limitation of the industry standard [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). See also [CIP-1852](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1852/CIP-1852.md).

  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-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 (possibly empty).
  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-assetMintedBurned: &assetMintedBurned
  type: object
  required:
    - policy_id
    - asset_name
    - quantity
  properties:
    policy_id: *assetPolicyId
    asset_name: *assetName
    quantity:
      type: integer
      minimum: 0

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-datum: &datum
  description: A datum hash.
  type: string
  format: hex
  maxLength: 64
  minLength: 64
  example: 16f30f4e8d665d53eb4ab6028bd0ac971809d514c92d423856bc91c49e928faf

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-transactionCollateral: &transactionCollateral
  description: |
    A list of transaction inputs used for collateral.
  type: array
  minItems: 0
  items:
    type: object
    required:
      - id
      - index
    properties:
      address: *addressId
      amount: *amount
      id: *transactionId
      index:
        type: integer
        minimum: 0

x-derivationSegment: &derivationSegment
  description: |
    An individual segment within a derivation path.

    The `H` suffix indicates a _Hardened_ child private key, which
    means that children of this key cannot be derived from the public
    key. Indices without a `H` suffix are called _Soft_.
  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-transactionOutputs: &transactionOutputs
  description: A list of target outputs with amount specified
  type: array
  minItems: 0
  items:
    type: object
    required:
      - address
      - amount
    properties:
      address: *addressId
      amount: *amount
      assets: *walletAssets

x-transactionNoAmountOutputs: &transactionNoAmountOutputs
  description: A list of target outputs without amounts specified
  type: array
  minItems: 0
  items:
    type: string
    <<: *addressId

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-delegationTarget: &delegationTarget
  <<: *stakePoolId
  description: A unique Stake-Pool identifier (present only if status = `delegating`)

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

x-certificate: &certificate
  description: |
    A delegation certificate belonging to wallet

    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-certificateNotOurs: &certificateNotOurs
  description: |
    A delegation certificate not belonging to wallet

    Only for 'join_pool' the 'pool' property is required.
  type: object
  required:
    - certificate_type
    - reward_account
  properties:
    certificate_type:
      type: string
      enum: ["join_pool_external", "quit_pool_external", "register_reward_account_external"]
    pool:
      <<: *stakePoolId
    reward_account:
      <<: *stakeAddress

x-otherCertificate: &otherCertificate
  type: object
  required:
    - certificate_type
  properties:
    certificate_type:
      type: string
      enum: ["mir", "genesis"]

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-ours: &ours
  type: string
  enum: ["ours"]
  description: |
    Used when withdrawal or output is ours.

x-transactionWithdrawalsGeneral: &transactionWithdrawalsGeneral
  description: |
     A list of withdrawals from stake addresses. Withdrawal belonging to the wallet
     is underlined.
  type: array
  minItems: 0
  items:
    type: object
    additionalProperties: false
    required:
      - stake_address
      - amount
    properties:
      stake_address: *stakeAddress
      amount: *amount
      context: *ours

x-softIndex: &softIndex
  type: integer
  minimum: 0
  maximum: 2147483647
  description: A soft derivation index.

x-multiDelegationAction: &multiDelegationAction
  description: |
    A delegation action for a given stake key denoted by its soft index.
    Pool id is only required for "join".
    Stake key index are required for both actions.
  oneOf:
    - type: object
      required:
        - join
      properties:
        join:
          type: object
          required:
            - pool
            - stake_key_index
          properties:
            pool: *stakePoolId
            stake_key_index: *derivationSegment
    - type: object
      required:
        - quit
      properties:
        quit:
          type: object
          required:
            - stake_key_index
          properties:
            stake_key_index: *derivationSegment

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

    A list of staking actions (joining, rejoining or leaving from stake pools).
  type: array
  minItems: 0
  items:
    <<: *multiDelegationAction

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-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
  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-transactionInputsOutsideWallet: &transactionInputsOutsideWallet
  description: |
    A transaction input not belonging to a given wallet.
  type: object
  required:
    - id
    - index
  properties:
    id: *transactionId
    index:
      type: integer
      minimum: 0

x-transactionInputsInsideWallet: &transactionInputsInsideWallet
  description: |
    A transaction input belonging to a given wallet.
  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-transactionInputsGeneral: &transactionInputsGeneral
  type: array
  minItems: 0
  items:
    oneOf:
      - <<: *transactionInputsOutsideWallet
        title: tx inputs without source not belonging to a given wallet
      - <<: *transactionInputsInsideWallet
        title: tx inputs belonging to a given wallet

x-transactionOutputsOutsideWallet: &transactionOutputsOutsideWallet
  description: |
     A transaction output not belonging to the wallet
  type: object
  required:
    - address
    - amount
  properties:
    address: *addressId
    amount: *amount
    assets: *walletAssets

x-transactionOutputsInsideWallet: &transactionOutputsInsideWallet
  description: |
     A transaction output not belonging to the wallet
  type: object
  required:
    - address
    - amount
    - derivation_path
  properties:
    address: *addressId
    amount: *amount
    assets: *walletAssets
    derivation_path: *derivationPath

x-transactionOutputsGeneral: &transactionOutputsGeneral
  type: array
  minItems: 0
  items:
    oneOf:
      - <<: *transactionOutputsOutsideWallet
        title: tx outputs not belonging to a given wallet
      - <<: *transactionOutputsInsideWallet
        title: tx outputs belonging to a given wallet

x-transactionResolvedCollateral: &transactionResolvedCollateral
  description: A list of transaction inputs used for collateral
  type: array
  items:
    type: object
    required:
      - id
      - index
      - address
      - amount
      - derivation_path
    properties:
      address: *addressId
      amount: *amount
      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-serialisedTransactionBase64: &serialisedTransactionBase64
  description: |
    The CBOR-encoded transaction, represented in base64 encoding.
    This always includes the transaction body and the witness set, even if the
    latter is empty.
  type: string
  format: base64

x-serialisedTransactionHex: &serialisedTransactionHex
  description: |
    The CBOR-encoded transaction, represented in hexadecimal encoding (base-16).
    This always includes the transaction body and the witness set, even if the
    latter is empty.
  type: string
  format: hex

x-serialisedTransactionEncoded: &serialisedTransactionEncoded
  description: |
    The CBOR-encoded transaction, represented in either hex or base64 encoding.
    This always includes the transaction body and the witness set, even if the
    latter is empty.
  type: string
  format: "base64|base16"

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

x-transactionBodyBlob: &transactionBodyBlob
  description: CBOR-encoded transaction body
  type: string
  format: binary

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

      ```
           *-----------*
      ---> |  PENDING  |----------------*
           *-----------*                |
                 |                      |
                 V                      V
           *-----------*          *-----------*
           |           |---------->  EXPIRED  |
           |           |  (ttl)   *-----------*
           | SUBMITTED |
           |           <----------------*
           |           |                |
           *-----------*           (rollback)
                  |                     |
             (in ledger)          *-----------*
                  |               |           |
                  *---------------> IN_LEDGER |
                                  |           |
                                  *-----------*
      ```
  type: string
  enum:
    - pending
    - submitted
    - 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-unspecified: &unspecified
  type: string
  enum:
    - unspecified

x-validityBound: &validityBound
  oneOf:
    - <<: *numberOfSeconds
      title: number of seconds
    - <<: *numberOfSlots
      title: number of slots
    - <<: *unspecified
      title: unspecified

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-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

x-collateralInputCount: &collateralInputCount
  type: integer
  minimum: 0
  example: 3

x-collateralPercentage: &collateralPercentage
  type: integer
  minimum: 0

x-maximumTokenBundleSize: &maximumTokenBundleSize
  type: object
  description: |
    The maximum size of a serialized `TokenBundle`. The concept was added in Mary where
    it was hard-coded to 4000 bytes. In Alonzo it was made an updateable protocol parameter (`_maxValSize`).
  required:
    - quantity
    - unit
  properties:
    quantity:
      type: number
      minimum: 0
      example: 4000
    unit:
      type: string
      enum:
        - byte

x-txScriptValidity: &txScriptValidity
  description: |
    Indicates whether the phase-2 monetary policy script (e.g. Plutus script)
    used in the transaction validated or not. Validity may be null if this
    transaction was from an era that doesn't support phase-2 monetary policy
    scripts, or is a pending transaction (we don't know if validation passed or
    failed until the transaction hits the ledger).
  nullable: true
  type: string
  enum:
    - valid
    - invalid

x-rationalAsPair: &rationalAsPair
  type: object
  required:
    - denominator
    - numerator
  properties:
    denominator:
      type: integer
      minimum: 0
    numerator:
      type: integer
      minimum: 0

x-rationalAsNumber: &rationalAsNumber
  type: integer
  minimum: 0

x-rational: &rational
  nullable: false
  oneOf:
    - <<: *rationalAsNumber
      title: rational as number
    - <<: *rationalAsPair
      title: rational as denominator and numerator

x-executionUnitPrices: &executionUnitPrices
  type: object
  description: |
    The price of time unit and memory unit used for calculating a fee of a script execution.
  required:
    - step_price
    - memory_unit_price
  properties:
    step_price: *rational
    memory_unit_price: *rational

#############################################################################
#                                                                           #
#                              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
          address_type:
            description: |
              The raw type field of the address.

              Details about possible address types are following (refer also to [cddl](https://github.com/input-output-hk/cardano-ledger/blob/master/eras/alonzo/test-suite/cddl-files/alonzo.cddl)).

              | address_type | binary prefix  |   Meaning                                                |
              | ------------ |:--------------:|:--------------------------------------------------------:|
              |      0       |  0000          |   base address: keyhash28,keyhash28                      |
              |      1       |  0001          |   base address: scripthash28,keyhash28                   |
              |      2       |  0010          |   base address: keyhash28,scripthash28                   |
              |      3       |  0011          |   base address: scripthash28,scripthash28                |
              |      4       |  0100          |   pointer address: keyhash28, 3 variable length uint     |
              |      5       |  0101          |   pointer address: scripthash28, 3 variable length uint  |
              |      6       |  0110          |   enterprise address: keyhash28                          |
              |      7       |  0111          |   enterprise address: scripthash28                       |
              |      8       |  1000          |   byron/icarus                                           |
              |      14      |  1110          |   reward account: keyhash28                              |
              |      15      |  1111          |   reward account: scripthash28                           |
            type: integer
            minimum: 0
            maximum: 15

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

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

    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
        alonzo: *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
        - maximum_collateral_input_count
        - maximum_token_bundle_size
      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
          description: |
            The minimum ada / Lovelace quantity required for new transaction outputs.

            It is only applicable for pure-ada outputs. If outputs contain other assets
            or a datum hash, the true minimum will be higher than this value.

            With Alonzo, `minimum_utxo_value` is not a real protocol parameter, but rather
            derived from from the Alonzo genesis `adaPerUTxOWord`.
        eras: *ApiEraInfo
        maximum_collateral_input_count:
          <<: *collateralInputCount
          description: |
            The maximum number of collateral inputs that can be used in a single
            transaction.
        minimum_collateral_percentage:
          <<: *collateralPercentage
          description: |
            The minimum required amount of collateral as a percentage of the
            total transaction fee.
        maximum_token_bundle_size:
          <<: *maximumTokenBundleSize
        execution_unit_prices:
          <<: *executionUnitPrices

    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
        collateral: *transactionResolvedCollateral
        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.

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

    ApiVerificationKeyShared: &ApiVerificationKeyShared
      type: string
      format: bech32
      pattern: "^((addr_shared_vk)|(stake_shared_vk)|(addr_shared_vkh)|(stake_shared_vkh))1[0-9a-z]*$"

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

    ApiAccountKeyShared: &ApiAccountKeyShared
      type: string
      format: bech32
      pattern: "^((acct_shared_xvk)|(acct_shared_vk))1[0-9a-z]*$"

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

    ApiSerialisedTransaction: &ApiSerialisedTransaction
      description: |
        An encoded transaction.
      required:
        - transaction
      properties:
        transaction: *serialisedTransactionBase64

    ApiSerialisedTransactionEncoded: &ApiSerialisedTransactionEncoded
      description: |
        An encoded transaction.
      required:
        - transaction
      properties:
        transaction: *serialisedTransactionEncoded

    ApiConstructTransaction: &ApiConstructTransaction
      type: object
      required:
        - transaction
        - coin_selection
        - fee
      properties:
        transaction: *serialisedTransactionBase64
        coin_selection: *ApiCoinSelection
        fee: *amount

    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
        collateral: *transactionCollateral
        withdrawals: *transactionWithdrawals
        mint: *transactionMint
        status: *transactionStatus
        metadata: *transactionMetadata
        script_validity: *txScriptValidity

    ApiInputsGeneral: &ApiInputsGeneral
      <<: *transactionInputsGeneral
      description: |
        Inputs that could be external or belong to the wallet.

    ApiOutputsGeneral: &ApiOutputsGeneral
      <<: *transactionOutputsGeneral
      description: |
        Outputs that could be external or belong to the wallet.

    ApiWithdrawalsGeneral: &ApiWithdrawalsGeneral
      <<: *transactionWithdrawalsGeneral
      description: |
        Withdrawals that could be external or belong to the wallet.

    ApiMintedAssets: &ApiMintedAssets
      description: |
        Assets minted (created).
        The act of minting assets provides value to a transaction.
      type: array
      minItems: 0
      items: *assetMintedBurned

    ApiBurnedAssets: &ApiBurnedAssets
      description: |
        Assets burned (destroyed).
        The act of burning assets consumes value from a transaction.
      type: array
      minItems: 0
      items: *assetMintedBurned

    ApiStakePoolMetadata: &ApiStakePoolMetadata
      type: object
      required:
        - url
        - hash
      properties:
        url: *stakePoolMetadataUrl
        hash: *stakePoolMetadataHash

    ApiRegisterPool: &ApiRegisterPool
      type: object
      required:
        - certificate_type
        - pool_id
        - pool_owners
        - pool_margin
        - pool_cost
        - pool_pledge
      properties:
        certificate_type:
          type: string
          enum: ["register_pool"]
        pool_id: *stakePoolId
        pool_owners:
          type: array
          minItems: 0
          items: *stakePoolOwner
        pool_margin: *stakePoolMargin
        pool_cost: *stakePoolCost
        pool_pledge: *stakePoolPledge
        pool_metadata: *ApiStakePoolMetadata

    ApiDeregisterPool: &ApiDeregisterPool
      type: object
      required:
        - certificate_type
        - pool_id
        - retirement_epoch
      properties:
        certificate_type:
          type: string
          enum: ["deregister_pool"]
        pool_id: *stakePoolId
        retirement_epoch: *epochNumber

    ApiCertificate: &ApiCertificate
      description: |
        Any certificate that could occur in an arbitrary transaction:
        might be related to delegation, pool activities, genesis or MIR.
      oneOf:
        - <<: *certificate
          title: delegation certificate belonging to the wallet
        - <<: *certificateNotOurs
          title: delegation certificate not belonging to the wallet
        - <<: *ApiRegisterPool
          title: pool registration certificate
        - <<: *ApiDeregisterPool
          title: pool deregistration certificate
        - <<: *otherCertificate
          title: genesis or MIR certificate

    ApiDecodedTransaction: &ApiDecodedTransaction
      type: object
      required:
        - id
        - fee
        - inputs
        - outputs
        - withdrawals
        - assets_minted
        - assets_burned
        - certificates
      properties:
        id: *transactionId
        fee: *amount
        inputs: *ApiInputsGeneral
        outputs: *ApiOutputsGeneral
        collateral: *ApiInputsGeneral
        withdrawals: *ApiWithdrawalsGeneral
        assets_minted: *ApiMintedAssets
        assets_burned: *ApiBurnedAssets
        certificates:
          type: array
          minItems: 0
          items: *ApiCertificate
        metadata: *transactionMetadata
        script_validity: *txScriptValidity

    x-txBody: &txBody
      oneOf:
        - <<: *serialisedTransactionBase64
          title: Serialized transaction body

    x-txWits: &txWitnesses
      type: array
      items: *serialisedTransactionBase64
      title: Serialized transaction witnesses

    ApiSignedTransaction: &ApiSignedTransaction
      <<: *ApiSerialisedTransaction
      description: |
        The result of signing a transaction (serialized and encoded).

    ApiSignedTransactionEncoded: &ApiSignedTransactionEncoded
      <<: *ApiSerialisedTransactionEncoded
      description: |
        The result of signing a transaction (serialized and encoded).

    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: *walletAccountXPubkey
        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
        - state
      properties:
        id: *walletId
        name: *walletName
        account_index: *derivationSegment
        address_pool_gap: *walletAddressPoolGap
        payment_script_template: *scriptTemplate
        delegation_script_template: *scriptTemplate
        state:
          type: object
          required:
            - status
          properties:
            status:
              description: |
                A pending shared wallet does not have a complete set
                of keys, so the only possible status is `incomplete`.
              type: string
              enum:
                - incomplete

    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: *scriptTemplateEntry
        delegation_script_template: *scriptTemplateEntry
        script_validation: *validationLevel

    ApiSharedWalletPostDataFromAccountPubX: &ApiSharedWalletPostDataFromAccountPubX
      type: object
      required:
        - name
        - account_public_key
        - account_index
        - payment_script_template
      properties:
        name: *walletName
        account_public_key: *walletAccountXPubkey
        account_index: *derivationSegment
        payment_script_template: *scriptTemplateEntry
        delegation_script_template: *scriptTemplateEntry
        script_validation: *validationLevel

    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
        metadata_error:
          type: string
          description: |
            If there was an error fetching metadata from the server,
            this will be set to one of `fetch` or `parse`, to indicate
            the kind of error.
          enum:
            - fetch
            - parse

    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 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.

    ApiWalletUtxoSnapshotEntry: &ApiWalletUtxoSnapshotEntry
      type: object
      required:
        - ada
        - ada_minimum
        - assets
      properties:
        ada:
          <<: *amount
          description: |
            The ada quantity associated with this UTxO entry.
        ada_minimum:
          <<: *amount
          description: |
            The minimum ada quantity permitted by the ledger for this UTxO
            entry.
        assets:
          <<: *walletAssets
          description: |
            The set of non-ada assets associated with this UTxO entry.

    ApiWalletUtxoSnapshot: &ApiWalletUtxoSnapshot
      type: object
      required:
        - entries
      properties:
        entries:
          type: array
          items: *ApiWalletUtxoSnapshotEntry
          minItems: 0
          description: |
            The complete set of UTxO entries associated with a wallet.

    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
        - format
      properties:
        passphrase: *walletPassphrase
        format: *keyExtended

    ApiPostAccountKeyDataWithPurpose: &ApiPostAccountKeyDataWithPurpose
      type: object
      required:
        - passphrase
        - format
      properties:
        passphrase: *walletPassphrase
        format: *keyExtended
        purpose: *derivationSegment

    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).

    ApiSignTransactionPostData: &ApiSignTransactionPostData
      type: object
      required:
        - passphrase
        - transaction
      properties:
        passphrase:
          <<: *lenientPassphrase
          description: The wallet's master passphrase.
        transaction: *serialisedTransactionEncoded

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

    # ADP-908 Deprecated
    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

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

    # ADP-910 Deprecated
    ApiPostTransactionFeeDataByron: &ApiPostTransactionFeeDataByron
      type: object
      required:
        - payments
      properties:
        payments: *transactionOutputs

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

    # ADP-910 Deprecated
    ApiPostRedemptionFeeData: &ApiPostRedemptionFeeData
      type: object
      required:
        - payments
        - withdrawal
      properties:
        payments: *transactionOutputs
        withdrawal: *transactionRedemptionRequest

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

    ApiValidityInterval: &ApiValidityInterval
      description: |
        <p>status: <strong>⚠ under development</strong></p>
      type: object
      required:
        - invalid_before
        - invalid_hereafter
      properties:
        invalid_before: *validityBound
        invalid_hereafter: *validityBound

    ApiPaymentDestination: &ApiPaymentDestination
      oneOf:
        - title: outputs with specified amounts
          <<: *transactionOutputs
        - title: outputs without amounts
          <<: *transactionNoAmountOutputs

    ApiConstructTransactionData: &ApiConstructTransactionData
      description: At least one field needs to be choosen
      type: object
      properties:
        payments: *ApiPaymentDestination
        withdrawal: *transactionWithdrawalRequestSelf
        metadata: *transactionMetadata
        mint: *transactionMint
        delegations: *transactionDelegations
        validity_interval: *ApiValidityInterval

    CredentialValue: *CredentialValue

    ScriptValue: *ScriptValue

    ScriptTemplateValue: *ScriptTemplateValue

    # https://github.com/input-output-hk/cardano-ledger/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)

    ApiOurStakeKey: &ApiOurStakeKey
      type: object
      required:
        - index
        - key
        - stake
        - reward_balance
        - delegation
      properties:
        index: *softIndex
        key: *stakeAddress
        stake: *amount
        reward_balance: *amount
        delegation: *ApiWalletDelegation

    ApiForeignStakeKey: &ApiForeignStakeKey
      type: object
      required:
        - key
        - stake
        - reward_balance
      properties:
        key: *stakeAddress
        stake: *amount
        reward_balance: *amount
    ApiNullStakeKey: &ApiNullStakeKey
      type: object
      required:
        - stake
      properties:
        stake: *amount
      description: |
        The absence of a stake key. The `stake` field shows how much of the wallet funds
        are not associated with an identifiable stake key.

        Most likely, these funds are associated with enterprise addresses lacking staking rights.
        But they /could/ also be associate with more rare types of addreses like pointer addresses.
    ApiStakeKeys: &ApiStakeKeys
      type: object
      required:
        - ours
        - foreign
        - "none"
      properties:
        ours:
          type: array
          items: *ApiOurStakeKey
          description: |
            Stake keys belonging to the wallet.
        foreign:
          type: array
          items: *ApiForeignStakeKey
          description: |
            Stake keys found in the wallet's UTxO, but does not belong to the wallet.

        "none": *ApiNullStakeKey

    ApiMintedBurnedInfo: &ApiMintedBurnedInfo
      type: object
      required:
        - monetary_policy_index
        - policy_id
        - asset_name
        - subject
        - script
      properties:
        monetary_policy_index: *derivationSegment
        policy_id: *assetPolicyId
        asset_name: *assetName
        subject: *assetFingerprint
        script:
          <<: *ScriptValue
          description: The script under which this asset was minted or burned.

    ApiMintedBurnedTransaction: &ApiMintedBurnedTransaction
      type: object
      required:
        - transaction
        - minted_burned
      properties:
        transaction:
          <<: *ApiTransaction
          description: Information about the mint/burn transaction submitted.
        minted_burned:
          type: array
          items: *ApiMintedBurnedInfo
          minItems: 1
          description: An entry for each unique asset minted and/or burned, containing helpful information.

    ApiAssetQuantity: &ApiAssetQuantity
      type: object
      required:
        - quantity
        - unit
      properties:
        quantity:
          type: integer
          example: 14
        unit:
          type: string
          enum:
            - assets

    ApiMintData: &ApiMintData
      type: object
      required:
        - receiving_address
        - amount
      properties:
        receiving_address: *addressId
        amount: *ApiAssetQuantity

    ApiBurnData: &ApiBurnData
      allOf:
        - *ApiAssetQuantity

    ApiMintBurnOperation: &ApiMintBurnOperation
      type: object
      oneOf:
        - title: "mint"
          properties:
            mint: *ApiMintData
        - title: "burn"
          properties:
            burn: *ApiBurnData

    ApiMintBurnData: &ApiMintBurnData
      type: object
      required:
        - asset_name
        - operation
      properties:
        monetary_policy_index:
          allOf:
            - *derivationSegment
            - type: string
              default: 0
        asset_name: *assetName
        operation: *ApiMintBurnOperation

    ApiPostMintBurnAssetData: &ApiPostMintBurnAssetData
      type: object
      required:
        - mint_burn
        - passphrase
      properties:
        mint_burn:
          type: array
          items: *ApiMintBurnData
          minItems: 1
        passphrase:
          <<: *lenientPassphrase
          description: The wallet's master passphrase.
        metadata: *transactionMetadata
        time_to_live: *transactionTTL

    ApiRedeemerSpending: &ApiRedeemerSpending
      type: object
      required:
        - purpose
        - data
        - input
      properties:
        purpose:
          type: string
          enum: ["spending"]
        data:
          type: string
          format: base16
        input:
          type: object
          required:
            - id
            - index
          properties:
            id: *transactionId
            index:
              type: integer
              minimum: 0

    ApiRedeemerMinting: &ApiRedeemerMinting
      type: object
      required:
        - purpose
        - data
        - policy_id
      properties:
        purpose:
          type: string
          enum: ["minting"]
        data:
          type: string
          format: base16
        policy_id:
          type: string
          format: hex
          maxLength: 56

    ApiRedeemerRewarding: &ApiRedeemerRewarding
      type: object
      required:
        - purpose
        - data
        - stake_address
      properties:
        purpose:
          type: string
          enum: ["rewarding"]
        data:
          type: string
          format: base16
        stake_address: *stakeAddress

    ApiRedeemer: &ApiRedeemer
      oneOf:
        - title: spending
          <<: *ApiRedeemerSpending

        - title: minting
          <<: *ApiRedeemerMinting

        - title: rewarding
          <<: *ApiRedeemerRewarding

    ApiBalanceTransactionPostData: &ApiBalanceTransactionPostData
      type: object
      required:
        - transaction
      properties:
        transaction: *serialisedTransactionEncoded
        inputs:
            description: A list of additional transaction inputs foreign to the wallet.
            type: array
            items:
              type: object
              required:
                - id
                - index
                - address
                - amount
                - assets
              properties:
                id: *transactionId
                index:
                  type: integer
                  minimum: 0
                address: *addressId
                amount: *amount
                datum: *datum
                assets: *walletAssets
        redeemers:
            description: A list of redeemers data with their purpose.
            type: array
            items: *ApiRedeemer


#############################################################################
#                                                                           #
#                               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

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

x-parametersDerivationHash: &parametersDerivationHash
  in: query
  name: hash
  schema:
    type: boolean
    default: false
  description: |
    Whether to return the key hash instead of the key.

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:
        Occurs when hardened derivation is required and soft index is used
        (without suffix 'H').
    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']

x-errTokensMintedButNotSpentOrBurned: &errTokensMintedButNotSpentOrBurned
  <<: *responsesErr
  title: tokens_minted_but_not_spent_or_burned
  properties:
    message:
      type: string
      description: |
        Returned when a user mints funds but does not spend or burn them all.
    code:
      type: string
      enum: ['tokens_minted_but_not_spent_or_burned']

# 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-errInsufficientCollateral: &errInsufficientCollateral
  <<: *responsesErr
  title: insufficient_collateral
  properties:
    message:
      type: string
      description: |
        May occur when the total balance of pure ada UTxOs in the wallet is
        insufficient to cover the minimum collateral amount required for a
        transaction requiring collateral.
    code:
      type: string
      enum: ['insufficient_collateral']

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-errSharedWalletScriptTemplateInvalid: &errSharedWalletScriptTemplateInvalid
  <<: *responsesErr
  title: shared_wallet_script_template_invalid
  properties:
    message:
      type: string
      description: |
        Returned when a user tries to create a shared wallet with script template
        that does not pass validation.
    code:
      type: string
      enum: ['shared_wallet_script_template_invalid']

# 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-errForeignTransaction: &errForeignTransaction
  <<: *responsesErr
  title: foreign_transaction
  properties:
    message:
      type: string
      description: Occurs when a transaction to be submitted does have neither input, output nor withdrawal belonging to a given wallet.
    code:
      type: string
      enum: ['foreign_transaction']

x-errMissingWitnessesInTransaction: &errMissingWitnessesInTransaction
  <<: *responsesErr
  title: missing_witnesses_in_transaction
  properties:
    message:
      type: string
      description: Occurs when a transaction to be submitted is not fully signed.
    code:
      type: string
      enum: ['missing_witnesses_in_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-errTransactionAlreadyBalanced: &errTransactionAlreadyBalanced
  <<: *responsesErr
  title: transaction_already_balanced
  properties:
    message:
      type: string
      description: |
        Occurs when a transaction is already balanced.
    code:
      type: string
      enum: ['transaction_already_balanced']

x-errRedeemerScriptFailure: &errRedeemerScriptFailure
  <<: *responsesErr
  title: redeemer_script_failure
  properties:
    message:
      type: string
      description: |
        Occurs when balancing transaction with failing scripts.
    code:
      type: string
      enum: ['redeemer_script_failure']

x-errRedeemerTargetNotFound: &errRedeemerTargetNotFound
  <<: *responsesErr
  title: redeemer_target_not_found
  properties:
    message:
      type: string
      description: |
        Occurs when balancing transaction with reedemers that point to unknown entities.
    code:
      type: string
      enum: ['redeemer_target_not_found']

x-errUnresolvedInputs: &errUnresolvedInputs
  <<: *responsesErr
  title: unresolved_inputs
  properties:
    message:
      type: string
      description: |
        The transaction contains foreign inputs which cannot be resolved.
    code:
      type: string
      enum: ['unknown_inputs']

x-errRedeemerInvalidData: &errRedeemerInvalidData
  <<: *responsesErr
  title: redeemer_invalid_data
  properties:
    message:
      type: string
      description: |
        Occurs when data in provided redeemers do not decode to valid Plutus data.
    code:
      type: string
      enum: ['redeemer_invalid_data']

x-errExistingKeyWitnesses: &errExistingKeyWitnesses
  <<: *responsesErr
  title: existing_key_witnesses
  properties:
    message:
      type: string
      description: |
        Occurs when trying to balance a transaction that already has key witnesses.
    code:
      type: string
      enum: ['existing_key_witnesses']

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-responsesListSharedWallets: &responsesListSharedWallets
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema:
          type: array
          items: *ApiSharedWallet

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-responsesGetWalletUtxoSnapshot: &responsesGetWalletUtxoSnapshot
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiWalletUtxoSnapshot

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:
            - <<: *errSharedWalletScriptTemplateInvalid
  201:
    description: Created
    content:
      application/json:
        schema: *ApiSharedWallet

x-responsesMintToken: &responsesMintToken
  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: *ApiMintedBurnedTransaction

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
            - <<: *errInsufficientCollateral
            - <<: *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

# ADP-908 Deprecated
x-responsesPostTransaction: &responsesPostTransaction
  <<: *responsesErr400
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errInvalidWalletType
            - <<: *errAlreadyWithdrawing
            - <<: *errUtxoTooSmall
            - <<: *errCannotCoverFee
            - <<: *errNotEnoughMoney
            - <<: *errInsufficientCollateral
            - <<: *errTransactionIsTooBig
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiTransaction

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

x-responsesSignTransaction: &responsesSignTransaction
  <<: *responsesErr400
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errNoRootKey
            - <<: *errWrongEncryptionPassphrase
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiSignedTransaction

x-responsesDecodedTransaction: &responsesDecodedTransaction
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiDecodedTransaction

x-responsesSubmitTransaction: &responsesSubmitTransaction
  <<: *responsesErr400
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiTxId
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errForeignTransaction
            - <<: *errMissingWitnessesInTransaction

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
            - <<: *errInsufficientCollateral
            - <<: *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-responsesGetShelleyKey: &responsesGetShelleyKey
  <<: *responsesErr400
  <<: *responsesErr404
  <<: *responsesErr406
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiVerificationKeyShelley

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

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

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

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

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

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

x-responsesListStakeKeys: &responsesListStakeKeys
  200:
    description: Ok
    content:
      application/json:
        schema: *ApiStakeKeys

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

x-responsesBalanceTransaction: &responsesBalanceTransaction
  400:
    description: Bad Request
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errBadRequest
            - <<: *errRedeemerScriptFailure
            - <<: *errRedeemerTargetNotFound
            - <<: *errRedeemerInvalidData
            - <<: *errUnresolvedInputs
  403:
    description: Forbidden
    content:
      application/json:
        schema:
          oneOf:
            - <<: *errInvalidWalletType
            - <<: *errAlreadyWithdrawing
            - <<: *errUtxoTooSmall
            - <<: *errCannotCoverFee
            - <<: *errNotEnoughMoney
            - <<: *errInsufficientCollateral
            - <<: *errTransactionIsTooBig
            - <<: *errTransactionAlreadyBalanced
            - <<: *errExistingKeyWitnesses
  <<: *responsesErr404WalletNotFound
  <<: *responsesErr406
  <<: *responsesErr415UnsupportedMediaType
  202:
    description: Accepted
    content:
      application/json:
        schema: *ApiSerialisedTransaction

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

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

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

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

  - 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

    post:
      operationId: mintBurnAssets
      tags: ["Assets"]
      summary: Mint/Burn
      description: |
        <p align="right">status: <strong>under development</strong></p>

        Mint and burn assets from the wallet.

        We only support the simplest of scripts: those which require a signature
        from a single key (known as the policy key). The policy key is generated
        from the HD wallet according to to draft CIP-1855
        (https://github.com/cardano-foundation/CIPs/blob/b2e9d02cb9a71ba9e754a432c78197428abf7e4c/CIP-1855/CIP-1855.md).

        Once the policy key is generated, cardano-wallet creates a script from
        that key, which we then mint or burn assets under.

        **⚠️ WARNING ⚠️**

        Please note that due to the fact that there is no physical access to
        policy keys under which assets are minted from the wallet it is
        currently not possible to add metadata of such assets into [Cardano Token Registry](https://github.com/cardano-foundation/cardano-token-registry).

      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              <<: *ApiPostMintBurnAssetData
      responses: *responsesMintToken

  /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 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}/utxo:
    get:
      operationId: getWalletUtxoSnapshot
      tags: ["Wallets"]
      summary: A snapshot of the wallet's UTxO set
      description: |
        Generate a snapshot of the wallet's UTxO set.

        This endpoint is intended for debugging purposes.
      parameters:
        - *parametersWalletId
      responses: *responsesGetWalletUtxoSnapshot

  /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
      # ADP-908 - Deprecated soon
      deprecated: false
      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
      # ADP-908 - Deprecated soon
      deprecated: false
      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}/transactions-construct:
    post:
      operationId: constructTransaction
      tags: ["Transactions New"]
      summary: Construct
      description: |
        <p align="right">status: <strong>under development</strong></p>

        Create a transaction to be signed from the wallet.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiConstructTransactionData
      responses: *responsesConstructTransaction

  /wallets/{walletId}/transactions-sign:
    post:
      operationId: signTransaction
      tags: ["Transactions New"]
      summary: Sign
      description: |
        <p align="right">status: <strong>under development</strong></p>

        Signs a serialised transaction, returning the modified
        transaction.

        This endpoint will add new witnesses using the keys available
        to this wallet. Any existing witnesses will remain in the
        witness set.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSignTransactionPostData
      responses: *responsesSignTransaction

  /wallets/{walletId}/transactions-decode:
    post:
      operationId: decodeTransaction
      tags: ["Transactions New"]
      summary: Decode
      description: |
        <p align="right">status: <strong>unstable</strong></p>

        Decode a serialized transaction.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSerialisedTransactionEncoded
      responses: *responsesDecodedTransaction

  /wallets/{walletId}/transactions-submit:
    post:
      operationId: submitTransaction
      tags: ["Transactions New"]
      summary: Submit
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Submit a transaction that was already created and signed.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSignedTransactionEncoded
      responses: *responsesPostExternalTransaction

  /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 Account Public Key
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Derive an account public key for any account index. For this key derivation to be possible,
        the wallet must have been created from mnemonic.

        It is possible to use the optional `purpose` field to override that branch of the derivation path
        with different hardened derivation index. If that field is omitted, the default purpose
        for Cardano wallets (`1852H`) will be used.

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

  /wallets/{walletId}/keys:
    get:
      operationId: getAccountKey
      tags: ["Keys"]
      summary: Get Account Public Key
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Retrieve the account public key of this wallet.

        To get an extended public key, instead of the public key,
        use query parameter `format=extended`. For non-extended public key
        use `format=non_extended` or omit query parameter.

      parameters:
        - *parametersWalletId
      responses: *responsesGetAccountKey

  /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.

        To get a hash of the public key, instead of the public key,
        use query parameter `hash=true`.

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

  /wallets/{walletId}/stake-keys:
    get:
      operationId: listStakeKeys
      tags: ["Stake Pools"]
      summary: List Stake Keys
      description: |
        <p align="right">status: <strong>Experimental</strong></p>

        List stake-keys relevant to the wallet, and how much ada is associated with each.
      parameters:
        - *parametersWalletId
      responses: *responsesListStakeKeys

  /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
      # ADP-908 - Deprecated soon
      deprecated: false
      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 tied 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: |
        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: |
        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

  /wallets/{walletId}/transactions-balance:
    post:
      operationId: balanceTransaction
      tags: ["Transactions New"]
      summary: Balance
      description: |
        <p align="right">status: <strong>under development</strong></p>
        Balance a transaction body of a given transaction, add needed inputs/outputs,
        so as the transaction can be signed from the wallet.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiBalanceTransactionPostData
      responses: *responsesBalanceTransaction

  /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 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}/utxo:
    get:
      operationId: getByronWalletUtxoSnapshot
      tags: ["Byron Wallets"]
      summary: A snapshot of the wallet's UTxO set
      description: |
        Generate a snapshot of the wallet's UTxO set.

        This endpoint is intended for debugging purposes.
      parameters:
        - *parametersWalletId
      responses: *responsesGetWalletUtxoSnapshot

  /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}/transactions-construct:
    post:
      operationId: constructByronTransaction
      tags: ["Byron Transactions New"]
      summary: Construct
      description: |
        <p align="right">status: <strong>unstable</strong></p>

        Create a transaction to be signed from the wallet.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiConstructTransactionData
      responses: *responsesConstructTransaction

  /byron-wallets/{walletId}/transactions-sign:
    post:
      operationId: signByronTransaction
      tags: ["Byron Transactions New"]
      summary: Sign
      description: |
        <p align="right">status: <strong>under development</strong></p>

        Signs a serialised transaction, returning the modified
        transaction.

        This endpoint will add new witnesses using the keys available
        to this wallet. Any existing witnesses will remain in the
        witness set.
      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSignTransactionPostData
      responses: *responsesSignTransaction

  /byron-wallets/{walletId}/payment-fees:
    post:
      operationId: postByronTransactionFee
      tags: ["Byron Transactions"]
      summary: Estimate Fee
      # ADP-908 - Deprecated soon
      deprecated: false
      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: |
        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: |
        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
      # ADP-908 - deprecated soon
      deprecated: false
      description: |
        <p align="right">status: <strong>stable</strong></p>

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

        NOTE: Unlike the `submitTransaction` 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 either an account public key and script
        templates or mnemonic and script templates.

      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSharedWalletPostData
      responses: *responsesPostSharedWallet

    get:
      operationId: listSharedWallets
      tags: ["Shared Wallets"]
      summary: List
      description: |
        <p align="right">status: <strong>⚠ under development</strong></p>

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

  /shared-wallets/{walletId}:
    get:
      operationId: getSharedWallet
      tags: ["Shared Wallets"]
      summary: Get
      description: |
        <p align="right">status: <strong>⚠ under development</strong></p>
        Get a shared wallet for a given wallet id.

      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>
        Update payment script template for a given shared wallet by
        updating/adding account public key for cosigner. Updating the
        shared wallet account key results in an error. Also updating is
        enabled only for pending shared wallet, ie., the wallet that has
        a missing account public key for any cosigner.

      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>
        Update delegation script template for a given shared wallet by
        updating/adding account public key for cosigner. Updating the
        shared wallet account key results in an error. Also updating is
        enabled only for pending shared wallet, ie., the wallet that has
        a missing account public key for any cosigner.

      parameters:
        - *parametersWalletId
      requestBody:
        required: true
        content:
          application/json:
            schema: *ApiSharedWalletPatchData
      responses: *responsesPatchSharedWallet

  /shared-wallets/{walletId}/keys/{index}:
    post:
      operationId: postAccountKeyShared
      tags: ["Shared Keys"]
      summary: Create Account Public Key
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Derive an account public key for any account index. For this key derivation to be possible,
        the wallet must have been created from mnemonic.

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

  /shared-wallets/{walletId}/keys:
    get:
      operationId: getAccountKeyShared
      tags: ["Shared Keys"]
      summary: Get Account Public Key
      description: |
        <p align="right">status: <strong>stable</strong></p>
        Retrieve the account public key of this shared wallet.

        To get an extended public key, instead of the public key,
        use query parameter `format=extended`. For non-extended public key
        use `format=non_extended` or omit query parameter.

      parameters:
        - *parametersWalletId
      responses: *responsesGetAccountSharedKey

  /shared-wallets/{walletId}/keys/{role}/{index}:
    get:
      operationId: getSharedWalletKey
      tags: ["Shared 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 for
        a shared wallet.

        To get a hash of the public key, instead of the public key,
        use query parameter `hash=true`.

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

  /shared-wallets/{walletId}/addresses:
    get:
      operationId: listSharedAddresses
      tags: ["Shared 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