externalDocs:
description: Need more? Click here to access our API guide and walkthrough.
url: https://cardano-foundation.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 a 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-witnessCount: &witnessCount
type: integer
description: The number of witnesses detected
minimum: 0
maximum: 127
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-genesis: &genesis
type: string
enum: ["from_genesis"]
example: "from_genesis"
x-tip: &tip
type: string
enum: ["from_tip"]
example: "from_tip"
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-chainPoint : &chainPoint
description: A reference to a particular block.
type: object
required:
- block_header_hash
- absolute_slot_number
properties:
block_header_hash: *blockId
absolute_slot_number: *absoluteSlot
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: µseconds
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: |
if: status == syncing
example:
status: ready
x-syncClockProgress: &syncClockProgress
type: object
required:
- status
properties:
status:
type: string
enum:
- unavailable
- pending
- available
offset:
<<: *microseconds
description: |
if: status == available
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 length 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-drepKeyHashNew: &drepKeyHashNew
type: string
format: bech32
example: drep_vkh15k6929drl7xt0spvudgcxndryn4kmlzpk4meed0xhqe254czjh2
description: |
DRep's verification key hash according to CIP-0105.
Replacing now deprecated 'drep' which is now used for drep credential.
pattern: "^(drep_vkh)1[0-9a-z]*$"
x-drepKeyHash: &drepKeyHash
type: string
format: bech32
example: drep1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm
description: |
DRep's key hash according to CIP-0105 (deprecated).
DRep credential which is special byte prepended to script/key hash payload.
Introduced by CIP-0129 and the byte prepended is 0x22 and 0x23 for
key and script hash, respectively.
pattern: "^(drep)1[0-9a-z]*$"
x-drepScriptHash: &drepScriptHash
type: string
format: bech32
example: drep1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm
description: |
DRep's script hash according to CIP-0105.
pattern: "^(drep_script)1[0-9a-z]*$"
x-walletAccountXPubkey: &walletAccountXPubkey
description: An extended account public key (public key + chain code)
type: string
format: hex
minLength: 128
maxLength: 128
example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1
x-sharedWalletAccountXPubkey: &sharedWalletAccountXPubkey
description: An extended account public key (public key + chain code) of shared wallet
type: string
format: bech32
pattern: "^(acct_shared_xvk)1[0-9a-z]*$"
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: *sharedWalletAccountXPubkey
# Note: propertyNames pattern not supported in current OpenAPI version.
# propertyNames:
# pattern: '^(cosigner#)[0-9]+$'
example:
- {"cosigner#0": "acct_shared_xvk1z8kc04yh544ksc9h2yhp7p6qwpf6syv5qnm8sgnhdne5z2esht5cwssxsec2wzw3nhxm2d9ph4s6ldmqdvxa0zuxzmukpajhyc7flug3te037"}
x-self: &self
type: string
enum:
- self
x-accountPubkeyOrSelf: &accountPubkeyOrSelf
nullable: false
oneOf:
- <<: *sharedWalletAccountXPubkey
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": "acct_shared_xvk1z8kc04yh544ksc9h2yhp7p6qwpf6syv5qnm8sgnhdne5z2esht5cwssxsec2wzw3nhxm2d9ph4s6ldmqdvxa0zuxzmukpajhyc7flug3te037"}
- {"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-oneChangeAddressMode: &oneChangeAddressMode
type: boolean
default: false
x-restorationMode: &restorationMode
description: |
The wallet restoration mode determines since when the wallet should
be restored from the blockchain.
cardano-wallet uses so-called `ChainSync` protocol under the hood to
scan the chain and restore its state from blocks and transactions.
[Ogmios](https://ogmios.dev/mini-protocols/local-chain-sync/) documentation provides a detailed
explanation of this underlying process.
oneOf:
- title: Restore from genesis
description: |
Restore the wallet from the genesis block. This will cause the wallet
to be restored from the very beginning of the blockchain, which is
expected to take a long time (several hours on mainnet).
<<: *genesis
- title: Restore from tip
description: |
Restore the wallet from the tip of the blockchain. The wallet queries
the current tip of the chain and then starts synchronizing from that point.
It waits for the _next block_ to appear before returning a result, which
on _mainnet_ will take an average of 30 seconds.
<<: *tip
- title: Restore from block
description: |
Restore the wallet after a specific _point_ identified by a block hash and
slot number. Note that any transaction which is part of that specified block
won't be restored.
<<: *chainPoint
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-scriptHash: &scriptHash
description: A script hash - 28 bytes
type: string
format: bech32
pattern: "^(script)1[0-9a-z]*$"
example:
- script1gr69m385thgvkrtspk73zmkwk537wxyxuevs2u9cukglvtlkz4k
x-scriptIntegrityHash: &scriptIntegrityHash
description: A script data integrity hash - 32 bytes
type: string
format: bech32
pattern: "^(script_data)1[0-9a-z]*$"
example:
- script_data16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d
x-extraSignatureHash: &extraSignatureHash
description: An extra signature hash - 28 bytes
type: string
format: bech32
pattern: "^(req_signer_vkh)1[0-9a-z]*$"
example:
- addr_keyhash1gr69m385thgvkrtspk73zmkwk537wxyxuevs2u9cukglvtlkz4k
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-credentialExtendedPubKey: &credentialExtendedPubKey
description: An extended public key (public key with chain code) for credential - 64 bytes
type: string
format: bech32
pattern: "^((addr_xvk)|(stake_xvk))1[0-9a-z]*$"
example:
- stake_xvk1qqqqzqqpqyqqzqgpqyqszqgpqqqqzqgpqqqqqqqpqyqqzqgqqqqqqqgpqqqqqqgqqyqszqqpqyqsqqqqqyqszqqqqqqqqqqpqqqqzqqgjanje
- addr_xvk1qyqqqqgqqyqsqqgqqyqsqqgqqqqszqqpqyqsqqgqqqqqqqgqqyqqqqqpqqqsqqqpqyqszqqpqqqszqgpqqqqzqgpqqqqqqqqqqqsqqqptg5dh
x-credentialKeyHash: &credentialKeyHash
description: A key hash for credential - 28 bytes
type: string
format: bech32
pattern: "^((addr_vkh)|(stake_vkh))1[0-9a-z]*$"
example:
- stake_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq
- addr_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq
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' coefficient is positive
* 'all', 'any' are non-empty and `'at_least' has no less elements in the list
than the coefficient 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)|(policy_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
# ScriptValueGeneral allows any key hash prefix, used in decoded transactions
# where scripts can come from any source (not just shared wallets)
x-ScriptValueGeneral: &ScriptValueGeneral
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)|(addr_vkh)|(stake_vkh)|(policy_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/ScriptValueGeneral"
- 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/ScriptValueGeneral"
- 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/ScriptValueGeneral"
- 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
- <<: *credentialExtendedPubKey
title: extended public key
- <<: *credentialKeyHash
title: key hash
- <<: *script
title: script
- <<: *scriptHash
title: script hash
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-n. 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-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
encryption_method:
description: |
The scheme used to protect the wallet's root key in storage.
Absent on wallets that have no stored passphrase (e.g. watch-only wallets).
type: string
enum:
- scrypt
- pbkdf2-hmac-sha512
- argon2id-v2
example: argon2id-v2
x-walletPassphraseInfoLegacy :: &walletPassphraseInfoLegacy
description: Information about the wallet's passphrase
type: object
required:
- last_updated_at
properties:
last_updated_at: *date
encryption_method:
description: |
The scheme used to protect the wallet's root key in storage.
Absent on wallets that have no stored passphrase.
type: string
enum:
- scrypt
- pbkdf2-hmac-sha512
example: pbkdf2-hmac-sha512
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: |
if: status == in_ledger
Absolute time at which the transaction was inserted in a block.
<<: *blockReference
x-transactionExpiresAt: &transactionExpiresAt
description: |
if: status == pending OR status == expired
Absolute time and slot at which the pending transaction TTL (time to live) will lapse.
<<: *slotReference
x-transactionPendingSince: &transactionPendingSince
description: |
if: status == pending
The point in time at which a transaction became pending.
<<: *blockReference
x-transactionDepth: &transactionDepth
description: |
if: status == in_ledger
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-referenceInput: &referenceInput
description: |
A reference input.
type: object
required:
- id
- index
properties:
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 amounts specified.
When creating a new transaction, the wallet software ensures that all
user-specified transaction outputs have ada amounts that satisfy the ledger
minimum UTxO rule:
- If a user-specified transaction output has an ada `amount` that is
**zero**, the wallet software will automatically assign a minimal amount
of ada to the output so that it satisfies the ledger minimum UTxO rule.
- If a user-specified transaction output has an ada `amount` that is
**non-zero**, the wallet software will verify that the specified amount
is large enough to satisfy the ledger minimum UTxO rule. If the amount is
not large enough, the wallet software will return a `utxo_too_small`
error, together with a revised ada amount that does satisfy the minimum
UTxO rule.
type: array
minItems: 0
items:
type: object
required:
- address
- amount
properties:
address: *addressId
amount: *amount
assets: *walletAssets
x-transactionCollateralOutputs: &transactionCollateralOutputs
description: A list of collateral return outputs with amounts specified.
type: array
minItems: 0
maxItems: 1
items:
type: object
required:
- address
- amount
properties:
address: *addressId
amount: *amount
assets: *walletAssets
x-delegationAction: &delegationAction
description: |
A delegation action.
Pool id is only required for "join".
type: object
required:
- action
properties:
action:
type: string
enum: ["quit", "join"]
pool: *stakePoolId
x-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_beneficial` error.
withdrawal field | reward balance | result
--- | --- | ---
any recovery phrase | too small | x Error 403 `withdrawal_not_beneficial`
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: |
status: stable
A list of staking actions (joining, rejoining or leaving from stake pools).
Using '0H' stake key index is supported at this moment. This will change with
multi-account support.
Only one delegation action can be used.
type: array
minItems: 0
items:
<<: *multiDelegationAction
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-transactionCollateralOutputsGeneral: &transactionCollateralOutputsGeneral
type: array
minItems: 0
maxItems: 1
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.
# with oneOf we get errors about the 2 schema being both valid
# anyOf seems broken trying to find properties
anyOf:
- type: object
title: full
nullable: true
additionalProperties:
$ref: "#/components/schemas/TransactionMetadataValue"
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 } }] }
- type: object
title: simple
nullable: true
additionalProperties:
$ref: "#/components/schemas/TransactionMetadataValueNoSchema"
example:
0: "cardano"
1: 14
2: [14, 42 , "1337" ]
3: {"key1": "value" , "key2": 42 }
# Note: propertyNames pattern not supported in current OpenAPI version.
# propertyNames:
# pattern: '^[0-9]+$'
x-encryptionMethod: &encryptionMethod
type: string
enum:
- basic
x-encryptMetadata: &encryptMetadata
description: |
If used then metadata in a transaction is going to be encrypted by
AES 256 using CBC mode which is a default method (called base).
PBKDF2 password stretching is used to get a 32-byte secret key and a 16-byte
initialization vector required in the cipher.
PBKDF2 encryption algorithm using HMAC with the SHA256 hash algorithm is employed,
and 10000 iterations to get key and iv pair are used.
Cipher algorithm uses 8-byte salt, PKCS#7 padding as specified in
https://datatracker.ietf.org/doc/html/rfc5652#section-6.3 is applied.
Only metadata value under `msg` field is encrypted. If `msg` field is missing error
will be emitted.
Metadata encryption is in accordance to CIP 83 (https://cips.cardano.org/cips/cip83/).
type: object
required:
- passphrase
properties:
method: *encryptionMethod
passphrase: *lenientPassphrase
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-validityBound: &validityBound
oneOf:
- <<: *numberOfSeconds
title: number of seconds
- <<: *numberOfSlots
title: number of slots
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: |
if: status == available
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
- voting
- delegating_and_voting
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: number # NOTE: intended to be 'integer', but logic to serialize as rationalAsPair is missing.
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:
ApiAddressWithPath: &ApiAddressWithPath
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/IntersectMBO/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
- babbage
- conway
NetworkInfo: &NetworkInfo
type: object
required:
- protocol_magic
- network_id
properties:
protocol_magic:
description: The unique magic number defining the network the wallet is working on.
type: integer
network_id:
description: A name just distinguishing mainnet from testnets
type: string
enum:
- mainnet
- testnet
ApiNetworkInformation: &ApiNetworkInformation
type: object
required:
- sync_progress
- node_tip
- node_era
- network_info
- wallet_mode
properties:
sync_progress: *networkInformationSyncProgress
node_tip: *networkInformationNodeTip
network_tip: *ApiNetworkTip
next_epoch: *epochInfo
node_era: *ApiEra
network_info: *NetworkInfo
wallet_mode:
type: string
enum:
- light
- node
ApiNetworkClock: &ApiNetworkClock
<<: *networkInformationNtpStatus
nullableEpochInfo: &nullableEpochInfo
<<: *epochInfo
nullable: True
ApiEraInfo: &ApiEraInfo
type: object
properties:
byron: *nullableEpochInfo
shelley: *nullableEpochInfo
allegra: *nullableEpochInfo
mary: *nullableEpochInfo
alonzo: *nullableEpochInfo
babbage: *nullableEpochInfo
conway: *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
- 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
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_taken: *deposits
deposits_returned: *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]*$"
ApiPolicyKey: &ApiPolicyKey
type: string
format: bech32
pattern: "^((policy_vk)|(policy_vkh))1[0-9a-z]*$"
ApiPostPolicyKeyData: &ApiPostPolicyKeyData
type: object
required:
- passphrase
properties:
passphrase: *walletPassphrase
ApiPolicyId: &ApiPolicyId
type: object
required:
- policy_id
properties:
policy_id: *assetPolicyId
ApiPostPolicyIdData: &ApiPostPolicyIdData
type: object
required:
- policy_script_template
properties:
policy_script_template: *ScriptTemplateValue
ApiTxId: &ApiTxId
type: object
required:
- id
properties:
id: *transactionId
ApiSerialisedTransaction: &ApiSerialisedTransaction
description: |
An encoded transaction.
required:
- transaction
properties:
transaction: *serialisedTransactionEncoded
ApiSerialisedTransactionEncoded: &ApiSerialisedTransactionEncoded
description: |
An encoded transaction.
required:
- transaction
properties:
transaction: *serialisedTransactionEncoded
ApiTokenAmountFingerprint: &ApiTokenAmountFingerprint
type: object
required:
- asset_name
- quantity
- fingerprint
properties:
asset_name: *assetName
quantity: *assetQuantity
fingerprint: *assetFingerprint
PlutusScriptInfo: &PlutusScriptInfo
type: object
required:
- language_version
- script_hash
properties:
language_version:
type: string
enum: ["v1", "v2"]
script_hash:
type: string
format: hex
minLength: 56
maxLength: 56
AnyScript: &AnyScript
oneOf:
- type: object
title: native script
required:
- script_type
- script
properties:
script_type:
type: string
enum: ["native"]
script: *ScriptValue
reference: *referenceInput
- type: object
title: plutus script
required:
- script_type
- script_info
properties:
script_type:
type: string
enum: ["plutus"]
script_info: *PlutusScriptInfo
reference: *referenceInput
- type: object
title: reference script
required:
- script_type
- script_hash
- references
properties:
script_type:
type: string
enum: ["reference script"]
script_hash:
type: string
format: hex
minLength: 56
maxLength: 56
references:
type: array
minItems: 1
items: *referenceInput
AnyExplicitScript: &AnyExplicitScript
oneOf:
- type: object
title: native script
required:
- script_type
- script
properties:
script_type:
type: string
enum: ["native"]
script: *ScriptValueGeneral
reference: *referenceInput
- type: object
title: plutus script
required:
- script_type
- script_info
properties:
script_type:
type: string
enum: ["plutus"]
script_info: *PlutusScriptInfo
reference: *referenceInput
ApiTokens: &ApiTokens
type: object
required:
- policy_id
- policy_script
- assets
properties:
policy_id: *assetPolicyId
policy_script: *AnyScript
assets:
type: array
minItems: 1
items: *ApiTokenAmountFingerprint
ApiAssetMintBurn: &ApiAssetMintBurn
type: object
required:
- tokens
properties:
tokens:
type: array
minItems: 0
items: *ApiTokens
wallet_policy_key_hash: *ApiPolicyKey
wallet_policy_key_index: *derivationSegment
ApiConstructTransaction: &ApiConstructTransaction
type: object
required:
- transaction
- coin_selection
- fee
properties:
transaction: *serialisedTransactionEncoded
coin_selection: *ApiCoinSelection
fee: *amount
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.
ApiCollateralOutputsGeneral: &ApiCollateralOutputsGeneral
<<: *transactionCollateralOutputsGeneral
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.
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
ApiValidityIntervalExplicit: &ApiValidityIntervalExplicit
type: object
required:
- invalid_before
- invalid_hereafter
properties:
invalid_before: *numberOfSlots
invalid_hereafter: *numberOfSlots
ApiWitnessCount: &ApiWitnessCount
description: |
Specifies the number of verification key and bootstrap wintesses.
As scripts act as witnesses they are also included. Scripts can be specified
and spent in a given transaction or defined to be consumed later.
In the latter case they are defined in transaction outputs (feature possible from Babbage era)
in one transaction and referenced in other later transaction(s). The script referencing
is realized via including of reference in a reference input. If reference script
is present here it included the form of the script and reference to be used later,
ie. tx id and index of tx out where the script was included.
type: object
required:
- verification_key
- scripts
- bootstrap
properties:
verification_key: *witnessCount
scripts:
type: array
minItems: 0
items: *AnyExplicitScript
bootstrap: *witnessCount
ApiDecodedTransaction: &ApiDecodedTransaction
type: object
required:
- id
- fee
- inputs
- outputs
- withdrawals
- mint
- burn
- certificates
- witness_count
properties:
id: *transactionId
fee: *amount
inputs: *ApiInputsGeneral
outputs: *ApiOutputsGeneral
collateral: *ApiInputsGeneral
collateral_outputs: *ApiCollateralOutputsGeneral
withdrawals: *ApiWithdrawalsGeneral
mint: *ApiAssetMintBurn
burn: *ApiAssetMintBurn
certificates:
type: array
minItems: 0
items: *ApiCertificate
metadata: *transactionMetadata
deposits_taken: *deposits
deposits_returned: *deposits
script_validity: *txScriptValidity
validity_interval: *ApiValidityIntervalExplicit
witness_count: *ApiWitnessCount
ApiTransaction: &ApiTransaction
type: object
required:
- id
- amount
- fee
- deposit_taken
- deposit_returned
- direction
- inputs
- outputs
- withdrawals
- 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 including the amount of Ada spent as fees or deposits.
For incoming transaction, it represents the total amount of Ada received to
addresses that belong to the wallet.
fee: *amount
deposit_taken: *amount
deposit_returned: *amount
inserted_at: *transactionInsertedAt
expires_at: *transactionExpiresAt
pending_since: *transactionPendingSince
depth: *transactionDepth
direction: *transactionDirection
inputs: *transactionInputs
outputs: *transactionOutputs
collateral: *transactionCollateral
collateral_outputs: *transactionCollateralOutputs
withdrawals: *transactionWithdrawals
status: *transactionStatus
metadata: *transactionMetadata
script_validity: *txScriptValidity
certificates:
type: array
minItems: 0
items: *ApiCertificate
mint: *ApiAssetMintBurn
burn: *ApiAssetMintBurn
validity_interval: *ApiValidityIntervalExplicit
script_integrity: *scriptIntegrityHash
extra_signatures:
type: array
minItems: 0
items: *extraSignatureHash
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).
ApiDRepInfo: &ApiDRepInfo
type: object
required:
- id
- credential
- status
- expiry_epoch
- voting_power
- deposit
properties:
id:
type: string
description: CIP-129 bech32-encoded DRep credential ID.
example: "drep1y4yzl4zeuh3r0l8t0j8k4r9p3wz2m9qv3k7xnvnmme4kk04lgq7xm6f"
credential:
type: object
required:
- type
- hash
properties:
type:
type: string
enum:
- key_hash
- script_hash
hash:
type: string
description: Lowercase hex-encoded 28-byte hash.
example: "25d64e9a9da17b6c6b5bde0e5b15ff059ba7e9e55ee6e6e55b04b13c"
status:
type: string
enum:
- active
- inactive
description: Active when expiry_epoch >= current epoch, inactive otherwise.
expiry_epoch:
type: integer
description: Epoch number at which the DRep's registration expires.
example: 520
voting_power:
type: object
required:
- quantity
- unit
properties:
quantity:
type: string
description: Voting power in lovelace, as a string to avoid precision loss.
example: "123456789012345"
unit:
type: string
enum:
- lovelace
deposit:
type: object
required:
- quantity
- unit
properties:
quantity:
type: integer
description: Registration deposit in lovelace.
example: 500000000
unit:
type: string
enum:
- lovelace
anchor:
nullable: true
type: object
required:
- url
- data_hash
properties:
url:
type: string
description: URL pointing to the DRep's metadata document.
example: "https://example.com/drep.jsonld"
data_hash:
type: string
description: Blake2b-256 hash of the metadata document, lowercase hex.
example: "a14a5ad4f36bddc00f92ddb39fd9ac633c0fd43f8bfa57758f9163d10ef916de"
name:
type: string
nullable: true
description: |
DRep's human-readable name (CIP-0119 givenName).
Null when the DRep has no anchor, when metadata has not yet
been fetched, or when hash verification failed.
metadata:
nullable: true
description: |
Full CIP-0119 off-chain metadata. Populated only on
GET /v2/dreps/{drepId}; always null in list responses.
allOf:
- $ref: '#/components/schemas/ApiDRepMetadata'
ApiDRepMetadata: &ApiDRepMetadata
type: object
required:
- name
- do_not_list
- references
properties:
name:
type: string
description: Human-readable DRep name (CIP-0119 givenName).
example: "Alice the DRep"
objectives:
type: string
nullable: true
description: DRep's stated governance objectives.
motivations:
type: string
nullable: true
description: DRep's stated motivations for participating in governance.
qualifications:
type: string
nullable: true
description: DRep's stated qualifications.
payment_address:
type: string
nullable: true
description: Optional Cardano payment address for the DRep.
do_not_list:
type: boolean
description: Informal extension (not part of CIP-0119); when true the DRep asks not to appear in suggestion lists. Filtering is the client's responsibility.
example: false
references:
type: array
items:
$ref: '#/components/schemas/ApiDRepMetaReference'
ApiDRepMetaReference: &ApiDRepMetaReference
type: object
required:
- label
- uri
properties:
label:
type: string
description: Human-readable label for the reference link.
example: "Website"
uri:
type: string
description: URI for the reference.
example: "https://alice.example.com"
ApiDRepSummary: &ApiDRepSummary
type: object
required:
- total_drep_stake
- active_drep_count
- inactive_drep_count
- total_drep_count
properties:
total_drep_stake:
type: object
required:
- quantity
- unit
properties:
quantity:
type: string
description: Total voting power delegated to all DReps, in lovelace, as a string to avoid precision loss.
example: "123456789012345"
unit:
type: string
enum:
- lovelace
active_drep_count:
type: integer
description: Number of active DReps (expiry_epoch >= current epoch).
example: 42
inactive_drep_count:
type: integer
description: Number of inactive DReps (expiry_epoch < current epoch).
example: 7
total_drep_count:
type: integer
description: Total number of registered DReps (active + inactive).
example: 49
ApiDRep: &ApiDRep
description: |
Decentralized representative (DRep)
that the wallet is delegating its vote to.
One can abstain, give no confidence vote,
or vote for a representative specified by a key hash or script hash.
Vote delegation can be done together with stake delegation action.
nullable: false
type: string
oneOf:
- enum:
- abstain
- no_confidence
title: casting a default vote
- <<: *drepKeyHash
title: vote to a drep represented by key hash (deprecated)
- <<: *drepScriptHash
title: vote to a drep represented by script hash
- <<: *drepKeyHashNew
title: vote to a drep represented by key hash
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
voting: *ApiDRep
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
voting: *ApiDRep
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: *walletPassphraseInfoLegacy
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
one_change_address_mode: *oneChangeAddressMode
restoration_mode: *restorationMode
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
restoration_mode: *restorationMode
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
ApiIncompleteSharedWallet: &ApiIncompleteSharedWallet
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: |
An incomplete 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: Incomplete shared wallet (collecting account public keys for each co-signer)
<<: *ApiIncompleteSharedWallet
- 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
one_change_address_mode: *oneChangeAddressMode
ApiSharedWalletPostDataFromAccountPubX: &ApiSharedWalletPostDataFromAccountPubX
type: object
required:
- name
- account_public_key
- account_index
- payment_script_template
properties:
name: *walletName
account_public_key: *sharedWalletAccountXPubkey
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
- assets
properties:
ada:
<<: *amount
description: |
The ada quantity associated with 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
ApiWalletPutDataExtended: &ApiWalletPutDataExtended
type: object
properties:
name: *walletName
one_change_address_mode: *oneChangeAddressMode
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
ApiWalletPutPassphraseOldPassphraseData: &ApiWalletPutPassphraseOldPassphraseData
type: object
required:
- old_passphrase
- new_passphrase
properties:
old_passphrase:
<<: *walletPassphrase
description: The current master passphrase.
new_passphrase:
<<: *walletPassphrase
description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds).
ApiWalletPutPassphraseMnemonicData: &ApiWalletPutPassphraseMnemonicData
type: object
required:
- mnemonic_sentence
- new_passphrase
properties:
mnemonic_second_factor: *walletSecondFactor
mnemonic_sentence:
<<: *walletMnemonicSentence
description: The mnemonic list of words to restore the wallet
new_passphrase:
<<: *walletPassphrase
description: The new master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds)
ApiWalletPutPassphraseData: &ApiWalletPutPassphraseData
type: object
oneOf:
- <<: *ApiWalletPutPassphraseOldPassphraseData
title: "providing old passphrase"
- <<: *ApiWalletPutPassphraseMnemonicData
title: "providing mnemonic"
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).
ApiDecodeTransactionPostData: &ApiDecodeTransactionPostData
type: object
required:
- transaction
properties:
decrypt_metadata:
<<: *encryptMetadata
description: The metadata passphrase for decryption.
transaction: *serialisedTransactionEncoded
ApiSignTransactionPostData: &ApiSignTransactionPostData
type: object
required:
- passphrase
- transaction
properties:
passphrase:
<<: *lenientPassphrase
description: The wallet's master passphrase.
transaction: *serialisedTransactionEncoded
encoding:
type: string
enum: ["base16", "base64"]
description: Encoding of transaction CBOR returned in response (base64 by default).
# 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: |
Specify only invalid_before or invalid_hereafter or both.
Please note that, if not set, the default values are:
- `"invalid_before": {"quantity":0, "unit":"slot"}`
- `"invalid_hereafter":{"quantity":7200, "unit":"second"}`
Which translates to 2h transaction TTL.
type: object
properties:
invalid_before: *validityBound
invalid_hereafter: *validityBound
ApiPaymentDestination: &ApiPaymentDestination
<<: *transactionOutputs
ApiMintData: &ApiMintData
type: object
required:
- quantity
properties:
receiving_address: *addressId
quantity: *assetQuantity
ApiBurnData: &ApiBurnData
type: object
required:
- quantity
properties:
quantity: *assetQuantity
ApiMintBurnOperation: &ApiMintBurnOperation
type: object
oneOf:
- title: "mint"
properties:
mint: *ApiMintData
- title: "burn"
properties:
burn: *ApiBurnData
ApiMintBurnData: &ApiMintBurnData
oneOf:
- type: object
title: minting via script template
required:
- operation
- policy_script_template
properties:
policy_script_template: *ScriptTemplateValue
asset_name: *assetName
operation: *ApiMintBurnOperation
- type: object
title: minting via script reference
required:
- operation
- reference_input
- policy_id
properties:
reference_input: *referenceInput
policy_id: *assetPolicyId
asset_name: *assetName
operation: *ApiMintBurnOperation
ApiConstructTransactionData: &ApiConstructTransactionData
description: At least one field needs to be chosen
type: object
properties:
payments: *ApiPaymentDestination
withdrawal: *transactionWithdrawalRequestSelf
metadata: *transactionMetadata
encrypt_metadata: *encryptMetadata
mint_burn:
type: array
items: *ApiMintBurnData
minItems: 1
description: |
An entry for each unique asset to be minted and/or burned,
containing helpful information.
vote: *ApiDRep
delegations: *transactionDelegations
validity_interval: *ApiValidityInterval
reference_policy_script_template:
<<: *ScriptTemplateValue
description: |
Optional policy script template that could be used as a script reference
in another transaction.
In the current transaction, the script will be included as
the first output (`index = 0`).
The script is constructed by replacing the cosigner
with the policy public key of the wallet.
In future transactions, the reference script can be used
by any wallet multiple times
by referencing the current transaction `id` and `index = 0`.
The script template must contain a single cosigner only, but it may include time locks.
encoding:
type: string
enum: ["base16", "base64"]
description: Encoding of transaction CBOR returned in response (base64 by default).
CredentialValue: *CredentialValue
ScriptValue: *ScriptValue
ScriptValueGeneral: *ScriptValueGeneral
ScriptTemplateValue: *ScriptTemplateValue
# https://github.com/IntersectMBO/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
nullable: true
properties:
k:
$ref: "#/components/schemas/TransactionMetadataValue"
v:
$ref: "#/components/schemas/TransactionMetadataValue"
TransactionMetadataValueNoSchema: &TransactionMetadataValueNoSchema
oneOf:
- title: String
type: string
- title: Int
type: integer
- title: List
type: array
items:
$ref: "#/components/schemas/TransactionMetadataValueNoSchema"
- title: Map
type: object
additionalProperties:
$ref: "#/components/schemas/TransactionMetadataValueNoSchema"
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 addresses 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
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: |
Mapping from inputs (`id`, `ix`) in the supplied `transaction` binary to outputs (`amount`, `assets`, ...). It is not required to include inputs present in the `cardano-node` UTxO, as `cardano-wallet` will automatically query for them.
In other words, this field can be left empty unless the supplied `transaction` contains inputs referring to pending transactions.
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. The redeemers in the `transaction` binary will be overwritten by this value.
type: array
items: *ApiRedeemer
encoding:
type: string
enum: ["base16", "base64"]
description: Encoding of transaction CBOR returned in response (base64 by default).
ApiBlockHeader: &ApiBlockHeader
description: |
A Block Header.
required:
- header_hash
- slot_no
- block_height
properties:
header_hash: *blockId
slot_no: *numberOfSlots
block_height: *numberOfBlocks
#############################################################################
# #
# PARAMETERS #
# #
#############################################################################
x-parametersWalletId: ¶metersWalletId
in: path
name: walletId
required: true
schema:
type: string
format: hex
maxLength: 40
minLength: 40
x-parametersIntendedStakeAmount: ¶metersIntendedStakeAmount
in: query
name: stake
required: true
schema:
type: integer
minimum: 0
maximum: 45000000000000000 # 45 B ada (in Lovelace)
description: |
The stake the user intends to delegate in Lovelace. Required.
x-parametersTransactionId: ¶metersTransactionId
in: path
name: transactionId
required: true
schema:
type: string
format: hex
maxLength: 64
minLength: 64
x-parametersStakePoolId: ¶metersStakePoolId
in: path
name: stakePoolId
required: true
schema:
type: string
format: hex|bech32
x-parametersAddressId: ¶metersAddressId
in: path
name: addressId
required: true
schema:
type: string
format: base58
example: DdzFFzCqrhtCNjPk5Lei7E1FxnoqMoAYtJ8VjAWbFmDb614nNBWBwv3kt6QHJa59cGezzf6piMWsbK7sWRB5sv325QqWdRuusMqqLdMt
x-parametersRole: ¶metersRole
in: path
name: role
required: true
schema:
type: string
enum:
- utxo_external
- utxo_internal
- mutable_account
x-parametersDerivationSegment: ¶metersDerivationSegment
in: path
name: index
required: true
schema: *derivationSegment
x-parametersDerivationHash: ¶metersDerivationHash
in: query
name: hash
schema:
type: boolean
default: false
description: |
Whether to return the key hash instead of the key.
x-parametersStartDate: ¶metersStartDate
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: ¶metersEndDate
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: ¶metersSortOrder
in: query
name: order
description: An optional sort order.
schema:
type: string
enum:
- ascending
- descending
default: descending
x-parametersMaxCount: ¶metersMaxCount
in: query
name: max_count
description: |
An optional maximum count.
schema:
type: integer
minimum: 1
x-parametersAddress: ¶metersAddress
in: query
name: address
description: |
An optional address.
If given, the list of transactions will be filtered
to only contain transactions that refer to this address in their inputs or outputs.
This may exclude transactions whose inputs reference outside transactions
that are not part of the transaction history of the wallet.
schema: *addressId
x-parametersAddressState: ¶metersAddressState
in: query
name: state
description: An optional filter on the address state.
schema:
type: string
enum:
- used
- unused
x-parametersForceNtpCheck: ¶metersForceNtpCheck
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-parametersMetadataFormat: ¶metersMetadataFormat
in: query
name: simple-metadata
schema:
type: boolean
allowEmptyValue: true
description: |
When present (or equal to true) in the query, the metadata format for the
transaction(s) in the output will be untyped plain json as specified in
[CIP 25](https://cips.cardano.org/cips/cip25/)
x-parametersMinWithdrawal: ¶metersMinWithdrawal
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: ¶metersPolicyId
in: path
name: policyId
required: true
schema:
type: string
format: hex
maxLength: 56
minLength: 56
x-parametersAssetName: ¶metersAssetName
in: path
name: assetName
required: true
schema:
type: string
format: hex
maxLength: 64
x-parametersDRepId: ¶metersDRepId
in: path
name: drepId
required: true
schema: *ApiDRep
#############################################################################
# #
# 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-errNoUtxosAvailable: &errNoUtxosAvailable
<<: *responsesErr
title: no_utxos_available
properties:
message:
type: string
description: |
Indicates that the wallet has no unspent transaction outputs (UTxOs)
available. A transaction must spend at least one UTxO in order to be
accepted for inclusion on the Cardano blockchain.
code:
type: string
enum: ['no_utxos_available']
x-errWalletNotInitialized: &errWalletNotInitialized
<<: *responsesErr
title: wallet_not_initialized
properties:
message:
type: string
description: |
May occur when the database for the requested wallet is not initialized.
code:
type: string
enum: ['wallet_not_initialized']
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']
info:
type: object
required:
- wallet_id
properties:
wallet_id: *walletId
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']
info:
type: object
required:
- transaction_id
properties:
transaction_id: *transactionId
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']
info:
type: object
required:
- transaction_id
properties:
transaction_id: *transactionId
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-errWalletMetadataNotFound: &errWalletMetadataNotFound
<<: *responsesErr
title: wallet_metadata_not_found
properties:
message:
type: string
description: |
Indicates that it was not possible to find any metadata for the given
wallet within the database.
May occur when a shared wallet has not yet become active after being in
the incomplete state.
code:
type: string
enum: ['wallet_metadata_not_found']
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']
info:
type: object
required:
- wallet_id
properties:
wallet_id: *walletId
x-errWrongMnemonic: &errWrongMnemonic
<<: *responsesErr
title: wrong_mnemonics
properties:
message:
type: string
description: May occur when the given mnemonic is wrong.
code:
type: string
enum: ['wrong_mnemonic']
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-errMempoolIsFull: &errMempoolIsFull
<<: *responsesErr
title: mempool_is_full
properties:
message:
type: string
description: May occur when submitting a serialized transaction to a node with full mempool.
code:
type: string
enum: [mempool_is_full]
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: |
Indicates that there's not enough money in the wallet for the operation
to succeed.
The 'shortfall' object indicates the additional quantity of each asset
that would be needed in order for the operation to succeed.
code:
type: string
enum: ['not_enough_money']
info:
type: object
required:
- shortfall
properties:
shortfall:
description: |
The additional quantity of each asset that would be needed in order
for the operation to succeed.
type: object
required:
- ada
- assets
properties:
ada: *amount
assets: *walletAssets
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-errCreatedMultidelegationTransaction: &errCreatedMultidelegationTransaction
<<: *responsesErr
title: created_multidelegation_transaction
properties:
message:
type: string
description: Occurs when more than 1 delegation action is included in a transaction.
code:
type: string
enum: ['created_multidelegation_transaction']
x-errCreatedMultiaccountTransaction: &errCreatedMultiaccountTransaction
<<: *responsesErr
title: created_multiaccount_transaction
properties:
message:
type: string
description: Occurs when a delegation action does not use '0H' account.
code:
type: string
enum: ['created_multiaccount_transaction']
x-errCreatedWrongPolicyScriptTemplate: &errCreatedWrongPolicyScriptTemplate
<<: *responsesErr
title: created_wrong_policy_script_template
properties:
message:
type: string
description: |
Occurs when a policy script template either does not pass validation
or has more than one cosigner.
code:
type: string
enum: ['created_wrong_policy_script_template']
x-errAssetNameTooLong: &errAssetNameTooLong
<<: *responsesErr
title: asset_name_too_long
properties:
message:
type: string
description: Occurs when an asset name exceeds 32 bytes in length.
code:
type: string
enum: ['asset_name_too_long']
x-errMintOrBurnAssetQuantityOutOfBounds: &errMintOrBurnAssetQuantityOutOfBounds
<<: *responsesErr
title: mint_or_burn_asset_quantity_out_of_bounds
properties:
message:
type: string
description: |
Occurs when attempting to mint or burn an asset quantity that is not
greater than zero or exceeds 9223372036854775807 (2^63 - 1).
code:
type: string
enum: ['mint_or_burn_asset_quantity_out_of_bounds']
x-errInvalidValidityBounds: &errInvalidValidityBounds
<<: *responsesErr
title: invalid_validity_bounds
properties:
message:
type: string
description: |
Occurs when attempting to create a transaction with invalid validity
bounds. The 'invalid_before' bound must precede the 'invalid_hereafter'
bound, and the given time values must not be negative.
code:
type: string
enum: ['invalid_validity_bounds']
x-errValidityIntervalNotInsideScriptTimelock: &errValidityIntervalNotInsideScriptTimelock
<<: *responsesErr
title: validity_interval_not_inside_script_timelock
properties:
message:
type: string
description: |
Occurs when attempting to create a transaction with a validity interval
that is not a subinterval of an associated script's timelock interval.
code:
type: string
enum: ['validity_interval_not_inside_script_timelock']
x-errSharedWalletIncomplete: &errSharedWalletIncomplete
<<: *responsesErr
title: shared_wallet_incomplete
properties:
message:
type: string
description: |
Occurs when attempting to create a transaction for an incomplete shared wallet.
code:
type: string
enum: ['shared_wallet_incomplete']
x-errDelegationInvalid: &errDelegationInvalid
<<: *responsesErr
title: staking_invalid
properties:
message:
type: string
description: |
Occurs when attempting to create a delegation transaction for a shared wallet
without a delegation script template.
code:
type: string
enum: ['staking_invalid']
x-errVotingInInvalidEra: &errVotingInInvalidEra
<<: *responsesErr
title: voting_in_invalid_era
properties:
message:
type: string
description: |
Occurs when attempting to create a transaction that has voting
before Conway era.
code:
type: string
enum: ['voting_in_invalid_era']
x-errWithdrawalNotPossibleWithoutVote: &errWithdrawalNotPossibleWithoutVote
<<: *responsesErr
title: withdrawal_not_possible_without_vote
properties:
message:
type: string
description: |
Occurs when attempting to create a transaction that contains withdrawals
but previous voting was not performed (in Conway era onwards).
code:
type: string
enum: ['withdrawal_not_possible_without_vote']
x-errInvalidMetadataEncryption: &errInvalidMetadataEncryption
<<: *responsesErr
title: invalid_metadata_encryption
properties:
message:
type: string
description: |
The supplied metadata object is not compatible with the format
specified by CIP-83 (https://cips.cardano.org/cip/CIP-83).
code:
type: string
enum: ['invalid_metadata_encryption']
x-errInvalidMetadataDecryption: &errInvalidMetadataDecryption
<<: *responsesErr
title: invalid_metadata_decryption
properties:
message:
type: string
description: |
The supplied encrypted metadata object is not compatible with standard
specified by CIP-83 (https://cips.cardano.org/cip/CIP-83).
code:
type: string
enum: ['invalid_metadata_decryption']
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']
info:
type: object
required:
- address
- bundle_size
properties:
address: *addressId
bundle_size:
type: integer
minimum: 0
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']
info:
type: object
required:
- address
- policy_id
- asset_name
- quantity
- max_quantity
properties:
address: *addressId
policy_id: *assetPolicyId
asset_name: *assetName
quantity: *assetQuantity
max_quantity: *assetQuantity
x-errSharedWalletActive: &errSharedWalletActive
<<: *responsesErr
title: shared_wallet_active
properties:
message:
type: string
description: |
Returned when a user tries to add cosigner key to a shared wallet
that is active, not incomplete anymore.
code:
type: string
enum: ['shared_wallet_active']
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']
info:
type: object
required:
- cosigner_index
- credential_type
properties:
cosigner_index:
type: integer
minimum: 0
maximum: 255
credential_type:
type: string
enum:
- delegation
- payment
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']
info:
type: object
required:
- detected_number_of_key_wits
- expected_number_of_key_wits
properties:
detected_number_of_key_wits:
type: integer
minimum: 0
expected_number_of_key_wits:
type: integer
minimum: 0
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-errNodeNotYetInRecentEra: &errNodeNotYetInRecentEra
<<: *responsesErr
title: node_not_yet_in_recent_era
description: Occurs when the operation requires the node to be in a recent era, but is not.
properties:
message:
type: string
code:
type: string
enum: ['node_not_yet_in_recent_era']
info:
type: object
required:
- node_era
- recent_eras
properties:
node_era: *ApiEra
recent_eras:
type: array
items: *ApiEra
x-errTxNotInNodeEra: &errTxNotInNodeEra
<<: *responsesErr
title: tx_not_in_node_era
properties:
message:
type: string
description: The transaction could be deserialised, just not in the era of the local node.
code:
type: string
enum: ["tx_not_in_node_era"]
x-errBalanceTxConflictingNetworks: &errBalanceTxConflictingNetworks
<<: *responsesErr
title: balance_tx_conflicting_networks
deprecated: true # TODO: Remove this error as soon as bump.sh allows us to
properties:
message:
type: string
description: |
There are withdrawals for multiple networks
(e.g. both mainnet and testnet) in the provided transaction.
This makes no sense, and I'm confused.
code:
type: string
enum: ["balance_tx_conflicting_networks"]
x-errTranslationByronTxOutInContext: &errTranslationByronTxOutInContext
<<: *responsesErr
title: translation_byron_tx_out_in_context
properties:
message:
type: string
description: |
The given transaction contains a Byron-style TxOut which i not supported when executing
Plutus scripts.
code:
type: string
enum: ["translation_byron_tx_out_in_context"]
x-errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage: &errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage
<<: *responsesErr
title: balance_tx_inline_plutus_v3_script_not_supported_in_babbage
properties:
message:
type: string
description: |
Inline Plutus V3 scripts are not supported in Babbage.
code:
type: string
enum: ["balance_tx_inline_plutus_v3_script_not_supported_in_babbage"]
x-errBalanceTxInlinePlutusV4ScriptNotSupportedInConway: &errBalanceTxInlinePlutusV4ScriptNotSupportedInConway
<<: *responsesErr
title: balance_tx_inline_plutus_v4_script_not_supported_in_conway
properties:
message:
type: string
description: |
Plutus V4 scripts are not supported in the Conway era.
code:
type: string
enum: ["balance_tx_inline_plutus_v4_script_not_supported_in_conway"]
x-errBalanceTxNativeScriptNotSupportedInConway: &errBalanceTxNativeScriptNotSupportedInConway
<<: *responsesErr
title: balance_tx_native_script_not_supported_in_conway
properties:
message:
type: string
description: |
Native scripts are not supported in the Conway era.
code:
type: string
enum: ["balance_tx_native_script_not_supported_in_conway"]
x-errBalanceTxExistingCollateral: &errBalanceTxExistingCollateral
<<: *responsesErr
title: balance_tx_existing_collateral
properties:
message:
type: string
description: I cannot balance transactions with pre-defined collateral.
code:
type: string
enum: ["balance_tx_existing_collateral"]
x-errBalanceTxExistingKeyWitnesses: &errBalanceTxExistingKeyWitnesses
<<: *responsesErr
title: balance_tx_existing_key_witnesses
properties:
message:
type: string
description: |
The transaction could not be balanced, because it contains
existing key-witnesses which would be invalid after
the transaction body is modified.
Please sign the transaction after it is balanced instead.
code:
type: string
enum: ["balance_tx_existing_key_witnesses"]
x-errBalanceTxExistingReturnCollateral: &errBalanceTxExistingReturnCollateral
<<: *responsesErr
title: balance_tx_existing_collateral_return_outputs
properties:
message:
type: string
description: |
Balancing transactions with pre-defined collateral return outputs
is not yet supported.
code:
type: string
enum: ["balance_tx_existing_collateral_return_outputs"]
x-errBalanceTxExistingTotalCollateral: &errBalanceTxExistingTotalCollateral
<<: *responsesErr
title: balance_tx_existing_total_collateral
properties:
message:
type: string
description: |
I cannot balance transactions with pre-defined total collateral.
code:
type: string
enum: ["balance_tx_existing_total_collateral"]
x-errBalanceTxInternalError: &errBalanceTxInternalError
<<: *responsesErr
title: balance_tx_internal_error
properties:
message:
type: string
description: |
Balancing transaction failed for an internal reason.
code:
type: string
enum: ["balance_tx_internal_error"]
x-errBalanceTxUnderestimatedFee: &errBalanceTxUnderestimatedFee
<<: *responsesErr
title: balance_tx_underestimated_fee
properties:
message:
type: string
description: |
I have somehow underestimated the fee of the transaction
and cannot finish balancing.
code:
type: string
enum: ["balance_tx_underestimated_fee"]
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']
info:
type: object
required:
- start_time
- end_time
properties:
start_time: *date
end_time: *date
# 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']
info:
type: object
required:
- pool_id
properties:
pool_id: *stakePoolId
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 (not in Conway onwards provided different vote was also casted).
code:
type: string
enum: ['pool_already_joined']
x-errPoolAlreadyJoinedSameVote: &errPoolAlreadyJoinedSameVote
<<: *responsesErr
title: pool_already_joined_same_vote
properties:
message:
type: string
description: May occur in Conway onwards when a given poolId matches the current delegation preferences of the wallet's account and also the same vote was cast.
code:
type: string
enum: ['pool_already_joined_same_vote']
x-errSameVote: &errSameVote
<<: *responsesErr
title: same_vote
properties:
message:
type: string
description: May occur in Conway onwards when the same vote was cast.
code:
type: string
enum: ['same_vote']
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-errMissingPolicyPublicKey: &errMissingPolicyPublicKey
<<: *responsesErr
title: missing_policy_public_key
properties:
message:
type: string
description: Occurs when trying to construct with minting/burning on shelley wallet without policy public key.
code:
type: string
enum: ['missing_policy_public_key']
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-errMissingRewardAccount: &errMissingRewardAccount
<<: *responsesErr
title: missing_reward_account
properties:
message:
type: string
description: May occur when there is a missing reward account but wallet participates in staking.
code:
type: string
enum: ['missing_reward_account']
x-errUtxoTooSmall: &errUtxoTooSmall
<<: *responsesErr
title: utxo_too_small
properties:
message:
type: string
description:
Occurs when a requested output has a quantity of lovelace that is below
the minimum required by the ledger.
code:
type: string
enum: ['utxo_too_small']
info:
type: object
required:
- tx_output_index
- tx_output_lovelace_specified
- tx_output_lovelace_required_minimum
properties:
tx_output_index:
type: integer
minimum: 0
tx_output_lovelace_specified: *amount
tx_output_lovelace_required_minimum: *amount
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-errWithdrawalNotBeneficial: &errWithdrawalNotBeneficial
<<: *responsesErr
title: withdrawal_not_beneficial
properties:
message:
type: string
description: |
Occurs when the cost of withdrawing a reward balance would be greater
than the reward balance itself.
code:
type: string
enum: ['withdrawal_not_beneficial']
# 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: |
There are inputs in the transaction for which the corresponding outputs
could not be found.
code:
type: string
enum: ['unknown_inputs']
x-errUnresolvedRefunds: &errUnresolvedRefunds
<<: *responsesErr
title: unresolved_refunds
properties:
message:
type: string
description: |
There are stake key deregistration certificates in the transaction for which corresponding
deposit amounts could not be found.
code:
type: string
enum: ['unresolved_refunds']
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-errTranslationError: &errTranslationError
<<: *responsesErr
title: translation_error
properties:
message:
type: string
description: |
Occurs when any data in a provided transaction cannot be translated in a given era
code:
type: string
enum: ['translation_error']
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-errInputResolutionConflicts: &errInputResolutionConflicts
<<: *responsesErr
title: input_resolution_conflicts
properties:
message:
type: string
description: |
At least one of the provided inputs has an
asset quantity or address that is different from that
recorded in the wallet's UTxO set.
code:
type: string
enum: ['input_resolution_conflicts']
x-errBlockHeaderNotFound: &errBlockHeaderNotFound
<<: *responsesErr
title: block_header_not_found
properties:
message:
type: string
description: |
Occurs when trying to retrieve a block header
that is not in the local node's chain.
code:
type: string
enum: ['block_header_not_found']
x-errUnsupportedEra: &errUnsupportedEra
<<: *responsesErr
title: unsupported_era
properties:
message:
type: string
code:
type: string
enum: ['unsupported_era']
info:
type: object
required:
- unsupported_era
- supported_eras
properties:
unsupported_era: *ApiEra
supported_eras:
type: array
items: *ApiEra
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-responsesErr425MempoolIsFull: &responsesErr425MempoolIsFull
425:
description: Mempool is Full
content:
application/json:
schema: *errMempoolIsFull
x-responsesErr404WalletNotFound: &responsesErr404WalletNotFound
404:
description: Not Found
content:
application/json:
schema: *errNoSuchWallet
x-responsesErr404WalletNotInitialized: &responsesErr404WalletNotInitialized
404:
description: Wallet not yet initialized
content:
application/json:
schema: *errWalletNotInitialized
x-responsesErr503WalletMetadataNotFound: &responsesErr503WalletMetadataNotFound
503:
description: No meta
content:
application/json:
schema: *errWalletMetadataNotFound
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
- *responsesErr404WalletNotInitialized
- *responsesErr406
200:
description: Ok
content:
application/json:
schema: *ApiWalletUTxOsStatistics
x-responsesGetWalletUtxoSnapshot: &responsesGetWalletUtxoSnapshot
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *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
500:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errMissingRewardAccount
201:
description: Created
content:
application/json:
schema: *ApiSharedWallet
x-responsesPostByronWallet: &responsesPostByronWallet
<<:
- *responsesErr400
- *responsesErr406
- *responsesErr409
- *responsesErr415
201:
description: Created
content:
application/json:
schema: *ApiByronWallet
x-responsesGetWallet: &responsesGetWallet
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *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
- *responsesErr404WalletNotInitialized
- *responsesErr406
200:
description: Ok
content:
application/json:
schema: *ApiSharedWallet
x-responsesPatchSharedWallet: &responsesPatchSharedWallet
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr503WalletMetadataNotFound
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errSharedWalletKeyAlreadyExists
- <<: *errSharedWalletNoDelegationTemplate
- <<: *errSharedWalletActive
- <<: *errSharedWalletNoSuchCosigner
- <<: *errSharedWalletCannotUpdateKey
200:
description: Ok
content:
application/json:
schema: *ApiSharedWallet
x-responsesCreateWalletMigrationPlan: &responsesCreateWalletMigrationPlan
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
403:
description: Forbidden
content:
application/json:
schema: *errNothingToMigrate
202:
description: Accepted
content:
application/json:
schema: *ApiWalletMigrationPlan
x-responsesMigrateWallet: &responsesMigrateWallet
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errNothingToMigrate
- <<: *errNoRootKey
- <<: *errWrongEncryptionPassphrase
202:
description: Accepted
content:
application/json:
schema:
type: array
items: *ApiTransaction
minItems: 1
x-responsesDeleteWallet: &responsesDeleteWallet
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
204:
description: No Content
x-responsesForceResyncWallet: &responsesForceResyncWallet
<<:
- *responsesErr400
- *responsesErr403
- *responsesErr404
- *responsesErr406
- *responsesErr415
204:
description: No Content
x-responsesPutWallet: &responsesPutWallet
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
200:
description: Ok
content:
application/json:
schema: *ApiWallet
x-responsesPutSharedWallet: &responsesPutSharedWallet
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
200:
description: Ok
content:
application/json:
schema: *ApiSharedWallet
x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errNoRootKey
- <<: *errWrongEncryptionPassphrase
- <<: *errWrongMnemonic
204:
description: No Content
x-responsesSelectCoins: &responsesSelectCoins
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errAlreadyWithdrawing
- <<: *errUtxoTooSmall
- <<: *errNoUtxosAvailable
- <<: *errNotEnoughMoney
- <<: *errInsufficientCollateral
- <<: *errCannotCoverFee
- <<: *errInputsDepleted
- <<: *errInvalidCoinSelection
- <<: *errOutputTokenQuantityExceedsLimit
- <<: *errOutputTokenBundleSizeExceedsLimit
200:
description: OK
content:
application/json:
schema: *ApiCoinSelection
x-responsesDeleteTransaction: &responsesDeleteTransaction
<<:
- *responsesErr406
403:
description: Forbidden
content:
application/json:
schema: *errTransactionAlreadyInLedger
404:
description: Not Found
content:
application/json:
schema:
oneOf:
- <<: *errNoSuchWallet
- <<: *errWalletNotInitialized
- <<: *errNoSuchTransaction
204:
description: No Content
x-responsesListTransactions: &responsesListTransactions
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
400:
description: Bad Request
content:
application/json:
schema:
oneOf:
- <<: *errMinWithdrawalWrong
- <<: *errStartTimeLaterThanEndTime
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
- <<: *errWalletNotInitialized
- <<: *errNoSuchTransaction
<<: *responsesErr406
200:
description: OK
content:
application/json:
schema: *ApiTransaction
# ADP-908 Deprecated
x-responsesPostTransaction: &responsesPostTransaction
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
- *responsesErr425MempoolIsFull
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errInvalidWalletType
- <<: *errAlreadyWithdrawing
- <<: *errUtxoTooSmall
- <<: *errCannotCoverFee
- <<: *errNoUtxosAvailable
- <<: *errNotEnoughMoney
- <<: *errInsufficientCollateral
- <<: *errTransactionIsTooBig
- <<: *errNoRootKey
- <<: *errWrongEncryptionPassphrase
- <<: *errUnsupportedEra
202:
description: Accepted
content:
application/json:
schema: *ApiTransaction
x-responsesConstructTransaction: &responsesConstructTransaction
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
400:
description: Bad Request
content:
application/json:
schema:
oneOf:
- <<: *errBadRequest
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errInvalidWalletType
- <<: *errAlreadyWithdrawing
- <<: *errUtxoTooSmall
- <<: *errCannotCoverFee
- <<: *errNoUtxosAvailable
- <<: *errNotEnoughMoney
- <<: *errInsufficientCollateral
- <<: *errTransactionIsTooBig
- <<: *errCreatedMultidelegationTransaction
- <<: *errCreatedMultiaccountTransaction
- <<: *errCreatedWrongPolicyScriptTemplate
- <<: *errAssetNameTooLong
- <<: *errMintOrBurnAssetQuantityOutOfBounds
- <<: *errInvalidValidityBounds
- <<: *errValidityIntervalNotInsideScriptTimelock
- <<: *errSharedWalletIncomplete
- <<: *errDelegationInvalid
- <<: *errVotingInInvalidEra
- <<: *errWithdrawalNotPossibleWithoutVote
- <<: *errInvalidMetadataEncryption
- <<: *errSameVote
202:
description: Accepted
content:
application/json:
schema: *ApiConstructTransaction
x-responsesSignTransaction: &responsesSignTransaction
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errNoRootKey
- <<: *errWrongEncryptionPassphrase
202:
description: Accepted
content:
application/json:
schema: *ApiSignedTransaction
x-responsesDecodedTransaction: &responsesDecodedTransaction
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errInvalidMetadataDecryption
202:
description: Accepted
content:
application/json:
schema: *ApiDecodedTransaction
x-responsesSubmitTransaction: &responsesSubmitTransaction
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
202:
description: Accepted
content:
application/json:
schema: *ApiTxId
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errForeignTransaction
- <<: *errMissingWitnessesInTransaction
- <<: *errCreatedMultidelegationTransaction
x-responsesPostExternalTransaction: &responsesPostExternalTransaction
<<:
- *responsesErr400
- *responsesErr406
- *responsesErr415UnsupportedMediaType
- *responsesErr425MempoolIsFull
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
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
400:
description: Bad Request
content:
application/json:
schema:
oneOf:
- <<: *errBadRequest
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errInvalidWalletType
- <<: *errAlreadyWithdrawing
- <<: *errUtxoTooSmall
- <<: *errCannotCoverFee
- <<: *errNoUtxosAvailable
- <<: *errNotEnoughMoney
- <<: *errInsufficientCollateral
- <<: *errInputsDepleted
- <<: *errInvalidCoinSelection
- <<: *errOutputTokenQuantityExceedsLimit
- <<: *errOutputTokenBundleSizeExceedsLimit
- <<: *errTransactionIsTooBig
202:
description: Accepted
content:
application/json:
schema: *ApiFee
x-responsesGetDelegationFee: &responsesGetDelegationFee
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
403:
description: Forbidden
content:
application/json:
schema: *errCannotCoverFee
200:
description: Ok
content:
application/json:
schema: *ApiFee
x-responsesListAddresses: &responsesListAddresses
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
200:
description: Ok
content:
application/json:
schema:
type: array
items: *ApiAddressWithPath
x-responsesGetShelleyKey: &responsesGetShelleyKey
<<:
- *responsesErr400
- *responsesErr404
- *responsesErr406
200:
description: Ok
content:
application/json:
schema: *ApiVerificationKeyShelley
x-responsesPostPolicyKey: &responsesPostPolicyKey
<<:
- *responsesErr400
- *responsesErr406
- *responsesErr415
202:
description: Accepted
content:
application/json:
schema: *ApiPolicyKey
x-responsesPostPolicyId: &responsesPostPolicyId
<<:
- *responsesErr400
- *responsesErr406
- *responsesErr415
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errInvalidWalletType
- <<: *errMissingPolicyPublicKey
- <<: *errCreatedWrongPolicyScriptTemplate
202:
description: Accepted
content:
application/json:
schema: *ApiPolicyId
x-responsesGetPolicyKey: &responsesGetPolicyKey
<<:
- *responsesErr400
- *responsesErr404
- *responsesErr406
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errInvalidWalletType
- <<: *errMissingPolicyPublicKey
200:
description: Ok
content:
application/json:
schema: *ApiPolicyKey
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
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errCannotCoverFee
- <<: *errNoRootKey
- <<: *errNoUtxosAvailable
- <<: *errWrongEncryptionPassphrase
- <<: *errPoolAlreadyJoined
- <<: *errPoolAlreadyJoinedSameVote
- <<: *errSameVote
404:
description: Not Found
content:
application/json:
schema:
oneOf:
- <<: *errNoSuchWallet
- <<: *errWalletNotInitialized
- <<: *errNoSuchPool
202:
description: Accepted
content:
application/json:
schema: *ApiTransaction
x-responsesJoinDRep: &responsesJoinDRep
<<:
- *responsesErr400
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errCannotCoverFee
- <<: *errNoRootKey
- <<: *errNoUtxosAvailable
- <<: *errWrongEncryptionPassphrase
- <<: *errSameVote
404:
description: Not Found
content:
application/json:
schema:
oneOf:
- <<: *errNoSuchWallet
- <<: *errWalletNotInitialized
- <<: *errNoSuchPool
202:
description: Accepted
content:
application/json:
schema: *ApiTransaction
x-responsesQuitStakePool: &responsesQuitStakePool
<<:
- *responsesErr400
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *responsesErr406
- *responsesErr415UnsupportedMediaType
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errCannotCoverFee
- <<: *errNoRootKey
- <<: *errNoUtxosAvailable
- <<: *errWrongEncryptionPassphrase
- <<: *errNotDelegatingTo
- <<: *errNonNullRewards
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: *ApiAddressWithPath
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
- <<: *errTranslationError
- <<: *errUnresolvedInputs
- <<: *errInputResolutionConflicts
403:
description: Forbidden
content:
application/json:
schema:
oneOf:
- <<: *errAlreadyWithdrawing
- <<: *errNodeNotYetInRecentEra
- <<: *errBalanceTxConflictingNetworks
- <<: *errBalanceTxExistingCollateral
- <<: *errBalanceTxExistingKeyWitnesses
- <<: *errBalanceTxExistingReturnCollateral
- <<: *errBalanceTxExistingTotalCollateral
- <<: *errBalanceTxInternalError
- <<: *errCannotCoverFee
- <<: *errInsufficientCollateral
- <<: *errInvalidWalletType
- <<: *errNoUtxosAvailable
- <<: *errNotEnoughMoney
- <<: *errTransactionAlreadyBalanced
- <<: *errTransactionIsTooBig
- <<: *errUtxoTooSmall
- <<: *errTxNotInNodeEra
- <<: *errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage
- <<: *errBalanceTxInlinePlutusV4ScriptNotSupportedInConway
- <<: *errBalanceTxNativeScriptNotSupportedInConway
- <<: *errTranslationByronTxOutInContext
<<:
- *responsesErr404WalletNotFound
- *responsesErr404WalletNotInitialized
- *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
- DReps
- Keys
- name: Shelley (Shared Wallets)
tags:
- Shared Wallets
- Shared Keys
- Shared Addresses
- Shared Transactions
- 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
- Node
paths:
/wallets/{walletId}/signatures/{role}/{index}:
post:
operationId: signMetadata
tags: ["Experimental"]
summary: Sign Metadata
description: |
status: experimental
**⚠️ 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**.
Note: 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: |
status: stable
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: |
status: stable
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, at one point in history,
it was spendable by the wallet.
parameters:
- *parametersWalletId
responses: *responsesListAssets
/wallets/{walletId}/assets/{policyId}/{assetName}:
get:
operationId: getAsset
tags: ["Assets"]
summary: Get Asset
description: |
Fetch a single asset from its `policy_id` and `asset_name`,
with its metadata if any.
The asset must be associated with the wallet.
parameters:
- *parametersWalletId
- *parametersPolicyId
- *parametersAssetName
responses: *responsesGetAsset
/wallets/{walletId}/assets/{policyId}:
get:
operationId: getAssetDefault
tags: ["Assets"]
summary: Get Asset (empty name)
description: |
Fetch the 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: |
status: stable
Return the UTxO 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: |
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: |
status: stable
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: |
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: |
status: stable
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: |
status: stable
Signs a serialised transaction either hex-encoded or base64-encoded,
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: |
status: stable
Decode a serialized transaction, either freshly constructed,
partially signed or fully-signed.
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiDecodeTransactionPostData
responses: *responsesDecodedTransaction
/wallets/{walletId}/transactions-submit:
post:
operationId: submitTransaction
tags: ["Transactions New"]
summary: Submit
description: |
status: stable
Submit a transaction that was already created and signed.
Fails for foreign transactions that is transactions which lack
the wallet's inputs and withdrawals.
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiSignedTransactionEncoded
responses: *responsesPostExternalTransaction
/wallets/{walletId}/addresses:
get:
operationId: listAddresses
tags: ["Addresses"]
summary: List
description: |
status: stable
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: |
status: stable
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.
Note: 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: |
status: stable
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.
Note the returned key is bech32-encoded. To be used when restoring
a wallet with public account key only, one needs to pass the key
in hex-encoded form. The bech32 tool which is included
in cardano-wallet distribution can used on the command-line:
curl https://my.host/v2/wallets/1f8[...]/keys?format=extended' | jq -r . | bech32
parameters:
- *parametersWalletId
responses: *responsesGetAccountKey
/wallets/{walletId}/keys/{role}/{index}:
get:
operationId: getWalletKey
tags: ["Keys"]
summary: Get Public Key
description: |
status: stable
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`.
Note: Only `Soft` indexes are supported by this endpoint.
parameters:
- *parametersWalletId
- *parametersRole
- *parametersDerivationSegment
responses: *responsesGetShelleyKey
/wallets/{walletId}/policy-id:
post:
operationId: postPolicyId
tags: ["Keys"]
summary: Create Policy Id
description: |
status: stable
Create policy id for the wallet and a given mint/burn script.
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiPostPolicyIdData
responses: *responsesPostPolicyId
/wallets/{walletId}/policy-key:
post:
operationId: postPolicyKey
tags: ["Keys"]
summary: Create Policy Key
description: |
status: stable
Create policy key for the wallet.
In order to be able to mint/burn assets with `POST Construct` endpoint there needs to be
a policy key set for the wallet. Invoking this endpoint would be required for all wallets instantiated
before introducing mint/burn feature prior to making a mint/burn transaction from them.
To get a hash of the policy key instead of the policy key,
use query parameter `hash=true`.
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiPostPolicyKeyData
responses: *responsesPostPolicyKey
get:
operationId: getPolicyKey
tags: ["Keys"]
summary: Get Policy Key
description: |
status: stable
Return a policy key for a derivation index = 0.
To get a hash of the policy key instead of the policy key,
use query parameter `hash=true`.
parameters:
- *parametersWalletId
responses: *responsesGetPolicyKey
/wallets/{walletId}/stake-keys:
get:
operationId: listStakeKeys
tags: ["Stake Pools"]
summary: List Stake Keys
description: |
status: Experimental
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: |
status: stable
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: |
status: stable
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: |
status: stable
Stop delegating completely. The wallet's stake will become inactive.
Any current rewards will automatically withdrawn.
> ⚠️ 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: |
status: stable
Delegate all (current and future) addresses from the given wallet to the given stake pool.
Note: Bech32-encoded stake pool identifiers can vary in length.
parameters:
- *parametersStakePoolId
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiWalletPassphrase
responses: *responsesJoinStakePool
/dreps:
get:
operationId: listDReps
tags: ["DReps"]
summary: List Registered DReps
description: |
status: stable
Returns all DRep registrations known to the local node, with voting
power inline. Only credential-based DReps (key-hash and script-hash)
are included; the always-abstain and always-no-confidence sentinel DReps
are not returned.
Returns an empty array when the connected node is running a pre-Conway
era (Byron through Babbage).
**Note:** Results are served from a cache with a ~15-minute TTL. A
recently deregistered DRep may still appear until the next cache refresh.
responses:
'200':
description: List of all registered DReps.
content:
application/json:
schema:
type: array
items: *ApiDRepInfo
/dreps/summary:
get:
operationId: getDRepSummary
tags: ["DReps"]
summary: DRep Summary
description: |
status: stable
Returns aggregate statistics for all registered DReps: total staked
voting power, active count, inactive count, and total count.
responses:
'200':
description: Aggregate DRep statistics.
content:
application/json:
schema: *ApiDRepSummary
/dreps/suggested:
get:
operationId: suggestedDReps
tags: ["DReps"]
summary: Suggested DReps
description: |
status: stable
Returns a random selection of DReps suitable for delegation.
DReps are ranked by delegated voting power. The top 35 (largest) are
excluded to encourage stake distribution. From the remainder, only
active DReps with off-chain metadata and `do_not_list: false` are
considered. A random sample of up to `count` is returned.
parameters:
- in: query
name: count
required: false
schema:
type: integer
minimum: 0
maximum: 200
default: 20
description: Number of DReps to return (default 20, max 200). A value of 0 returns an empty array.
responses:
'200':
description: Random sample of suggested DReps.
content:
application/json:
schema:
type: array
items: *ApiDRepInfo
/dreps/{drepId}:
get:
operationId: getDRep
tags: ["DReps"]
summary: Get DRep
description: |
status: stable
Returns full data for the given DRep, including the complete CIP-0119
off-chain metadata in the `metadata` field (or null if the DRep has no
anchor, metadata has not yet been fetched, or hash verification failed).
**Note:** Results are served from a cache with a ~15-minute TTL. A
recently deregistered DRep may still appear until the next cache refresh.
**Security note:** Metadata fields (name, objectives, references, payment
address) are attacker-controlled content passed through verbatim from the
DRep's anchor URL. Clients must treat this data as untrusted.
Returns 404 for the always-abstain and always-no-confidence sentinels,
and for unknown DRep IDs. Returns 400 for malformed DRep IDs.
parameters:
- *parametersDRepId
responses:
'200':
description: DRep data with embedded metadata.
content:
application/json:
schema: *ApiDRepInfo
'400':
description: Malformed DRep ID.
content:
application/json:
schema: *errBadRequest
'404':
description: The requested DRep was not found.
content:
application/json:
schema: *errNotFound
/dreps/{drepId}/wallets/{walletId}:
put:
operationId: joinDRep
tags: ["DReps"]
summary: Join
description: |
status: stable
Delegate all votes from the given wallet to the given DRep or
case abstain or no-confidence
parameters:
- *parametersDRepId
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiWalletPassphrase
responses: *responsesJoinDRep
/wallets/{walletId}/coin-selections/random:
post:
operationId: selectCoins
tags: ["Coin Selections"]
summary: Random
description: |
status: stable
Select coins to cover the given set of payments.
Uses the
Random-Improve coin selection algorithm.
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: |
status: under development
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: |
status: stable
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: |
status: stable
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: |
status: stable
Return the UTxO 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: |
status: stable
Return information about a Byron wallet.
parameters:
- *parametersWalletId
responses: *responsesGetByronWallet
delete:
operationId: deleteByronWallet
tags: ["Byron Wallets"]
summary: Delete
description: |
⚠️ 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: |
status: stable
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: |
status: stable
⚠️ 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: |
status: stable
⚠️ This endpoint is available for `random` wallets only. Any
attempt to call this endpoint on another type of wallet will result in
a `403 Forbidden` error from the server.
parameters:
- *parametersWalletId
- *parametersAddressId
responses: *responsesPutRandomAddress
/byron-wallets/{walletId}/payment-fees:
post:
operationId: postByronTransactionFee
tags: ["Byron Transactions"]
summary: Estimate Fee
# ADP-908 - Deprecated soon
deprecated: false
description: |
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: |
status: stable
Select coins to cover the given set of payments.
Uses the
Random-Improve coin selection algorithm.
Note: 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: |
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: |
status: stable
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: |
status: stable
Give useful information about the structure of a given address.
parameters:
- *parametersAddressId
responses: *responsesInspectAddress
/addresses:
post:
operationId: postAnyAddress
tags: ["Addresses"]
summary: Construct Address
description: |
status: stable
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: |
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: |
status: stable
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: |
status: stable
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: |
status: stable
Get a shared wallet for a given wallet id.
parameters:
- *parametersWalletId
responses: *responsesGetSharedWallet
delete:
operationId: deleteSharedWallet
tags: ["Shared Wallets"]
summary: Delete
description: |
Return the UTxO 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
/shared-wallets/{walletId}/utxo:
get:
operationId: getSharedWalletUtxoSnapshot
tags: ["Shared 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
/shared-wallets/{walletId}/payment-script-template:
patch:
operationId: patchSharedWalletInPayment
tags: ["Shared Wallets"]
summary: Update Payment
description: |
status: stable
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 incomplete 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: |
status: stable
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 incomplete 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}/transactions-construct:
post:
operationId: constructSharedTransaction
tags: ["Shared Transactions"]
summary: Construct
description: |
status: stable
Create a transaction to be signed from the shared wallet.
Works for the following fields:
- payments
- metadata
- validity_interval
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiConstructTransactionData
responses: *responsesConstructTransaction
/shared-wallets/{walletId}/transactions-decode:
post:
operationId: decodeSharedTransaction
tags: ["Shared Transactions"]
summary: Decode
description: |
status: stable
Decode a serialized transaction, either freshly constructed,
partially signed or fully-signed.
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiDecodeTransactionPostData
responses: *responsesDecodedTransaction
/shared-wallets/{walletId}/transactions-sign:
post:
operationId: signSharedTransaction
tags: ["Shared Transactions"]
summary: Sign
description: |
status: stable
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
/shared-wallets/{walletId}/transactions-submit:
post:
operationId: submitSharedTransaction
tags: ["Shared Transactions"]
summary: Submit
description: |
status: stable
Submit a transaction that was already created and fully signed.
Fails for foreign transactions that is transactions which lack
the wallet's inputs and withdrawals.
parameters:
- *parametersWalletId
requestBody:
required: true
content:
application/json:
schema: *ApiSignedTransactionEncoded
responses: *responsesPostExternalTransaction
/shared-wallets/{walletId}/transactions:
get:
operationId: listSharedTransactions
tags: ["Shared Transactions"]
summary: List
description: |
Get transaction by id.
parameters:
- *parametersWalletId
- *parametersTransactionId
- *parametersMetadataFormat
responses: *responsesGetTransaction
/shared-wallets/{walletId}/keys/{index}:
post:
operationId: postAccountKeyShared
tags: ["Shared Keys"]
summary: Create Account Public Key
description: |
status: stable
Derive an account public key for any account index. For this key derivation to be possible,
the wallet must have been created from mnemonic.
Note: 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: |
status: stable
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: |
status: stable
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`.
Note: 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: |
status: stable
Return a list of known addresses, ordered from newest to oldest
parameters:
- *parametersWalletId
- *parametersAddressState
responses: *responsesListAddresses
/blocks/latest/header:
get:
operationId: getBlocksLatestHeader
tags: ["Node"]
summary: Block Header
description: |
status: stable
Return the latest block-header available at the chain source
responses:
<<: *responsesErr406
200:
description: OK
content:
application/json:
schema: *ApiBlockHeader