From 81dfc445df622c9370caef21310b4d7fb5fafeb1 Mon Sep 17 00:00:00 2001 From: William King Noel Bot Date: Thu, 27 May 2021 02:14:08 +0000 Subject: [PATCH] docs: Merge pull request #2674 from input-output-hk/piotr/adp-925/test-failfetch-metadata Add test checking fail to fetch asset metadata 7426ccc17ecffcc112abf5e8382bcb89cb24f771 --- api/v2021-05-26/README.md | 28 + api/v2021-05-26/index.html | 19 + api/v2021-05-26/swagger.yaml | 5539 ++++++++++++++++++++++++++++++++++ 3 files changed, 5586 insertions(+) create mode 100644 api/v2021-05-26/README.md create mode 100644 api/v2021-05-26/index.html create mode 100644 api/v2021-05-26/swagger.yaml diff --git a/api/v2021-05-26/README.md b/api/v2021-05-26/README.md new file mode 100644 index 00000000000..53da2462ac3 --- /dev/null +++ b/api/v2021-05-26/README.md @@ -0,0 +1,28 @@ +# API Specification + +The specification is written using [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (known today as OpenAPI). + +# How to + +## Preview a local specification file + +Serve the content of this directory through any HTTP server, for instance: + +``` +$ python -m SimpleHTTPServer +Serving HTTP on 0.0.0.0 port 8000 ... +``` + +``` +$ python3 -m http.server +Serving HTTP on 0.0.0.0 port 8000 ... +``` + +Then, browse your localhost on port 8000. + + +## Preview a specification file hosted on a remote machine + +- Visit https://rebilly.github.io/ReDoc/ +- Provide a URL to the spec file +- Click on 'TRY IT' diff --git a/api/v2021-05-26/index.html b/api/v2021-05-26/index.html new file mode 100644 index 00000000000..363d7f5244f --- /dev/null +++ b/api/v2021-05-26/index.html @@ -0,0 +1,19 @@ + + + + Cardano Wallet Backend API Documentation + + + + + + + + + + + + + + + diff --git a/api/v2021-05-26/swagger.yaml b/api/v2021-05-26/swagger.yaml new file mode 100644 index 00000000000..b09d2a5b972 --- /dev/null +++ b/api/v2021-05-26/swagger.yaml @@ -0,0 +1,5539 @@ +openapi: 3.0.0 +info: + title: Cardano Wallet Backend API + version: 2021.5.26 + license: + name: Apache-2.0 + url: https://raw.githubusercontent.com/input-output-hk/cardano-wallet/master/LICENSE + description: | +

+externalDocs: + description: Need more? Click here to access our API guide and walkthrough. + url: https://github.com/input-output-hk/cardano-wallet/wiki + +servers: + - url: https://localhost:8090/v2/ + +############################################################################# +# # +# FIELDS # +# # +############################################################################# + +x-date: &date + type: string + format: iso-8601-date-and-time + example: 2019-02-27T14:46:45Z + +x-slotNumber: &slotNumber + type: integer + description: The zero-based slot index within an epoch. + minimum: 0 + example: 1337 + +x-stakePoolsNumber: &stakePoolsNumber + type: integer + minimum: 0 + example: 100 + +x-numberOfSeconds: &numberOfSeconds + type: object + required: + - quantity + - unit + properties: + quantity: + type: number + minimum: 0.0 + example: 10.0 + unit: + type: string + enum: ["second"] + +x-epochNumber: &epochNumber + type: integer + description: An epoch is a time period which is divided into slots. + minimum: 0 + example: 14 + +x-epochInfo: &epochInfo + type: object + required: + - epoch_number + - epoch_start_time + properties: + epoch_number: *epochNumber + epoch_start_time: *date + +x-blockId: &blockId + description: The hash of genesis block + type: string + format: hex + maxLength: 64 + minLength: 64 + example: 3c07030e36bfffe67e2e2ec09e5293d384637cd2f004356ef320f3fe6c52041a + +x-absoluteSlot: &absoluteSlot + type: integer + description: The 0-based slot index starting from genesis of the blockchain. + minimum: 0 + example: 8086 + +x-numberOfSlots: &numberOfSlots + type: object + required: + - quantity + - unit + properties: + quantity: + type: integer + minimum: 0 + example: 42000 + unit: + type: string + enum: ["slot"] + +x-numberOfBlocks: &numberOfBlocks + type: object + required: + - quantity + - unit + properties: + quantity: + type: integer + minimum: 0 + example: 1337 + unit: + type: string + enum: + - block + example: "block" + +x-blockReference: &blockReference + description: A reference to a particular time slot, and the block height at that point. + type: object + required: + - absolute_slot_number + - slot_number + - epoch_number + - time + - height + properties: + absolute_slot_number: *absoluteSlot + slot_number: *slotNumber + epoch_number: *epochNumber + time: *date + height: *numberOfBlocks + +x-slotId: &slotId + description: A slot identifier, given by epoch number and local slot index. + type: object + required: + - epoch_number + - slot_number + properties: + epoch_number: *epochNumber + slot_number: *slotNumber + +x-slotReference: &slotReference + description: A reference to a particular time slot. + type: object + required: + - absolute_slot_number + - slot_number + - epoch_number + - time + properties: + absolute_slot_number: *absoluteSlot + epoch_number: *epochNumber + slot_number: *slotNumber + time: *date + +x-genesisBlock: &genesisBlock + description: A reference to a particular block. + type: object + required: + - slot_number + - epoch_number + properties: + slot_number: + <<: *slotNumber + maximum: 0 + example: 0 + epoch_number: + <<: *epochNumber + maximum: 0 + example: 0 + +x-percentage: &percentage + type: object + required: + - quantity + - unit + properties: + quantity: + type: number + minimum: 0 + maximum: 100 + example: 42 + unit: + type: string + enum: + - percent + +x-microseconds: µ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 + +x-addressState: &addressState + type: string + enum: + - used + - unused + +x-stakePoolId: &stakePoolId + type: string + format: hex|bech32 + example: pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm + description: A unique identifier for the pool. + +x-walletAccountPubkey: &walletAccountPubkey + description: An extended account public key (public key + chain code) + type: string + format: hex + minLength: 128 + maxLength: 128 + example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 + +x-cosigner: &cosigner + type: string + pattern: "^(cosigner#)[0-9]+$" + +x-cosigners: &cosigners + description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#" + type: object + additionalProperties: *walletAccountPubkey + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^(cosigner#)[0-9]+$' + example: + - {"cosigner#0": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1"} + +x-self: &self + type: string + enum: + - self + +x-accountPubkeyOrSelf: &accountPubkeyOrSelf + nullable: false + oneOf: + - <<: *walletAccountPubkey + title: public key + - <<: *self + title: self + +x-cosignersEntry: &cosignersEntry + description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#"or 'self' + type: object + additionalProperties: *accountPubkeyOrSelf + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^(cosigner#)[0-9]+$' + example: + - {"cosigner#0": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1"} + - {"cosigner#0": "self"} + +x-walletId: &walletId + description: A unique identifier for the wallet + type: string + format: hex + maxLength: 40 + minLength: 40 + example: 2512a00e9653fe49a44a5886202e24d77eeb998f + +x-walletDiscovery: &walletDiscovery + description: Mechanism used for discovering addresses. + type: string + enum: + - random + - sequential + example: sequential + +x-walletName: &walletName + type: string + maxLength: 255 + minLength: 1 + example: Alan's Wallet + +x-poolMetadataSource: &poolMetadataSource + description: | + Pool metadata source. This sets the metadata fetching strategy. + + Possible values are + * none -> no fetching + * direct -> direct fetching + * uri -> use SMASH server + type: string + pattern: '^(none|direct|https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?)$' + example: https://smash.cardano-mainnet.iohk.io/ + +x-credentialPubKey: &credentialPubKey + description: A public key (public key without chain code) for credential - 32 bytes + type: string + format: bech32 + pattern: "^((addr_vk)|(stake_vk))1[0-9a-z]*$" + example: + - stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d + - addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2 + +x-validationLevel: &validationLevel + description: | + Script validation level. Required validation sifts off scripts that would not + be accepted by the ledger. Recommended level filters out scripts that do not pass + required validation and additionally when: + * 'all' is non-empty + * there are redundant timelocks in a given level + * there are no duplicated verification keys in a given level + * 'at_least' coeffcient is positive + * 'all', 'any' are non-empty and `'at_least' has no less elements in the list + than the coeffcient after timelocks are filtered out. + + type: string + enum: + - required + - recommended + +x-anyAddress: &anyAddress + description: A Shelley address representing either enterprise, reward account or delegating address + type: string + format: bech32 + pattern: "^((addr)|(stake)|(addr_test)|(stake_test))1[0-9a-z]*$" + example: + - stake17xt2z3pa7etaxp7jurdg0m8jhsmtp4r2z56pd3a5q3jhxycdxzmx9 + - addr1wy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5taclc6dnd8e + - addr1xy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5tacluk59zrmajh6vra9cx6slk090pkkr2x59f5zmrmgpr9wvfs37hjk4 + +x-ScriptValue: &ScriptValue + oneOf: + - title: Key Hash + description: Leaf value for a script designating a required verification key hash. + type: string + format: bech32 + pattern: "^((addr_shared_vkh)|(stake_shared_vkh))1[0-9a-z]*$" + + - title: All + type: object + required: + - all + properties: + all: + description: Script primitive for which all signing keys corresponding to all list elements' verification keys are expected to make the script valid. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValue" + + - title: Any + type: object + required: + - any + properties: + any: + description: Script primitive for which a signing key corresponding to any of the list elements' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValue" + + - title: Some + type: object + required: + - some + properties: + some: + description: Script primitive for which at least a given number of signing keys corresponding to the list elements' verification keys are expected to make the script valid. + type: object + required: + - at_least + - from + properties: + at_least: + type: integer + minimum: 1 + maximum: 255 + from: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValue" + + - title: Active from slot + type: object + required: + - active_from + properties: + active_from: + description: Transaction is only valid starting at the specified slot number (`≥ active_from`). + type: integer + minimum: 0 + + - title: Active until slot + type: object + required: + - active_until + properties: + active_until: + description: Transaction is only valid before the specified slot number (`< active_until`). + type: integer + minimum: 0 + +x-script: &script + <<: *ScriptValue + +x-ScriptTemplateValue: &ScriptTemplateValue + oneOf: + - title: Cosigner + description: Leaf value for a script designating a cosigner co-sharing the script. + type: string + pattern: "^(cosigner#)[0-9]*$" + + - title: All + type: object + required: + - all + properties: + all: + description: Script primitive for which all signing keys corresponding to all list cosigners' verification keys are expected to make the script valid. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptTemplateValue" + + - title: Any + type: object + required: + - any + properties: + any: + description: Script primitive for which a signing key corresponding to any of the list cosigners' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptTemplateValue" + + - title: Some + type: object + required: + - some + properties: + some: + description: Script primitive for which at least a given number of signing keys corresponding to the list cosigners' verification keys are expected to make the script valid. + type: object + required: + - at_least + - from + properties: + at_least: + type: integer + minimum: 1 + maximum: 255 + from: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptTemplateValue" + + - title: Active from slot + type: object + required: + - active_from + properties: + active_from: + description: Transaction is only valid starting at the specified slot number (`≥ active_from`). + type: integer + minimum: 0 + + - title: Active until slot + type: object + required: + - active_until + properties: + active_until: + description: Transaction is only valid before the specified slot number (`< active_until`). + type: integer + minimum: 0 + +x-scriptTemplate: &scriptTemplate + type: object + required: + - cosigners + - template + properties: + cosigners: *cosigners + template: *ScriptTemplateValue + +x-scriptTemplateEntry: &scriptTemplateEntry + type: object + required: + - cosigners + - template + properties: + cosigners: *cosignersEntry + template: *ScriptTemplateValue + +x-CredentialValue: &CredentialValue + nullable: false + oneOf: + - <<: *credentialPubKey + title: public key + - <<: *script + title: script + example: + any: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + + - stake_shared_vkh1nqc00hvlc6cq0sfhretk0rmzw8dywmusp8retuqnnxzajtzhjg5 + + - all: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp + + - any: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - all: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp + + - some: + at_least: 2 + from: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp + +x-settings: &settings + description: Settings + type: object + required: + - pool_metadata_source + properties: + pool_metadata_source: + <<: *poolMetadataSource + description: | + Select stake pool metadata fetching strategy: + - `none` - metadata is not fetched at all, + - `direct` - metadata is fetched directly URLs registered on chain, + - `uri` - metadata is fetched from an external Stake-Pool Metadata Aggregation Server (SMASH) + + After update existing metadata will be dropped forcing it to re-sync automatically with the new setting. + +x-assetName: &assetName + type: string + description: | + The asset on-chain type which acts as a sub-identifier within a + policy. Although we call it "asset name", the value needn't be + text, and it could even be empty. + + For policies with a single fungible asset item, asset name is + typically an empty string. + + This value can be up to 32 bytes of arbitrary data (which is 64 + hexadecimal digits). + format: hex + maxLength: 64 + example: "" + +x-assetPolicyId: &assetPolicyId + type: string + description: | + A unique identifier of the asset's monetary policy. The policy + controls how assets of this kind are created and destroyed. + + The contents are the blake2b-224 hash of the monetary policy + script, encoded in hexadecimal. + format: hex + minLength: 56 + maxLength: 56 + example: 65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b + +x-assetFingerprint: &assetFingerprint + type: string + description: | + A user-facing short fingerprint which combines the `policy_id` and `asset_name` + to allow for an easier human comparison of assets. Note that it is generally + **not okay** to use this fingerprint as a unique identifier for it is not collision + resistant. Yet within the context of a single wallet, it makes for a (rather) + short user-facing comparison mean. + pattern: "^(asset)1[0-9a-z]*$" + maxLength: 44 + minLength: 44 + example: asset1rjklcrnsdzqp65wjgrg55sy9723kw09mlgvlc3 + +x-assetMetadataName: &assetMetadataName + type: string + maxLength: 50 + minLength: 1 + description: | + A human-readable name for the asset, intended for display in user + interfaces. + example: SwaggerCoin + +x-assetMetadataTicker: &assetMetadataTicker + type: string + maxLength: 5 + minLength: 2 + description: | + An optional human-readable very short name or acronym for the + asset, intended for display in user interfaces. If `ticker` is not + present, then `name` will be used, but it might be truncated to + fit within the available space. + example: SWAG + +x-assetMetadataDescription: &assetMetadataDescription + description: | + A human-readable description for the asset. Good for display in + user interfaces. + type: string + maxLength: 500 + +x-assetMetadataDecimals: &assetMetadataDecimals + type: integer + description: | + Defines a scaling factor for the asset of 10-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. + + type: integer + minimum: 10 + maximum: 100000 + example: 20 + default: 20 + +x-walletState: &walletState + <<: *syncProgress + description: Whether a wallet is ready to use or still syncing + +x-walletBalance: &walletBalance + description: Wallet current Ada balance(s). + type: object + required: + - available + - reward + - total + properties: + available: + <<: *amount + description: Available Ada UTxO balance (funds that can be spent without condition). + reward: + <<: *amount + description: The Ada balance of the reward account for this wallet. + total: + <<: *amount + description: Total Ada balance (available balance plus pending change and reward balance). + +x-assetQuantity: &assetQuantity + type: integer + description: | + Number of assets for the given `policy_id` and `asset_name`. + minimum: 0 + +x-walletAsset: &walletAsset + description: | + An asset on the Cardano blockchain. An asset is uniquely identified by + its `policy_id` and `asset_name` (together, these form the _asset id_). + + Two assets with the same `asset_name` and `policy_id` are + interchangeable. Yet, different assets with a same `policy_id` but + different `asset_name` are treated as separate assets, as are two + assets with the same `asset_name` but different `policy_id`. + type: object + required: + - policy_id + - asset_name + - quantity + properties: + policy_id: *assetPolicyId + asset_name: *assetName + quantity: *assetQuantity + +x-walletAssets: &walletAssets + description: A flat list of assets. + type: array + items: *walletAsset + +x-assetMint: &assetMint + type: object + required: + - policy_id + - asset_name + - quantity + properties: + policy_id: *assetPolicyId + asset_name: *assetName + fingerprint: *assetFingerprint + quantity: + type: integer + description: | + Positive values mean creation and negative values mean + destruction. + +x-walletAssetsBalance: &walletAssetsBalance + description: | + Current non-Ada asset holdings of the wallet. + + The amount of assets available to spend may be less than the total + unspent assets due to transaction change amounts which are yet to + be fully confirmed (pending). + type: object + required: + - available + - total + properties: + available: + <<: *walletAssets + description: | + Available UTxO asset balances (funds that can be spent without + condition). + total: + <<: *walletAssets + description: | + Total asset balances (available balances plus pending change balances). + +x-byronWalletBalance: &byronWalletBalance + description: Byron wallet's current balance(s) + type: object + required: + - available + - total + properties: + available: + <<: *amount + description: Available balance (funds that can be spent) + total: + <<: *amount + description: Total balance (available balance plus pending change) + +x-walletPassphraseInfo :: &walletPassphraseInfo + description: Information about the wallet's passphrase + type: object + required: + - last_updated_at + properties: + last_updated_at: *date + +x-transactionId: &transactionId + description: A unique identifier for this transaction + type: string + format: hex + maxLength: 64 + minLength: 64 + example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 + +x-transactionInsertedAt: &transactionInsertedAt + description: | + + 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-transactionOutputs: &transactionOutputs + description: A list of target outputs + type: array + minItems: 0 + items: + type: object + required: + - address + - amount + properties: + address: *addressId + amount: *amount + assets: *walletAssets + +x-delegationAction: &delegationAction + description: | + A delegation action. + + Pool id is only required for "join". + type: object + required: + - action + properties: + action: + type: string + enum: ["quit", "join"] + pool: *stakePoolId + +x-rewardAccountPath: &rewardAccountPath + type: array + minItems: 5 + maxItems: 5 + items: + type: string + +x-certificate: &certificate + description: | + A delegation certificate + + Only for 'join_pool' the 'pool' property is required. + type: object + required: + - certificate_type + - reward_account_path + properties: + certificate_type: + type: string + enum: ["join_pool", "quit_pool", "register_reward_account"] + pool: + <<: *stakePoolId + reward_account_path: + <<: *rewardAccountPath + +x-transactionRedemptionRequest: &transactionRedemptionRequest + <<: *walletMnemonicSentence + description: | + When provided, attempts to withdraw rewards from the default stake address corresponding to the given mnemonic. + + Should the rewards be null or too small to be worth withdrawing (i.e. the cost of adding them into the transaction + is more than their own intrinsic value), the server will reject the request with a `withdrawal_not_worth` error. + + withdrawal field | reward balance | result + --- | --- | --- + any recovery phrase | too small | x Error 403 `withdrawal_not_worth` + any recovery phrase | big enough | ✓ withdrawal generated + +x-transactionWithdrawalRequestSelf: &transactionWithdrawalRequestSelf + type: string + enum: ["self"] + description: | + When provided, instruments the server to automatically withdraw rewards from the source wallet when they are deemed + sufficient (i.e. they contribute to the balance for at least as much as they cost). + + As a consequence, the resulting transaction may or may not have a withdrawal object. Summarizing: + + withdrawal field | reward balance | result + --- | --- | --- + `null` | too small | ✓ no withdrawals generated + `null` | big enough | ✓ no withdrawals generated + `"self"` | too small | ✓ no withdrawals generated + `"self"` | big enough | ✓ withdrawal generated + +x-transactionWithdrawals: &transactionWithdrawals + description: A list of withdrawals from stake addresses. + type: array + minItems: 0 + items: + type: object + additionalProperties: false + required: + - stake_address + - amount + properties: + stake_address: *stakeAddress + amount: *amount + +x-transactionMint: &transactionMint + description: | +

status: ⚠ under development

+ + _This field is not implemented yet, and will always be empty._ + + Assets minted (created) or unminted (destroyed) + + This amount contributes to the total transaction value. + + Positive values denote creation of assets and negative values + denote the reverse. + type: array + minItems: 0 + items: *assetMint + +x-derivationSegment: &derivationSegment + description: | + An individual segment within a derivation path. + + 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-transactionChange: &transactionChange + description: A list of transaction change outputs. + type: array + minItems: 0 + items: + type: object + required: + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + assets: *walletAssets + derivation_path: *derivationPath + +x-transactionResolvedInputs: &transactionResolvedInputs + description: A list of transaction inputs + type: array + minItems: 1 + items: + type: object + required: + - id + - index + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + assets: *walletAssets + id: *transactionId + derivation_path: *derivationPath + index: + type: integer + minimum: 0 + +x-transactionResolvedWithdrawals: &transactionResolvedWithdrawals + description: A list of withdrawals from stake addresses. + type: array + minItems: 0 + items: + type: object + additionalProperties: false + required: + - stake_address + - derivation_path + - amount + properties: + stake_address: *stakeAddress + derivation_path: *derivationPath + amount: *amount + +x-signedTransactionBlob: &signedTransactionBlob + description: Signed transaction message binary blob. + type: string + format: binary + +x-transactionStatus: &transactionStatus + description: | + Current transaction status. + + ``` + *---------* *-----------* + | |----------> EXPIRED | + | | (ttl) *-----------* + -------> PENDING | + | <----------------* + | | | + *---------* (rollback) + | | + (in ledger) *-----------* + | | | + *---------------> IN_LEDGER | + | | + *-----------* + ``` + type: string + enum: + - pending + - in_ledger + - expired + +x-transactionSerializedMetadata: &transactionSerializedMetadata + type: string + format: base64 + description: Transaction metadata, serialized according to the expected on-chain binary format, base64-encoded. + +x-transactionMetadata: &transactionMetadata + description: | + **⚠️ WARNING ⚠️** + + _Please note that metadata provided in a transaction will be + stored on the blockchain forever. Make sure not to include any sensitive data, + in particular personally identifiable information (PII)._ + + Extra application data attached to the transaction. + + Cardano allows users and developers to embed their own + authenticated metadata when submitting transactions. Metadata can + be expressed as a JSON object with some restrictions: + + 1. All top-level keys must be integers between `0` and `2^64 - 1`. + + 2. Each metadata value is tagged with its type. + + 3. Strings must be at most 64 bytes when UTF-8 encoded. + + 4. Bytestrings are hex-encoded, with a maximum length of 64 bytes. + + Metadata aren't stored as JSON on the Cardano blockchain but are + instead stored using a compact binary encoding (CBOR). + + The binary encoding of metadata values supports three simple types: + + * Integers in the range `-(2^64 - 1)` to `2^64 - 1` + * Strings (UTF-8 encoded) + * Bytestrings + + And two compound types: + + * Lists of metadata values + * Mappings from metadata values to metadata values + + It is possible to transform any JSON object into this schema. + + However, if your application uses floating point values, they will + need to be converted somehow, according to your + requirements. Likewise for `null` or `bool` values. When reading + metadata from chain, be aware that integers may exceed the + javascript numeric range, and may need special "bigint" parsing. + + type: object + nullable: true + additionalProperties: + $ref: "#/components/schemas/TransactionMetadataValue" + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^[0-9]+$' + example: + 0: { "string": "cardano" } + 1: { "int": 14 } + 2: { "bytes": "2512a00e9653fe49a44a5886202e24d77eeb998f" } + 3: { "list": [ { "int": 14 }, { "int": 42 }, { "string": "1337" } ] } + 4: { "map": [{ "k": { "string": "key" }, "v": { "string": "value" }}, { "k": { "int": 14 }, "v": { "int": 42 } }] } + +x-transactionTTL: &transactionTTL + description: | + The TTL (time to live) is the time period in which the transaction + will be accepted into node mempools. + + After the TTL has lapsed, the transaction is considered + expired. At this point, nodes will give up on broadcasting the + transaction, and the wallet will release the funds allocated to + the transaction so they can be used for other payments. + + The TTL should be long enough that the transaction has time to be + propagated through the network and confirmed, but short enough so + that - in the event of failures - UTxO are returned to the wallet + in a timely manner. + + The TTL value is given in seconds. It will be converted to a slot + number internally. + + If the TTL is not provided for a payment, a reasonable default + value will be used. + + <<: *numberOfSeconds + +x-stakePoolApparentPerformance: &stakePoolApparentPerformance + description: | + Apparent performance of the stake pool over past epochs. This indicator is computed + using data available to the server. In particular, the server can't reliably know the + stake distribution of past epochs without being during those epochs. The performance + are therefore an average measure that is more accurate for servers that are online + often. + + The performance is a float with double-precision which is _typically_ within `0` and `1`: + + - `0` means that a pool is not performing well. + - `1` means that a pool is performing _as expected_. + - above `1` means the pool is performing beyond expectations. + + Pools that are lucky enough to win most of their slots early in the epoch will tend to look + like they're over-performing for a while. Having a wallet regularly connected to the network + would harmonize the performance and give better results. + + type: number + minimum: 0 + example: 0.5053763440860215 + + +x-stakePoolMetadata: &stakePoolMetadata + description: | + Information about the stake pool. + type: object + required: + - ticker + - name + - homepage + additionalProperties: false + properties: + ticker: + type: string + minLength: 3 + maxLength: 5 + example: IOHK + name: + type: string + minLength: 1 + maxLength: 50 + description: + type: string + maxLength: 255 + homepage: + type: string + format: uri + example: https://iohk.io + +x-stakePoolRetirement: &stakePoolRetirement + <<: *epochInfo + description: | + The epoch in which a stake pool retires. + + May be omitted if the wallet hasn't yet found a retirement certificate + for this stake pool. + +x-stakePoolPledge: &stakePoolPledge + <<: *amount + description: | + Minimal stake amount that a stake pool is willing to honor. + + May be omitted if the wallet hasn't found the pool's registration cerificate yet. + +x-stakePoolCost: &stakePoolCost + <<: *amount + description: | + Estimated cost set by the pool operator when registering his pool. + This fixed cost is taken from each reward earned by the pool before splitting rewards between stakeholders. + + May be omitted if the wallet hasn't found the pool's registration cerificate yet. + +x-stakePoolMargin: &stakePoolMargin + <<: *percentage + description: | + Variable margin on the total reward given to an operator before splitting rewards between stakeholders. + + May be omitted if the wallet hasn't found the pool's registration cerificate yet. + +x-stakePoolSaturation: &stakePoolSaturation + type: number + minimum: 0 + description: | + Saturation-level of the pool based on the desired number of pools aimed by the network. + A value above `1` indicates that the pool is saturated. + + The `non_myopic_member_rewards` take oversaturation into account, as specified by the [specs](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec). + + The saturation is based on the live `relative_stake`. The saturation at the end of epoch e, + will affect the rewards paid out at the end of epoch e+3. + + example: 0.74 + +x-non-myopic-member-rewards: &nonMyopicMemberRewards + <<: *amount + description: | + The rewards the wallet can expect to receive at the end of an epoch, in the long term, if delegating to + this pool. + + For more details, see the + [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec) + document. + +x-stakePoolMetrics: &stakePoolMetrics + type: object + required: + - relative_stake + - non_myopic_member_rewards + - produced_blocks + - saturation + properties: + non_myopic_member_rewards: *nonMyopicMemberRewards + relative_stake: + <<: *percentage + description: | + The live pool stake relative to the *total* stake. + + For more details, see the section "Relative Stake: Active vs Total" in + [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec). + saturation: *stakePoolSaturation + produced_blocks: + <<: *numberOfBlocks + description: Number of blocks produced by a given stake pool in its lifetime. + +x-stakePoolFlag: &stakePoolFlag + type: string + enum: + - delisted + +x-stakePoolFlags: &stakePoolFlags + type: array + description: | + Various flags applicable to stake pools. Possible flags: + + | flag | description | + | --- | --- | + | delisted | The pool is marked as delisted on a configured SMASH server; metadata for this pool have therefore been dropped. | + items: *stakePoolFlag + +x-networkInformationSyncProgress: &networkInformationSyncProgress + <<: *syncProgress + description: | + Estimated synchronization progress of the node with the underlying network. Note that this may + change quite arbitrarily as the node may switch to shorter or longer chain forks. + +x-networkClockSyncProgress: &networkClockSyncProgress + <<: *syncClockProgress + description: | + The status progress of syncing local ntp client aiming to get ntp offset. + +x-networkInformationNtpStatus: &networkInformationNtpStatus + type: object + description: | + [Network Time Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) information of the server. + + **Important:** This piece of information only makes sense when the server runs on the same host machine as the node. + required: + - status + properties: + status: + type: string + enum: + - available + - unavailable + - pending + offset: + type: object + description: | + + 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 + +x-delegationTarget: &delegationTarget + <<: *stakePoolId + description: A unique Stake-Pool identifier (present only if status = `delegating`) + +x-addressIndex: &addressIndex + type: number + minimum: 0 + # 2 ^ 32 - 1, whole range (soft and hard) for random addresses: + maximum: 4294967295 + description: | + An address derivation index. + +x-gCStatus :: &gCStatus + +x-deposits: &deposits + description: A list of deposits associated with a transaction. + type: array + minItems: 0 + items: *amount + +x-minimumCoins: &minimumCoins + description: | + A list of minimum coin values that each output in a payment must satisfy. The values themselves depends on two things: + + - (a) Some updatable protocol parameters fixed by the network. + - (b) The nature of the outputs (i.e. the kind of assets it includes). + + The list is a direct 1:1 mapping of the requested outputs. Said differently, it has the **same number of items** and **items + are ordered in the same way** as **requested outputs** are ordered. In the case where there's no explicitly requested outputs (e.g. + when calculating fee for delegation), this list is empty. + + For example, an output containing only `Ada` may require to be of at least `1 Ada`. An output containing only an hypothetical `AppleCoin` + may require to also carry a minimum of `1.2 Ada`. Note that no matter what, a minimum coin value is always given in Lovelace / Ada. + + > ℹ️ This mechanism is used by the protocol to protect against flooding of the network with worthless assets. By requiring a minimum coin value to every + UTxO, they are given an intrinsic value indexed itself on the value of Ada. + type: array + minItems: 0 + items: *amount + +############################################################################# +# # +# DEFINITIONS # +# # +############################################################################# + +components: + schemas: + ApiAddress: &ApiAddress + type: object + required: + - id + - state + - derivation_path + properties: + id: *addressId + state: *addressState + derivation_path: *derivationPath + + ApiAddressInspect: &ApiAddressInspect + type: object + required: + - address_style + - stake_reference + properties: + address_style: + type: string + enum: + - Shelley + - Icarus + - Byron + stake_reference: + type: string + enum: + - none + - by value + - by pointer + network_tag: + description: Can be null for 'Icarus' and 'Byron' styles. + type: integer + minimum: 0 + spending_key_hash: + type: string + format: base16 + minLength: 56 + maxLength: 56 + spending_key_bech32: + type: string + format: bech32 + stake_key_hash: + type: string + format: base16 + minLength: 56 + maxLength: 56 + stake_key_bech32: + type: string + format: bech32 + script_hash: + type: string + format: base16 + minLength: 64 + maxLength: 64 + script_hash_bech32: + type: string + format: bech32 + pointer: + type: object + additionalProperties: false + required: + - slot_num + - transaction_index + - output_index + properties: + slot_num: + type: integer + minimum: 0 + transaction_index: + type: integer + minimum: 0 + output_index: + type: integer + minimum: 0 + address_root: + description: Only for 'Icarus' and 'Byron' styles. + type: string + format: base16 + derivation_path: + description: Only for 'Byron' style. + type: string + format: base16 + + ApiNetworkTip: &ApiNetworkTip + <<: *slotReference + description: The time slot corresponding the network tip. + + ApiEra: &ApiEra + type: string + enum: + - byron + - shelley + - allegra + - mary + + ApiNetworkInformation: &ApiNetworkInformation + type: object + required: + - sync_progress + - node_tip + - node_era + properties: + sync_progress: *networkInformationSyncProgress + node_tip: *networkInformationNodeTip + network_tip: *ApiNetworkTip + next_epoch: *epochInfo + node_era: *ApiEra + + ApiNetworkClock: &ApiNetworkClock + <<: *networkInformationNtpStatus + + nullableEpochInfo: &nullableEpochInfo + <<: *epochInfo + nullable: True + + ApiEraInfo: &ApiEraInfo + type: object + properties: + byron: *nullableEpochInfo + shelley: *nullableEpochInfo + allegra: *nullableEpochInfo + mary: *nullableEpochInfo + description: | + + If and when each era started or will start. + + The object is keyed by era names. The values either describe the epoch boundary + when the era starts (can be in the future or in the past), or are null if not yet + confirmed on-chain. + + If you need to know the current era, see the `node_era` field of + `GET /network/information`. + + > Due to complications with our current tooling, we cannot mark the era names + > as required, but the keys are in fact always present. + + ApiNetworkParameters: &ApiNetworkParameters + type: object + required: + - genesis_block_hash + - blockchain_start_time + - slot_length + - epoch_length + - security_parameter + - active_slot_coefficient + - decentralization_level + - desired_pool_number + - minimum_utxo_value + - eras + properties: + genesis_block_hash: *blockId + blockchain_start_time: *date + slot_length: *numberOfSeconds + epoch_length: *numberOfSlots + security_parameter: *numberOfBlocks + active_slot_coefficient: *percentage + decentralization_level: *percentage + desired_pool_number: *stakePoolsNumber + minimum_utxo_value: *amount + eras: *ApiEraInfo + + ApiSelectCoinsPayments: &ApiSelectCoinsPayments + type: object + required: + - payments + properties: + payments: *transactionOutputs + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + + ApiSelectCoinsRedemption: &ApiSelectCoinsRedemption + type: object + required: + - payments + - withdrawal + properties: + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + metadata: *transactionMetadata + + ApiSelectCoinsAction: &ApiSelectCoinsAction + type: object + required: + - delegation_action + properties: + delegation_action: *delegationAction + + ApiSelectCoinsData: &ApiSelectCoinsData + type: object + oneOf: + - title: Normal payment + <<: *ApiSelectCoinsPayments + - title: Delegation + <<: *ApiSelectCoinsAction + - title: Reward redemption + <<: *ApiSelectCoinsRedemption + + ApiByronSelectCoinsData: &ApiByronSelectCoinsData + type: object + required: + - payments + properties: + payments: *transactionOutputs + + ApiCoinSelection: &ApiCoinSelection + type: object + required: + - inputs + - outputs + - change + properties: + inputs: *transactionResolvedInputs + outputs: *transactionOutputs + change: *transactionChange + withdrawals: *transactionResolvedWithdrawals + certificates: + type: array + items: *certificate + deposits: *deposits + metadata: *transactionSerializedMetadata + + ApiGCStatus: &ApiGCStatus + type: object + description: | + Gives an indication if metadata GC checking for delisted pools + has run and if so, when. + + Possible values are: + - not_applicable -> we're currently not querying a SMASH server for metadata + - not_started -> the GC hasn't started yet, try again in a short while + - restarting -> the GC thread is currently restarting, try again in short while + - has_run -> the GC has run successfully + + When 'status' is 'restarting' or 'has_run' then the field 'last_run' + is set to the last GC time in UTC. + required: + - status + properties: + status: + type: string + enum: + - not_applicable + - not_started + - restarting + - has_run + last_run: *date + + ApiMaintenanceActionPostData: &ApiMaintenanceActionPostData + type: object + required: + - maintenance_action + description: | + The maintenance action to carry out, current values are + - gc_stake_pools -> trigger looking up delisted pools from the remote SMASH server + properties: + maintenance_action: + type: string + enum: ['gc_stake_pools'] + + ApiMaintenanceAction: &ApiMaintenanceAction + type: object + required: + - gc_stake_pools + properties: + gc_stake_pools: *ApiGCStatus + + ApiStakePool: &ApiStakePool + type: object + required: + - id + - metrics + - cost + - margin + - pledge + - flags + properties: + id: *stakePoolId + metrics: *stakePoolMetrics + cost: *stakePoolCost + margin: *stakePoolMargin + pledge: *stakePoolPledge + metadata: *stakePoolMetadata + retirement: *stakePoolRetirement + flags: *stakePoolFlags + + ApiFee: &ApiFee + type: object + required: + - estimated_min + - estimated_max + - minimum_coins + - deposit + properties: + estimated_min: *amount + estimated_max: *amount + minimum_coins: *minimumCoins + deposit: *amount + + ApiPutAddressesData: &ApiPutAddressesData + type: object + required: + - addresses + properties: + addresses: + <<: *addresses + description: The imported addresses. + + 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))1[0-9a-z]*$" + + ApiAccountKeyShared: &ApiAccountKeyShared + type: string + format: bech32 + pattern: "^((acct_shared_xvk)|(acct_shared_vk))1[0-9a-z]*$" + + ApiTxId: &ApiTxId + type: object + required: + - id + properties: + id: *transactionId + + ApiTransaction: &ApiTransaction + type: object + required: + - id + - amount + - fee + - deposit + - direction + - inputs + - outputs + - withdrawals + - mint + - status + properties: + id: *transactionId + amount: + <<: *amount + description: | + An amount of Ada spent or received, from the perspective of the wallet. + + That is, for outgoing transaction, it represents the amount of Ada consumed + as inputs, minus the amount of Ada spent as fees, as deposits or to addresses + which do not belong to the wallet. + + For incoming transaction, it represents the total amount of Ada received to + addresses that belong to the wallet. + fee: *amount + deposit: *amount + inserted_at: *transactionInsertedAt + expires_at: *transactionExpiresAt + pending_since: *transactionPendingSince + depth: *transactionDepth + direction: *transactionDirection + inputs: *transactionInputs + outputs: *transactionOutputs + withdrawals: *transactionWithdrawals + mint: *transactionMint + status: *transactionStatus + metadata: *transactionMetadata + + ApiWalletDelegationNext: &ApiWalletDelegationNext + type: object + description: Next delegation status becomes active at the start of the second epoch after the corresponding delegation certificate was discovered. The exact moment is specified by changes_at + required: + - status + - changes_at + properties: + status: *delegationStatus + target: *delegationTarget + changes_at: *epochInfo + example: + status: not_delegating + changes_at: + epoch_number: 14 + epoch_start_time: 2020-01-22T10:06:39.037Z + + ApiWalletDelegation: &ApiWalletDelegation + description: Delegation settings + type: object + required: + - active + - next + properties: + active: + type: object + description: Currently active delegation status. + required: + - status + properties: + status: *delegationStatus + target: *delegationTarget + example: + status: delegating + target: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 + next: + type: array + items: *ApiWalletDelegationNext + + ApiWallet: &ApiWallet + type: object + required: + - id + - address_pool_gap + - balance + - assets + - delegation + - name + - state + - tip + properties: + id: *walletId + address_pool_gap: *walletAddressPoolGap + balance: *walletBalance + assets: *walletAssetsBalance + delegation: *ApiWalletDelegation + name: *walletName + passphrase: *walletPassphraseInfo + state: *walletState + tip: *blockReference + + ApiByronWallet: &ApiByronWallet + type: object + required: + - id + - balance + - assets + - discovery + - name + - state + - tip + properties: + id: *walletId + balance: *byronWalletBalance + assets: *walletAssetsBalance + discovery: *walletDiscovery + name: *walletName + passphrase: *walletPassphraseInfo + state: *walletState + tip: *blockReference + + ApiWalletPostData: &ApiWalletPostData + type: object + description: Restore from root private key + required: + - name + - mnemonic_sentence + - passphrase + properties: + name: *walletName + mnemonic_sentence: *walletMnemonicSentence + mnemonic_second_factor: *walletSecondFactor + passphrase: *walletPassphrase + address_pool_gap: *walletAddressPoolGap + + ApiAccountPostData: &ApiAccountPostData + type: object + description: Restore from account public key + required: + - name + - account_public_key + properties: + name: *walletName + account_public_key: *walletAccountPubkey + address_pool_gap: *walletAddressPoolGap + + ApiWalletOrAccountPostData: &ApiWalletOrAccountPostData + type: object + oneOf: + - <<: *ApiWalletPostData + title: shelley + - <<: *ApiAccountPostData + title: shelley (from xpub) + + ApiActiveSharedWallet: &ApiActiveSharedWallet + type: object + required: + - id + - name + - account_index + - address_pool_gap + - payment_script_template + - balance + - assets + - delegation + - state + - tip + properties: + id: *walletId + name: *walletName + account_index: *derivationSegment + address_pool_gap: *walletAddressPoolGap + passphrase: *walletPassphraseInfo + payment_script_template: *scriptTemplate + delegation_script_template: *scriptTemplate + balance: *walletBalance + assets: *walletAssetsBalance + delegation: *ApiWalletDelegation + state: *walletState + tip: *blockReference + + ApiPendingSharedWallet: &ApiPendingSharedWallet + type: object + required: + - id + - name + - account_index + - address_pool_gap + - payment_script_template + - state + properties: + id: *walletId + name: *walletName + account_index: *derivationSegment + address_pool_gap: *walletAddressPoolGap + payment_script_template: *scriptTemplate + delegation_script_template: *scriptTemplate + state: + type: object + required: + - status + properties: + status: + description: | + A pending shared wallet does not have a complete set + of keys, so the only possible status is `incomplete`. + type: string + enum: + - incomplete + + ApiSharedWallet: &ApiSharedWallet + type: object + oneOf: + - title: Pending shared wallet (collecting account public keys for each co-signer) + <<: *ApiPendingSharedWallet + - title: Active shared wallet (account public keys for each co-signers is collected) + <<: *ApiActiveSharedWallet + + ApiSharedWalletPostDataFromMnemonics: &ApiSharedWalletPostDataFromMnemonics + type: object + required: + - name + - mnemonic_sentence + - passphrase + - account_index + - payment_script_template + properties: + name: *walletName + mnemonic_sentence: *walletMnemonicSentence + mnemonic_second_factor: *walletSecondFactor + passphrase: *walletPassphrase + account_index: *derivationSegment + payment_script_template: *scriptTemplateEntry + delegation_script_template: *scriptTemplateEntry + script_validation: *validationLevel + + ApiSharedWalletPostDataFromAccountPubX: &ApiSharedWalletPostDataFromAccountPubX + type: object + required: + - name + - account_public_key + - account_index + - payment_script_template + properties: + name: *walletName + account_public_key: *walletAccountPubkey + 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 Byron wallet's master passphrase. + + ApiWalletMigrationPlanPostData: &ApiWalletMigrationPlanPostData + type: object + required: + - addresses + properties: + addresses: + <<: *addresses + description: The recipient addresses. + + ApiByronWalletMigrationPostData: &ApiByronWalletMigrationPostData + type: object + required: + - passphrase + - addresses + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + addresses: + <<: *addresses + description: The recipient addresses. + + ApiShelleyWalletMigrationPostData: &ApiShelleyWalletMigrationPostData + type: object + required: + - passphrase + - addresses + properties: + passphrase: + <<: *walletPassphrase + description: The wallet's master passphrase. + addresses: + <<: *addresses + description: The recipient addresses. + + ApiWalletUTxOsStatistics: &ApiWalletUTxOsStatistics + type: object + required: + - total + - scale + - distribution + properties: + total: *amount + scale: + type: string + enum: + - log10 + distribution: + type: object + additionalProperties: + type: integer + example: + total: + quantity: 42000000 + unit: lovelace + scale: log10 + distribution: + 10: 1 + 100: 0 + 1000: 8 + 10000: 14 + 100000: 32 + 1000000: 3 + 10000000: 0 + 100000000: 12 + 1000000000: 0 + 10000000000: 0 + 100000000000: 0 + 1000000000000: 0 + 10000000000000: 0 + 100000000000000: 0 + 1000000000000000: 0 + 10000000000000000: 0 + 45000000000000000: 0 + + ApiWalletSignData: &ApiWalletSignData + type: object + required: + - passphrase + - metadata + properties: + passphrase: *lenientPassphrase + metadata: *transactionMetadata + + ApiScript: &ApiScript + <<: *script + + ApiPubKey: &ApiPubKey + <<: *credentialPubKey + + AnyAddress: &AnyAddress + type: object + required: + - address + properties: + address: *anyAddress + + ApiCredential: &ApiCredential + <<: *CredentialValue + + ApiAddressData: &ApiAddressData + type: object + nullable: false + properties: + payment: *ApiCredential + stake: + <<: *ApiCredential + example: stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d + validation: *validationLevel + + ApiByronWalletRandomPostData: &ApiByronWalletRandomPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["random"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiByronWalletRandomXPrvPostData: &ApiByronWalletRandomXPrvPostData + type: object + description: patate + required: + - name + - encrypted_root_private_key + - passphrase_hash + properties: + style: + type: string + enum: ["random"] + name: *walletName + encrypted_root_private_key: + <<: *walletEncryptedRootPrivateKey + deprecated: true + + passphrase_hash: + <<: *walletPassphraseHash + deprecated: true + + ApiByronWalletIcarusPostData: &ApiByronWalletIcarusPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["icarus"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiByronWalletTrezorPostData: &ApiByronWalletTrezorPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["trezor"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiByronWalletLedgerPostData: &ApiByronWalletLedgerPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["ledger"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiWalletPutData: &ApiWalletPutData + type: object + properties: + name: *walletName + + ApiPostAccountKeyData: &ApiPostAccountKeyData + type: object + required: + - passphrase + - format + properties: + passphrase: *walletPassphrase + format: *keyExtended + + ApiSettingsPutData: &ApiSettingsPutData + type: object + properties: + settings: *settings + + ApiSmashServer: &ApiSmashServer + type: string + pattern: '^https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?$' + example: https://smash.cardano-mainnet.iohk.io/ + description: A base SMASH uri without endpoint path. + + ApiHealthCheck: &ApiHealthCheck + type: object + required: + - health + properties: + health: + type: string + enum: ["available", "unavailable", "unreachable", "no_smash_configured"] + description: | + The status of the SMASH server. Possible values are: + + health | description + --- | --- + `"available"` | server is awaiting your requests + `"unavailable"` | server is running, but currently unavailable, try again in a short time + `"unreachable"` | server could not be reached or didn't return a health status + `"no_smash_configured"` | SMASH is currently not configured, adjust the Settings first + + ApiWalletPutPassphraseData: &ApiWalletPutPassphraseData + type: object + required: + - old_passphrase + - new_passphrase + properties: + old_passphrase: + <<: *walletPassphrase + description: The current passphrase. + new_passphrase: + <<: *walletPassphrase + description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds). + + ApiByronWalletPutPassphraseData: &ApiByronWalletPutPassphraseData + type: object + required: + - new_passphrase + properties: + old_passphrase: + <<: *lenientPassphrase + description: The current passphrase if present. + new_passphrase: + <<: *walletPassphrase + description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds). + + ApiPostTransactionDataByron: &ApiPostTransactionDataByron + type: object + required: + - payments + - passphrase + properties: + payments: *transactionOutputs + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + + ApiPostTransactionData: &ApiPostTransactionData + type: object + required: + - payments + - passphrase + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + payments: *transactionOutputs + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + time_to_live: *transactionTTL + + ApiPostRedemptionData: &ApiPostRedemptionData + type: object + required: + - payments + - passphrase + - withdrawal + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + + ApiPostTransactionFeeDataByron: &ApiPostTransactionFeeDataByron + type: object + required: + - payments + properties: + payments: *transactionOutputs + + ApiPostTransactionFeeData: &ApiPostTransactionFeeData + type: object + required: + - payments + properties: + payments: *transactionOutputs + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + time_to_live: *transactionTTL + + ApiPostRedemptionFeeData: &ApiPostRedemptionFeeData + type: object + required: + - payments + - withdrawal + properties: + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + + ApiPostRandomAddressData: &ApiPostRandomAddressData + type: object + required: + - passphrase + properties: + passphrase: *lenientPassphrase + address_index: *addressIndex + + CredentialValue: *CredentialValue + + ScriptValue: *ScriptValue + + ScriptTemplateValue: *ScriptTemplateValue + + # https://github.com/input-output-hk/cardano-ledger-specs/blob/8d836e61bb88bda4a6a5c00694735928390067a1/shelley/chain-and-ledger/executable-spec/src/Shelley/Spec/Ledger/MetaData.hs#L48-L65 + TransactionMetadataValue: &TransactionMetadataValue + oneOf: + - title: String + type: object + required: + - string + properties: + string: + type: string + maxLength: 64 + + - title: Int + type: object + required: + - int + properties: + int: + type: integer + + - title: ByteString + type: object + required: + - bytes + properties: + bytes: + type: string + pattern: "^[0-9a-fA-F]*$" + maxLength: 128 + + - title: List + type: object + required: + - list + properties: + list: + type: array + items: + $ref: "#/components/schemas/TransactionMetadataValue" + + - title: Map + type: object + required: + - map + properties: + map: + type: array + items: + type: object + properties: + k: + $ref: "#/components/schemas/TransactionMetadataValue" + v: + $ref: "#/components/schemas/TransactionMetadataValue" + + ApiGetSettings: &ApiGetSettings + type: object + required: + - pool_metadata_source + properties: + pool_metadata_source: *poolMetadataSource + + SomeByronWalletPostData: &SomeByronWalletPostData + oneOf: + - <<: *ApiByronWalletRandomPostData + title: random + - <<: *ApiByronWalletIcarusPostData + title: icarus + - <<: *ApiByronWalletTrezorPostData + title: trezor + - <<: *ApiByronWalletLedgerPostData + title: ledger + - <<: *ApiAccountPostData + title: icarus/trezor/ledger (from xpub) + - <<: *ApiByronWalletRandomXPrvPostData + title: random (from xprv) + + +############################################################################# +# # +# PARAMETERS # +# # +############################################################################# + +x-parametersWalletId: ¶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: 45_000_000_000_000_000 # 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-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-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 + +############################################################################# +# # +# RESPONSES # +# # +############################################################################# + +x-responsesErr: &responsesErr + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + description: A specific error code for this error, more precise than HTTP ones. + example: an_error_code + +x-errNotFound: &errNotFound + <<: *responsesErr + title: not_found + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['not_found'] + +x-errSoftDerivationRequired: &errSoftDerivationRequired + <<: *responsesErr + title: not_found + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['soft_derivation_required'] + +x-errHardenedDerivationRequired: &errHardenedDerivationRequired + <<: *responsesErr + title: not_found + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['hardened_derivation_required'] + +x-errNoSuchWallet: &errNoSuchWallet + <<: *responsesErr + title: no_such_wallet + properties: + message: + type: string + description: | + May occur when a given walletId does not match with any known + wallets (because it has been deleted, or has never existed). + code: + type: string + enum: ['no_such_wallet'] + +x-errNoSuchTransaction: &errNoSuchTransaction + <<: *responsesErr + title: no_such_transaction + properties: + message: + type: string + description: May occur when a given transactionId does not match with any known transactions. + code: + type: string + enum: ['no_such_transaction'] + +x-errTransactionAlreadyInLedger: &errTransactionAlreadyInLedger + <<: *responsesErr + title: transaction_already_in_ledger + properties: + message: + type: string + description: Occurs when attempting to delete a transaction which is neither pending nor expired. + code: + type: string + enum: ['transaction_already_in_ledger'] + +x-errWalletAlreadyExists: &errWalletAlreadyExists + <<: *responsesErr + title: wallet_already_exists + properties: + message: + type: string + description: May occur when a otherwise valid request would yield a wallet that already exists. + code: + type: string + enum: ['wallet_already_exists'] + +x-errNoRootKey: &errNoRootKey + <<: *responsesErr + title: no_root_key + properties: + message: + type: string + description: May occur when an action require a signing key but the wallet has only access to verification keys. + code: + type: string + enum: ['no_root_key'] + +x-errWrongEncryptionPassphrase: &errWrongEncryptionPassphrase + <<: *responsesErr + title: wrong_encryption_passphrase + properties: + message: + type: string + description: May occur when the given spending passphrase is wrong. + code: + type: string + enum: ['wrong_encryption_passphrase'] + +x-errMalformedTxPayload: &errMalformedTxPayload + <<: *responsesErr + title: malformed_tx_payload + properties: + message: + type: string + description: May occur when submitting a malformed serialized transaction. + code: + type: string + enum: ['malformed_tx_payload'] + +# TODO: Map this error to the place it belongs. +x-errKeyNotFoundForAddress: &errKeyNotFoundForAddress + <<: *responsesErr + title: key_not_found_for_address + properties: + message: + type: string + description: Should never happen unless the server screwed up and has lost track of previously known addresses. + code: + type: string + enum: ['key_not_found_for_address'] + +x-errNotEnoughMoney: &errNotEnoughMoney + <<: *responsesErr + title: not_enough_money + properties: + message: + type: string + description: May occur when there's not enough money in the wallet to cover a requested payment. + code: + type: string + enum: ['not_enough_money'] + +x-errTransactionIsTooBig: &errTransactionIsTooBig + <<: *responsesErr + title: transaction_is_too_big + properties: + message: + type: string + description: May occur when the wallet can't cover for all requested outputs without making the transaction too large. + code: + type: string + enum: ['transaction_is_too_big'] + +x-errInputsDepleted: &errInputsDepleted + <<: *responsesErr + title: inputs_depleted + properties: + message: + type: string + description: May occur when there's enough money to pay for a payment, but not enough UTxO to allow for paying each output independently. + code: + type: string + enum: ['inputs_depleted'] + +x-errCannotCoverFee: &errCannotCoverFee + <<: *responsesErr + title: cannot_cover_fee + properties: + message: + type: string + description: May occur when a transaction can't be balanced for fees. + code: + type: string + enum: ['cannot_cover_fee'] + +x-errInvalidCoinSelection: &errInvalidCoinSelection + <<: *responsesErr + title: invalid_coin_selection + properties: + message: + type: string + description: Should never happen unless the server screwed up with the creation of a coin selection. + code: + type: string + enum: ['invalid_coin_selection'] + +x-errOutputTokenBundleSizeExceedsLimit: &errOutputTokenBundleSizeExceedsLimit + <<: *responsesErr + title: output_token_bundle_size_exceeds_limit + properties: + message: + type: string + description: | + Returned when a user-specified transaction output contains a token + bundle whose serialized length exceeds the limit supported by the + protocol. + code: + type: string + enum: ['output_token_bundle_size_exceeds_limit'] + +x-errOutputTokenQuantityExceedsLimit: &errOutputTokenQuantityExceedsLimit + <<: *responsesErr + title: output_token_quantity_exceeds_limit + properties: + message: + type: string + description: | + Returned when a user-specified transaction output contains, for some + asset, a token quantity that exceeds the limit supported by the + protocol. + code: + type: string + enum: ['output_token_quantity_exceeds_limit'] + +x-errSharedWalletNotPending: &errSharedWalletNotPending + <<: *responsesErr + title: shared_wallet_not_pending + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + that is active, not pending anymore. + code: + type: string + enum: ['shared_wallet_not_pending'] + +x-errSharedWalletNoDelegationTemplate: &errSharedWalletNoDelegationTemplate + <<: *responsesErr + title: shared_wallet_no_delegation_template + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + for delegation, but the shared wallet misses the delegation template. + code: + type: string + enum: ['shared_wallet_no_delegation_template'] + +x-errSharedWalletKeyAlreadyExists: &errSharedWalletKeyAlreadyExists + <<: *responsesErr + title: shared_wallet_key_already_exists + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + but the same key is already present in a given template. + code: + type: string + enum: ['shared_wallet_key_already_exists'] + +x-errSharedWalletNoSuchCosigner: &errSharedWalletNoSuchCosigner + <<: *responsesErr + title: shared_wallet_no_such_cosigner + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + in script template that misses the cosigner. + code: + type: string + enum: ['shared_wallet_no_such_cosigner'] + +x-errSharedWalletCannotUpdateKey: &errSharedWalletCannotUpdateKey + <<: *responsesErr + title: shared_wallet_cannot_update_key + properties: + message: + type: string + description: | + Returned when a user tries to update cosigner key that contains a key of a shared wallet. + Only other cosigner keys can be updated. + code: + type: string + enum: ['shared_wallet_cannot_update_key'] + +x-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-errRejectedByCoreNode: &errRejectedByCoreNode + <<: *responsesErr + title: rejected_by_core_node + properties: + message: + type: string + description: Should never happen unless the server screwed up with the creation of transaction. + code: + type: string + enum: ['rejected_by_core_node'] + +x-errBadRequest: &errBadRequest + <<: *responsesErr + title: bad_request + properties: + message: + type: string + description: | + May occur when a request is not well-formed; that is, it fails to parse + successfully. This could be the case when some required parameters + are missing or, when malformed values are provided. + code: + type: string + enum: ['bad_request'] + +x-errMethodNotAllowed: &errMethodNotAllowed + <<: *responsesErr + title: method_not_allowed + properties: + message: + type: string + description: May occur when sending a request on a wrong endpoint. + code: + type: string + enum: ['method_not_allowed'] + +x-errNotAcceptable: &errNotAcceptable + <<: *responsesErr + title: not_acceptable + properties: + message: + type: string + description: May occur when providing an invalid 'Accept' header. + code: + type: string + enum: ['not_acceptable'] + +x-errUnsupportedMediaType: &errUnsupportedMediaType + <<: *responsesErr + title: unsupported_media_type + properties: + message: + type: string + description: May occur when providing an invalid 'Content-Type' header. + code: + type: string + enum: ['unsupported_media_type'] + +# TODO: Map this error to the place it belongs. +x-errUnexpectedError: &errUnexpectedError + <<: *responsesErr + title: unexpected_error + properties: + message: + type: string + description: Should never occur, unless the server screwed up badly. + code: + type: string + enum: ['unexpected_error'] + +x-errStartTimeLaterThanEndTime: &errStartTimeLaterThanEndTime + <<: *responsesErr + title: start_time_later_than_end_time + properties: + message: + type: string + description: May occur when a provided time-range is unsound. + code: + type: string + enum: ['start_time_later_than_end_time'] + +# TODO: Map this error to the place it belongs. +x-errUnableToDetermineCurrentEpoch: &errUnableToDetermineCurrentEpoch + <<: *responsesErr + title: unable_to_determine_current_epoch + properties: + message: + type: string + description: May occur under rare circumstances if the underlying node isn't enough synced with the network. + code: + type: string + enum: ['unable_to_determine_current_epoch'] + +# TODO: Map this error to the place it belongs. +x-errNotSynced: &errNotSynced + <<: *responsesErr + title: not_synced + properties: + message: + type: string + description: May occur under rare circumstances if the underlying node isn't enough synced with the network. + code: + type: string + enum: ['not_synced'] + +# TODO: Map this error to the place it belongs. +x-errNothingToMigrate: &errNothingToMigrate + <<: *responsesErr + title: nothing_to_migrate + properties: + message: + type: string + description: May occur when trying to migrate a wallet that is empty or full of dust. + code: + type: string + enum: ['nothing_to_migrate'] + +x-errNoSuchPool: &errNoSuchPool + <<: *responsesErr + title: no_such_pool + properties: + message: + type: string + description: May occur when a given poolId does not match any known pool. + code: + type: string + enum: ['no_such_pool'] + +x-errPoolAlreadyJoined: &errPoolAlreadyJoined + <<: *responsesErr + title: pool_already_joined + properties: + message: + type: string + description: May occur when a given poolId matches the current delegation preferences of the wallet's account. + code: + type: string + enum: ['pool_already_joined'] + +x-errNotDelegatingTo: &errNotDelegatingTo + <<: *responsesErr + title: not_delegating_to + properties: + message: + type: string + description: May occur when trying to quit a pool on an account that isn't delegating. + code: + type: string + enum: ['not_delegating_to'] + +# TODO: Map this error to the place it belongs. +x-errNotImplemented: &errNotImplemented + <<: *responsesErr + title: not_implemented + properties: + message: + type: string + description: May occur when reaching an endpoint under construction. + code: + type: string + enum: ['not_implemented'] + +# TODO: Map this error to the place it belongs. +x-errWalletNotResponding: &errWalletNotResponding + <<: *responsesErr + title: wallet_not_responding + properties: + message: + type: string + description: Should never occur unless something really wrong happened causing a background worker to die. + code: + type: string + enum: ['wallet_not_responding'] + +# TODO: Map this error to the place it belongs. +x-errAddressAlreadyExists: &errAddressAlreadyExists + <<: *responsesErr + title: address_already_exists + properties: + message: + type: string + description: May occur when trying to import an address that is already known of the wallet's account. + code: + type: string + enum: ['address_already_exists'] + +x-errInvalidWalletType: &errInvalidWalletType + <<: *responsesErr + title: invalid_wallet_type + properties: + message: + type: string + description: May occur when trying to perform an operation not supported by this type of wallet. + code: + type: string + enum: ['invalid_wallet_type'] + +x-errQueryParamMissing: &errQueryParamMissing + <<: *responsesErr + title: query_param_missing + properties: + message: + type: string + description: May occur when an endpoint requires the presence of a query parameter that is missing. + code: + type: string + enum: ['query_param_missing'] + +x-errNonNullRewards: &errNonNullRewards + <<: *responsesErr + title: non_null_rewards + properties: + message: + type: string + description: May occur when trying to unregister a stake key that still has rewards attached to it. + code: + type: string + enum: ['non_null_rewards'] + +x-errUtxoTooSmall: &errUtxoTooSmall + <<: *responsesErr + title: utxo_too_small + properties: + message: + type: string + description: May occur when a requested output is below the minimum utxo value. + code: + type: string + enum: ['utxo_too_small'] + +x-errMinWithdrawalWrong: &errMinWithdrawalWrong + <<: *responsesErr + title: min_withdrawal_wrong + properties: + message: + type: string + description: May occur when trying to withdraw less than the minimal UTxO value. + code: + type: string + enum: ['min_withdrawal_wrong'] + +x-errAlreadyWithdrawing: &errAlreadyWithdrawing + <<: *responsesErr + title: already_withdrawing + properties: + message: + type: string + description: May occur when submitting a withdrawal while another withdrawal is pending. + code: + type: string + enum: ['already_withdrawing'] + +# TODO: Map this error to the place it belongs. +x-errWithdrawalNotWorth: &errWithdrawalNotWorth + <<: *responsesErr + title: withdrawal_not_worth + properties: + message: + type: string + description: May occur when withdrawing an amount would cost more than the withdrawn value. + code: + type: string + enum: ['withdrawal_not_worth'] + +# TODO: Map this error to the place it belongs. +x-errPastHorizon: &errPastHorizon + <<: *responsesErr + title: past_horizon + properties: + message: + type: string + description: May occur in rare cases when converting slot to time can't be done, typically near hard-forks. + code: + type: string + enum: ['past_horizon'] + +# TODO: Map this error to the place it belongs. +x-errUnableToAssignInputOutput: &errUnableToAssignInputOutput + <<: *responsesErr + title: unable_to_assign_input_output + properties: + message: + type: string + description: Should never occur unless the server screwed up with a coin selection. + code: + type: string + enum: ['unable_to_assign_input_output'] + +x-errAssetNotPresent: &errAssetNotPresent + <<: *responsesErr + title: asset_not_present + properties: + message: + type: string + description: | + Occurs when requesting information about an asset which is not + involved in any transaction related to the wallet. + code: + type: string + enum: ['asset_not_present'] + +x-responsesErr400: &responsesErr400 + 400: + description: Bad Request + content: + application/json: + schema: *errBadRequest + +x-responsesErr403: &responsesErr403 + 403: + description: Forbidden + content: + application/json: + schema: *responsesErr + +x-responsesErr404: &responsesErr404 + 404: + description: Not Found + content: + application/json: + schema: *responsesErr + +x-responsesErr406: &responsesErr406 + 406: + description: Not Acceptable + content: + application/json: + schema: *errNotAcceptable + +x-responsesErr409: &responsesErr409 + 409: + description: Conflict + content: + application/json: + schema: *responsesErr + +x-responsesErr410: &responsesErr410 + 410: + description: Gone + content: + application/json: + schema: *responsesErr + +x-responsesErr415: &responsesErr415 + 415: + description: Unsupported Media Type + content: + application/json: + schema: *responsesErr + +x-responsesErr423: &responsesErr423 + 423: + description: Locked + content: + application/json: + schema: *responsesErr + +x-responsesErr404WalletNotFound: &responsesErr404WalletNotFound + 404: + description: Not Found + content: + application/json: + schema: *errNoSuchWallet + +x-responsesErr409WalletAlreadyExists: &responsesErr409WalletAlreadyExists + 409: + description: Conflict + content: + application/json: + schema: *errWalletAlreadyExists + +x-responsesErr415UnsupportedMediaType: &responsesErr415UnsupportedMediaType + 415: + description: Unsupported Media Type + content: + application/json: + schema: *errUnsupportedMediaType + +x-responsesListWallets: &responsesListWallets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiWallet + +x-responsesListSharedWallets: &responsesListSharedWallets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiSharedWallet + +x-responsesErr404AssetNotPresent: &responsesErr404AssetNotPresent + 404: + description: Not Found + content: + application/json: + schema: *errAssetNotPresent + +x-responsesListAssets: &responsesListAssets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiAsset + +x-responsesGetAsset: &responsesGetAsset + <<: *responsesErr404AssetNotPresent + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiAsset + +x-responsesListByronWallets: &responsesListByronWallets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiByronWallet + +x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWalletUTxOsStatistics + +x-responsesPostWallet: &responsesPostWallet + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr409WalletAlreadyExists + <<: *responsesErr415UnsupportedMediaType + 201: + description: Created + content: + application/json: + schema: *ApiWallet + +x-responsesPostSharedWallet: &responsesPostSharedWallet + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr409WalletAlreadyExists + <<: *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errSharedWalletScriptTemplateInvalid + 201: + description: Created + content: + application/json: + schema: *ApiSharedWallet + +x-responsesPostByronWallet: &responsesPostByronWallet + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr409 + <<: *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiByronWallet + +x-responsesGetWallet: &responsesGetWallet + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWallet + +x-responsesGetByronWallet: &responsesGetByronWallet + <<: *responsesErr404 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiByronWallet + +x-responsesGetSharedWallet: &responsesGetSharedWallet + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiSharedWallet + +x-responsesPatchSharedWallet: &responsesPatchSharedWallet + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errSharedWalletKeyAlreadyExists + - <<: *errSharedWalletNoDelegationTemplate + - <<: *errSharedWalletNotPending + - <<: *errSharedWalletNoSuchCosigner + - <<: *errSharedWalletCannotUpdateKey + 200: + description: Ok + content: + application/json: + schema: *ApiSharedWallet + +x-responsesCreateWalletMigrationPlan: &responsesCreateWalletMigrationPlan + 403: + description: Forbidden + content: + application/json: + schema: *errNothingToMigrate + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 202: + description: Accepted + content: + application/json: + schema: *ApiWalletMigrationPlan + +x-responsesMigrateWallet: &responsesMigrateWallet + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errNothingToMigrate + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: + type: array + items: *ApiTransaction + minItems: 1 + +x-responsesDeleteWallet: &responsesDeleteWallet + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 204: + description: No Content + +x-responsesForceResyncWallet: &responsesForceResyncWallet + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr406 + <<: *responsesErr415 + 204: + description: No Content + +x-responsesPutWallet: &responsesPutWallet + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 200: + description: Ok + content: + application/json: + schema: *ApiWallet + +x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase + <<: *responsesErr400 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 204: + description: No Content + +x-responsesSelectCoins: &responsesSelectCoins + <<: *responsesErr400 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errNotEnoughMoney + - <<: *errCannotCoverFee + - <<: *errInputsDepleted + - <<: *errInvalidCoinSelection + - <<: *errOutputTokenQuantityExceedsLimit + - <<: *errOutputTokenBundleSizeExceedsLimit + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 200: + description: OK + content: + application/json: + schema: *ApiCoinSelection + +x-responsesDeleteTransaction: &responsesDeleteTransaction + 403: + description: Forbidden + content: + application/json: + schema: *errTransactionAlreadyInLedger + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errNoSuchTransaction + <<: *responsesErr406 + 204: + description: No Content + +x-responsesListTransactions: &responsesListTransactions + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errMinWithdrawalWrong + - <<: *errStartTimeLaterThanEndTime + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 200: + description: Ok + headers: + Content-Range: + schema: + type: string + format: inserted-at {range-start}-{range-end}/{total} + content: + application/json: + schema: + type: array + items: *ApiTransaction + +x-responsesGetTransaction: &responsesGetTransaction + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errNoSuchTransaction + <<: *responsesErr406 + 200: + description: OK + content: + application/json: + schema: *ApiTransaction + +x-responsesPostTransaction: &responsesPostTransaction + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errBadRequest + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errCannotCoverFee + - <<: *errNotEnoughMoney + - <<: *errTransactionIsTooBig + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesPostExternalTransaction: &responsesPostExternalTransaction + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiTxId + +x-responsesPostAnyAddress: &responsesPostAnyAddress + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *AnyAddress + +x-responsesPostTransactionFee: &responsesPostTransactionFee + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errBadRequest + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errCannotCoverFee + - <<: *errNotEnoughMoney + - <<: *errInputsDepleted + - <<: *errInvalidCoinSelection + - <<: *errOutputTokenQuantityExceedsLimit + - <<: *errOutputTokenBundleSizeExceedsLimit + - <<: *errTransactionIsTooBig + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiFee + +x-responsesGetDelegationFee: &responsesGetDelegationFee + 403: + description: Forbidden + content: + application/json: + schema: *errCannotCoverFee + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiFee + +x-responsesListAddresses: &responsesListAddresses + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiAddress + +x-responsesGetShelleyKey: &responsesGetShelleyKey + <<: *responsesErr400 + <<: *responsesErr404 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiVerificationKeyShelley + +x-responsesGetSharedKey: &responsesGetSharedKey + <<: *responsesErr400 + <<: *responsesErr404 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiVerificationKeyShared + +x-responsesGetAccountSharedKey: &responsesGetAccountSharedKey + <<: *responsesErr400 + <<: *responsesErr404 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiAccountKeyShared + +x-responsesPostAccountKey: &responsesPostAccountKey + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiAccountKey + +x-responsesGetAccountKey: &responsesGetAccountKey + <<: *responsesErr400 + <<: *responsesErr404 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiAccountKey + +x-responsesPostAccountKeyShared: &responsesPostAccountKeyShared + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiAccountKeyShared + +x-responsesListStakePools: &responsesListStakePools + 400: + description: Bad Request + content: + application/json: + schema: *errQueryParamMissing + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiStakePool + +x-responsesPostMaintenanceAction: &responsesPostMaintenanceAction + <<: *responsesErr404 + 204: + description: No Content + +x-responsesGetMaintenanceAction: &responsesGetMaintenanceAction + 200: + description: Ok + content: + application/json: + schema: + <<: *ApiMaintenanceAction + +x-responsesJoinStakePool: &responsesJoinStakePool + <<: *responsesErr400 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + - <<: *errPoolAlreadyJoined + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errNoSuchPool + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesQuitStakePool: &responsesQuitStakePool + <<: *responsesErr400 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + - <<: *errNotDelegatingTo + - <<: *errNonNullRewards + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + <<: *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesGetNetworkInformation: &responsesGetNetworkInformation + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkInformation + +x-responsesGetNetworkClock: &responsesGetNetworkClock + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkClock + +x-responsesGetNetworkParameters: &responsesGetNetworkParameters + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkParameters + +x-responsesPostRandomAddress: &responsesPostRandomAddress + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr406 + <<: *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiAddress + +x-responsesPutRandomAddress: &responsesPutRandomAddress + <<: *responsesErr400 + <<: *responsesErr403 + 204: + description: No Content + +x-responsesPutRandomAddresses: &responsesPutRandomAddresses + <<: *responsesErr400 + <<: *responsesErr403 + 204: + description: No Content + +x-responsesInspectAddress: &responsesInspectAddress + <<: *responsesErr400 + 200: + description: Ok + content: + application/json: + schema: *ApiAddressInspect + +x-responsesPutSettings: &responsesPutSettings + <<: *responsesErr400 + <<: *responsesErr415UnsupportedMediaType + 204: + description: No Content + +x-responsesGetSettings: &responsesGetSettings + 200: + description: Ok + content: + application/json: + schema: *ApiGetSettings + +x-responsesPostSignatures: &responsesPostSignatures + <<: *responsesErr400 + <<: *responsesErr406 + <<: *responsesErr415 + 200: + description: OK + content: + application/octet-stream: + schema: + type: string + format: binary + +x-responsesGetSmashHealth: &responsesGetSmashHealth + <<: *responsesErr400 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiHealthCheck + + +############################################################################# +# # +# PATHS # +# # +############################################################################# + +x-tagGroups: + - name: Shelley (Sequential) + tags: + - Wallets + - Assets + - Addresses + - Coin Selections + - Transactions + - Migrations + - Stake Pools + - Keys + + - name: Shelley (Shared Wallets) + tags: + - Shared Wallets + - Shared Keys + - Shared Addresses + + - name: Byron (Random) + tags: + - Byron Wallets + - Byron Assets + - Byron Addresses + - Byron Coin Selections + - Byron Transactions + - Byron Migrations + + - name: Miscellaneous + tags: + - Utils + - Network + - Proxy + - Settings + - Experimental + +paths: + /wallets/{walletId}/signatures/{role}/{index}: + post: + operationId: signMetadata + tags: ["Experimental"] + summary: Sign Metadata + description: | +

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 it is involved in a + transaction of the wallet. + parameters: + - *parametersWalletId + responses: *responsesListAssets + + /wallets/{walletId}/assets/{policyId}/{assetName}: + get: + operationId: getAsset + tags: ["Assets"] + summary: Get Asset + description: | + Fetch a single asset from its `policy_id` and `asset_name`, + with its metadata if any. + + The asset must be associated with the wallet. + parameters: + - *parametersWalletId + - *parametersPolicyId + - *parametersAssetName + responses: *responsesGetAsset + + /wallets/{walletId}/assets/{policyId}: + get: + operationId: getAssetDefault + tags: ["Assets"] + summary: Get Asset (empty name) + description: | + Fetch the the asset from `policy_id` with an empty name. + + The asset must be associated with the wallet. + parameters: + - *parametersWalletId + - *parametersPolicyId + responses: *responsesGetAsset + + /wallets/{walletId}/statistics/utxos: + get: + operationId: getUTxOsStatistics + tags: ["Wallets"] + summary: UTxO Statistics + description: | +

status: stable

+ + Return the UTxOs distribution across the whole wallet, in the form of a histogram. + + ``` + │ + 100 ─ + │ + │ ┌───┐ + 10 ─ ┌───┐ │ │ ┌───┐ + │ ┌───┐ │ │ │ │ │ │ + │ │ │ │ │ │ │ ┌───┐ │ │ + 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ + └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── + 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ + ``` + parameters: + - *parametersWalletId + responses: *responsesGetUTxOsStatistics + + /wallets/{walletId}: + get: + operationId: getWallet + tags: ["Wallets"] + summary: Get + description: | +

status: stable

+ parameters: + - *parametersWalletId + responses: *responsesGetWallet + + delete: + operationId: deleteWallet + tags: ["Wallets"] + summary: Delete + description: | +

status: stable

+ parameters: + - *parametersWalletId + responses: *responsesDeleteWallet + + put: + operationId: putWallet + tags: ["Wallets"] + summary: Update Metadata + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutData + responses: *responsesPutWallet + + /wallets/{walletId}/passphrase: + put: + operationId: putWalletPassphrase + tags: ["Wallets"] + summary: Update Passphrase + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutPassphraseData + responses: *responsesPutWalletPassphrase + + /wallets/{walletId}/payment-fees: + post: + operationId: postTransactionFee + tags: ["Transactions"] + summary: Estimate Fee + description: | +

status: stable

+ + Estimate fee for the transaction. The estimate is made by + assembling multiple transactions and analyzing the + distribution of their fees. The estimated_max is the highest + fee observed, and the estimated_min is the fee which is lower + than at least 90% of the fees observed. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - <<: *ApiPostTransactionFeeData + title: "payment" + - <<: *ApiPostRedemptionFeeData + title: "redemption" + responses: *responsesPostTransactionFee + + /wallets/{walletId}/transactions: + post: + operationId: postTransaction + tags: ["Transactions"] + summary: Create + description: | +

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

status: stable

+ + Lists all incoming and outgoing wallet's transactions. + parameters: + - *parametersWalletId + - *parametersStartDate + - *parametersEndDate + - *parametersSortOrder + - *parametersMinWithdrawal + responses: *responsesListTransactions + + /wallets/{walletId}/transactions/{transactionId}: + get: + operationId: getTransaction + tags: ["Transactions"] + summary: Get + description: | +

status: stable

+ + Get transaction by id. + parameters: + - *parametersWalletId + - *parametersTransactionId + responses: *responsesGetTransaction + + delete: + operationId: deleteTransaction + tags: ["Transactions"] + summary: Forget + description: | +

status: stable

+ + Forget pending transaction. Importantly, a transaction, when sent, + cannot be cancelled. One can only request forgetting about it + in order to try spending (concurrently) the same UTxO in another + transaction. But, the transaction may still show up later in a block + and therefore, appear in the wallet. + parameters: + - *parametersWalletId + - *parametersTransactionId + responses: *responsesDeleteTransaction + + /wallets/{walletId}/addresses: + get: + operationId: listAddresses + tags: ["Addresses"] + summary: List + description: | +

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. + + Note: Only _Hardened_ indexes are supported by this endpoint. + parameters: + - *parametersWalletId + - *parametersDerivationSegment + requestBody: + required: true + content: + application/json: + schema: *ApiPostAccountKeyData + 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. + + 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 + + /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 + 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. + + > ⚠️ Disclaimer ⚠️ + > + > This endpoint historically use to take a stake pool id as a path parameter. + > However, retiring from delegation is ubiquitous and not tight to a particular + > stake pool. For backward-compatibility reasons, sending stake pool ids as path + > parameter will still be accepted by the server but new integrations are + > encouraged to provide a placeholder asterisk `*` instead. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPassphrase + responses: *responsesQuitStakePool + + /stake-pools/{stakePoolId}/wallets/{walletId}: + put: + operationId: joinStakePool + tags: ["Stake Pools"] + summary: Join + description: | +

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 + + /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 + + /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 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 UTxOs distribution across the whole wallet, in the form of a histogram. + + ``` + │ + 100 ─ + │ + │ ┌───┐ + 10 ─ ┌───┐ │ │ ┌───┐ + │ ┌───┐ │ │ │ │ │ │ + │ │ │ │ │ │ │ ┌───┐ │ │ + 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ + └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── + 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ + ``` + parameters: + - *parametersWalletId + responses: *responsesGetUTxOsStatistics + + /byron-wallets/{walletId}: + get: + operationId: getByronWallet + tags: ["Byron Wallets"] + summary: Get + description: | +

status: stable

+ + Return information about a Byron wallet. + parameters: + - *parametersWalletId + responses: *responsesGetByronWallet + + delete: + operationId: deleteByronWallet + tags: ["Byron Wallets"] + summary: Delete + description: | +

status: stable

+ + Delete a Byron wallet. + parameters: + - *parametersWalletId + responses: *responsesDeleteWallet + + put: + operationId: putByronWallet + tags: ["Byron Wallets"] + summary: Update Metadata + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutData + responses: *responsesPutWallet + + /byron-wallets/{walletId}/passphrase: + put: + operationId: putByronWalletPassphrase + tags: ["Byron Wallets"] + summary: Update Passphrase + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiByronWalletPutPassphraseData + responses: *responsesPutWalletPassphrase + + /byron-wallets/{walletId}/addresses: + post: + operationId: createAddress + tags: ["Byron Addresses"] + summary: Create Address + description: | +

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: *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 + description: | +

status: stable

+ + Estimate fee for the transaction. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostTransactionFeeDataByron + responses: *responsesPostTransactionFee + + /byron-wallets/{walletId}/transactions: + post: + operationId: postByronTransaction + tags: ["Byron Transactions"] + summary: Create + description: | +

status: stable

+ + Create and send transaction from the wallet. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostTransactionDataByron + responses: *responsesPostTransaction + + get: + operationId: listByronTransactions + tags: ["Byron Transactions"] + summary: List + description: | +

status: stable

+ + List all incoming and outgoing transactions for the given wallet. + parameters: + - *parametersWalletId + - *parametersStartDate + - *parametersEndDate + - *parametersSortOrder + responses: *responsesListTransactions + + /byron-wallets/{walletId}/transactions/{transactionId}: + get: + operationId: getByronTransaction + tags: ["Byron Transactions"] + summary: Get + description: | +

status: stable

+ + Get transaction by id. + parameters: + - *parametersWalletId + - *parametersTransactionId + responses: *responsesGetTransaction + + delete: + operationId: deleteByronTransaction + tags: ["Byron Transactions"] + summary: Forget + description: | +

status: stable

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

status: disabled

+ ⚠️IMPORTANT⚠️ This endpoint has been temporarily disabled with the introduction of multi-assets UTxO. It will be enabled again soon. + +
+ 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: | +

status: disabled

+ ⚠️IMPORTANT⚠️ This endpoint has been temporarily disabled with the introduction of multi-assets UTxO. It will be enabled again soon. + +
+ 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: | +

status: stable

+ responses: *responsesGetNetworkInformation + + /network/clock: + get: + operationId: getNetworkClock + tags: ["Network"] + summary: Clock + description: | +

status: stable

+ parameters: + - <<: *parametersForceNtpCheck + name: forceNtpCheck + responses: *responsesGetNetworkClock + + /network/parameters: + get: + operationId: getNetworkParameters + tags: ["Network"] + summary: Parameters + description: | +

status: stable

+ + Returns the set of network parameters for the current epoch. + responses: *responsesGetNetworkParameters + + /proxy/transactions: + post: + operationId: postExternalTransaction + tags: ["Proxy"] + summary: Submit External Transaction + description: | +

status: stable

+ + Submits a transaction that was created and signed outside of cardano-wallet. + + NOTE: Unlike the postTransaction endpoint, there are no + guarantees that a transaction accepted by this endpoint will + actually be included in the chain. It's up to the caller to + retry submission until the transaction is confirmed. + requestBody: + content: + application/octet-stream: + schema: *signedTransactionBlob + responses: *responsesPostExternalTransaction + + /addresses/{addressId}: + get: + operationId: inspectAddress + tags: ["Addresses"] + summary: Inspect Address + description: | +

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

status: stable

+ + Overwrite current settings. + requestBody: + required: true + content: + application/json: + schema: *ApiSettingsPutData + responses: *responsesPutSettings + + get: + operationId: getSettings + tags: ["Settings"] + summary: Get settings + description: | +

status: stable

+ + 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: ⚠ under development

+ Create a shared wallet from either an account public key and script + templates or mnemonic and script templates. + ADP-686 will enable restoration. + + requestBody: + required: true + content: + application/json: + schema: *ApiSharedWalletPostData + responses: *responsesPostSharedWallet + + get: + operationId: listSharedWallets + tags: ["Shared Wallets"] + summary: List + description: | +

status: ⚠ under development

+ + 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: ⚠ under development

+ Get a shared wallet for a given wallet id. + + parameters: + - *parametersWalletId + responses: *responsesGetSharedWallet + + delete: + operationId: deleteSharedWallet + tags: ["Shared Wallets"] + summary: Delete + description: | +

status: stable

+ parameters: + - *parametersWalletId + responses: *responsesDeleteWallet + + /shared-wallets/{walletId}/payment-script-template: + patch: + operationId: patchSharedWalletInPayment + tags: ["Shared Wallets"] + summary: Update Payment + description: | +

status: ⚠ under development

+ Update payment script template for a given shared wallet by + updating/adding account public key for cosigner. Updating the + shared wallet account key results in an error. Also updating is + enabled only for pending shared wallet, ie., the wallet that has + a missing account public key for any cosigner. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSharedWalletPatchData + responses: *responsesPatchSharedWallet + + /shared-wallets/{walletId}/delegation-script-template: + patch: + operationId: patchSharedWalletInDelegation + tags: ["Shared Wallets"] + summary: Update Delegation + description: | +

status: ⚠ under development

+ Update delegation script template for a given shared wallet by + updating/adding account public key for cosigner. Updating the + shared wallet account key results in an error. Also updating is + enabled only for pending shared wallet, ie., the wallet that has + a missing account public key for any cosigner. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSharedWalletPatchData + responses: *responsesPatchSharedWallet + + /shared-wallets/{walletId}/keys/{index}: + post: + operationId: postAccountKeyShared + tags: ["Shared Keys"] + summary: Create Account Public Key + description: | +

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