diff --git a/api/v2020-09-22/README.md b/api/v2020-09-22/README.md new file mode 100644 index 00000000000..53da2462ac3 --- /dev/null +++ b/api/v2020-09-22/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/v2020-09-22/index.html b/api/v2020-09-22/index.html new file mode 100644 index 00000000000..363d7f5244f --- /dev/null +++ b/api/v2020-09-22/index.html @@ -0,0 +1,19 @@ + + + + Cardano Wallet Backend API Documentation + + + + + + + + + + + + + + + diff --git a/api/v2020-09-22/swagger.yaml b/api/v2020-09-22/swagger.yaml new file mode 100644 index 00000000000..f4329651b7b --- /dev/null +++ b/api/v2020-09-22/swagger.yaml @@ -0,0 +1,2822 @@ +openapi: 3.0.0 +info: + title: Cardano Wallet Backend API + version: 2.0.0 + 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 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 block. + type: object + required: + - slot_number + - epoch_number + - height + - absolute_slot_number + properties: + slot_number: *slotNumber + epoch_number: *epochNumber + height: *numberOfBlocks + absolute_slot_number: *absoluteSlot + +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 + 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-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-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-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 balance(s) + type: object + required: + - available + - reward + - total + properties: + available: + <<: *amount + description: Available UTxO balance (funds that can be spent without condition). + reward: + <<: *amount + description: The balance of the reward account for this wallet. + total: + <<: *amount + description: Total balance (available balance plus pending change and reward balance). + +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-transactionAmount: &transactionAmount + <<: *amount + +x-transactionInsertedAt: &transactionInsertedAt + description: | + + if: status == in_ledger +
+ Absolute time at which the transaction was inserted in a block. + type: object + required: + - block + - time + properties: + time: *date + block: *blockReference + +x-transactionPendingSince: &transactionPendingSince + description: | + + if: status == pending +
+ The point in time at which a transaction became pending. + type: object + required: + - block + - time + properties: + time: *date + block: *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 + type: array + minItems: 0 + items: + type: object + required: + - id + - index + properties: + address: *addressId + amount: *transactionAmount + id: *transactionId + index: + type: integer + minimum: 0 + +x-transactionOutputs: &transactionOutputs + description: A list of target outputs + type: array + minItems: 1 + items: + type: object + required: + - address + - amount + properties: + address: *addressId + amount: *transactionAmount + +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-transactionResolvedInputs: &transactionResolvedInputs + description: A list of transaction inputs + type: array + minItems: 0 + items: + type: object + required: + - id + - index + - address + - amount + properties: + address: *addressId + amount: *transactionAmount + id: *transactionId + index: + type: integer + minimum: 0 + +x-signedTransactionBlob: &signedTransactionBlob + description: Signed transaction message binary blob. + type: string + format: binary + +x-transactionStatus: &transactionStatus + description: | + Current transaction status. + + ``` + *---------* + | | + -------> PENDING <----------------* + | | | + *---------* (rollback) + | | + (in ledger) *-----------* + | | | + *---------------> IN_LEDGER | + | | + *-----------* + ``` + type: string + enum: + - pending + - in_ledger + +x-transactionMetadata: &transactionMetadata + description: | + 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-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-jormungandrStakePoolMetadata: &jormungandrStakePoolMetadata + description: | + Information about the stake pool. + type: object + required: + - owner + - ticker + - name + - homepage + - pledge_address + additionalProperties: false + properties: + owner: + type: string + format: bech32 + example: ed25519_pk1lrspg0h4afh3l2kaneqlktdv9kaq4zskcvehqwhc4lmx36f5dweqjtaga8 + 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 + pledge_address: + type: string + format: bech32 + example: addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g + +x-jormungandrStakePoolCost: &jormungandrStakePoolCost + <<: *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. + +x-jormungandrStakePoolMargin: &jormungandrStakePoolMargin + <<: *percentage + description: | + Variable margin on the total reward given to an operator before splitting rewards between stakeholders. + +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 + <<: *jormungandrStakePoolCost + 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 + <<: *jormungandrStakePoolMargin + 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-jormungandrStakePoolSaturation: &jormungandrStakePoolSaturation + 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. + example: 0.74 + +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-stakePoolDesirability: &stakePoolDesirability + type: number + minimum: 0 + description: | + How desirable / attractive a pool is. To determine a pool's _rank_, we order pools by decreasing desirability. + The most desirable pool gets rank 1, the second most desirable pool gets rank 2 and so on. + example: 42 + +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-jormungandrStakePoolMetrics: &jormungandrStakePoolMetrics + type: object + required: + - controlled_stake + - produced_blocks + properties: + controlled_stake: *transactionAmount + produced_blocks: + <<: *numberOfBlocks + description: Number of blocks produced by a given stake pool + + +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 + maximum: 4294967296 # 2 ^ 32, whole range (soft and hard) for random addresses. + description: | + An optional address derivation index. Leave out to get an address + with a randomly generated index. + +############################################################################# +# # +# DEFINITIONS # +# # +############################################################################# + +components: + schemas: + ApiAddress: &ApiAddress + type: object + required: + - id + - state + properties: + id: *addressId + state: *addressState + + ApiNetworkTip: &ApiNetworkTip + description: A network tip + type: object + required: + - slot_number + - epoch_number + - absolute_slot_number + properties: + slot_number: *slotNumber + epoch_number: *epochNumber + absolute_slot_number: *absoluteSlot + + ApiNetworkInformation: &ApiNetworkInformation + type: object + required: + - sync_progress + - node_tip + properties: + sync_progress: *networkInformationSyncProgress + node_tip: *networkInformationNodeTip + network_tip: *ApiNetworkTip + next_epoch: *epochInfo + + ApiNetworkClock: &ApiNetworkClock + <<: *networkInformationNtpStatus + + ApiNetworkParameters: &ApiNetworkParameters + type: object + required: + - genesis_block_hash + - blockchain_start_time + - slot_length + - epoch_length + - epoch_stability + - active_slot_coefficient + - decentralization_level + - desired_pool_number + - minimum_utxo_value + properties: + genesis_block_hash: *blockId + blockchain_start_time: *date + slot_length: *numberOfSeconds + epoch_length: *numberOfSlots + epoch_stability: *numberOfBlocks + active_slot_coefficient: *percentage + decentralization_level: *percentage + desired_pool_number: *stakePoolsNumber + minimum_utxo_value: *amount + hardfork_at: *epochInfo + + ApiSelectCoinsData: &ApiSelectCoinsData + type: object + required: + - payments + properties: + payments: *transactionOutputs + + ApiCoinSelection: &ApiCoinSelection + type: object + required: + - inputs + - outputs + properties: + inputs: *transactionResolvedInputs + outputs: *transactionOutputs + + ApiStakePool: &ApiStakePool + type: object + required: + - id + - metrics + - cost + - margin + - pledge + properties: + id: *stakePoolId + metrics: *stakePoolMetrics + cost: *stakePoolCost + margin: *stakePoolMargin + pledge: *stakePoolPledge + metadata: *stakePoolMetadata + retirement: *stakePoolRetirement + + ApiJormungandrStakePool: &ApiJormungandrStakePool + type: object + required: + - id + - metrics + - apparent_performance + - cost + - margin + - saturation + - desirability + properties: + id: *stakePoolId + metrics: *jormungandrStakePoolMetrics + apparent_performance: *stakePoolApparentPerformance + cost: *jormungandrStakePoolCost + margin: *jormungandrStakePoolMargin + metadata: *jormungandrStakePoolMetadata + saturation: *jormungandrStakePoolSaturation + desirability: *stakePoolDesirability + + ApiFee: &ApiFee + type: object + required: + - estimated_min + - estimated_max + properties: + estimated_min: *transactionAmount + estimated_max: *transactionAmount + + ApiPutAddressesData: &ApiPutAddressesData + type: object + required: + - addresses + properties: + addresses: + <<: *addresses + description: The imported addresses. + + ApiTxId: &ApiTxId + type: object + required: + - id + properties: + id: *transactionId + + ApiTransaction: &ApiTransaction + type: object + required: + - id + - amount + - direction + - inputs + - outputs + - withdrawals + - status + properties: + id: *transactionId + amount: *transactionAmount + inserted_at: *transactionInsertedAt + pending_since: *transactionPendingSince + depth: *transactionDepth + direction: *transactionDirection + inputs: *transactionInputs + outputs: *transactionOutputs + withdrawals: *transactionWithdrawals + 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 + - delegation + - name + - state + - tip + properties: + id: *walletId + address_pool_gap: *walletAddressPoolGap + balance: *walletBalance + delegation: *ApiWalletDelegation + name: *walletName + passphrase: *walletPassphraseInfo + state: *walletState + tip: *blockReference + + ApiByronWallet: &ApiByronWallet + type: object + required: + - id + - balance + - discovery + - name + - state + - tip + properties: + id: *walletId + balance: *byronWalletBalance + discovery: *walletDiscovery + name: *walletName + passphrase: *walletPassphraseInfo + state: *walletState + tip: *blockReference + + ApiWalletMigrationInfo: &ApiWalletMigrationInfo + type: object + required: + - migration_cost + - leftovers + properties: + migration_cost: + <<: *amount + description: Total amount which will be paid as fees for the migration. + leftovers: + <<: *amount + description: Leftovers dust coins which won't be migrated nor spent as fees. + + ApiWalletPassphrase: &ApiWalletPassphrase + type: object + required: + - passphrase + properties: + passphrase: + <<: *lenientPassphrase + description: The source Byron wallet's master passphrase. + + 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 + + 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) + + 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 + required: + - name + - encrypted_root_private_key + - passphrase_hash + properties: + style: + type: string + enum: ["random"] + name: *walletName + encrypted_root_private_key: *walletEncryptedRootPrivateKey + passphrase_hash: *walletPassphraseHash + + 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 + + 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 + + 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 + + ApiPostRedemptionFeeData: &ApiPostRedemptionFeeData + type: object + required: + - payments + - withdrawal + properties: + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + + ApiPostRandomAddressData: &ApiPostRandomAddressData + type: object + required: + - passphrase + properties: + passphrase: *lenientPassphrase + address_index: *addressIndex + + 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" + +############################################################################# +# # +# 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: false + 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. + + > ⚠️ On the incentivized testnet, this parameter is not requred, but rather completely ignored. + +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-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 + +############################################################################# +# # +# 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-responsesErr400: &responsesErr400 + 400: + description: Bad Request + content: + application/json: + schema: *responsesErr + +x-responsesErr403: &responsesErr403 + 403: + description: Forbidden + content: + application/json: + schema: *responsesErr + +x-responsesErr404: &responsesErr404 + 404: + description: Not Found + content: + application/json: + schema: *responsesErr + +x-responsesErr405: &responsesErr405 + 405: + description: Method Not Allowed + content: + application/json: + schema: *responsesErr + +x-responsesErr406: &responsesErr406 + 406: + description: Not Acceptable + content: + application/json: + schema: *responsesErr + +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-responsesListWallets: &responsesListWallets + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiWallet + +x-responsesListByronWallets: &responsesListByronWallets + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiByronWallet + +x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWalletUTxOsStatistics + +x-responsesPostWallet: &responsesPostWallet + <<: *responsesErr400 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr409 + <<: *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiWallet + +x-responsesPostByronWallet: &responsesPostByronWallet + <<: *responsesErr400 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr409 + <<: *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiByronWallet + +x-responsesGetWallet: &responsesGetWallet + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWallet + +x-responsesGetByronWallet: &responsesGetByronWallet + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiByronWallet + +x-responsesGetWalletMigrationInfo: &responsesGetWalletMigrationInfo + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWalletMigrationInfo + +x-responsesMigrateWallet: &responsesMigrateWallet + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiTransaction + +x-responsesDeleteWallet: &responsesDeleteWallet + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 204: + description: No Content + +x-responsesForceResyncWallet: &responsesForceResyncWallet + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 204: + description: No Content + +x-responsesPutWallet: &responsesPutWallet + <<: *responsesErr400 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 200: + description: Ok + content: + application/json: + schema: *ApiWallet + +x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 204: + description: No Content + +x-responsesSelectCoins: &responsesSelectCoins + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 200: + description: OK + content: + application/json: + schema: *ApiCoinSelection + +x-responsesDeleteTransaction: &responsesDeleteTransaction + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 204: + description: No Content + +x-responsesListTransactions: &responsesListTransactions + <<: *responsesErr404 + <<: *responsesErr405 + <<: *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 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: OK + content: + application/json: + schema: *ApiTransaction + +x-responsesPostTransaction: &responsesPostTransaction + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesPostExternalTransaction: &responsesPostExternalTransaction + <<: *responsesErr400 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiTxId + +x-responsesPostTransactionFee: &responsesPostTransactionFee + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiFee + +x-responsesGetDelegationFee: &responsesGetDelegationFee + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiFee + +x-responsesListAddresses: &responsesListAddresses + <<: *responsesErr400 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiAddress + +x-responsesListStakePools: &responsesListStakePools + <<: *responsesErr405 + <<: *responsesErr404 + 200: + description: Ok + content: + application/json: + schema: + oneOf: + - type: array + items: *ApiStakePool + title: "cardano-node stake pools" + - type: array + items: *ApiJormungandrStakePool + title: "jormungandr stake pools" + +x-responsesJoinStakePool: &responsesJoinStakePool + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr404 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesQuitStakePool: &responsesQuitStakePool + <<: *responsesJoinStakePool + +x-responsesGetNetworkInformation: &responsesGetNetworkInformation + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkInformation + +x-responsesGetNetworkClock: &responsesGetNetworkClock + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkClock + +x-responsesGetNetworkParameters: &responsesGetNetworkParameters + <<: *responsesErr405 + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkParameters + +x-responsesPostRandomAddress: &responsesPostRandomAddress + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr405 + <<: *responsesErr406 + <<: *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiAddress + +x-responsesPutRandomAddress: &responsesPutRandomAddress + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr405 + 204: + description: No Content + +x-responsesPutRandomAddresses: &responsesPutRandomAddresses + <<: *responsesErr400 + <<: *responsesErr403 + <<: *responsesErr405 + 204: + description: No Content + +############################################################################# +# # +# PATHS # +# # +############################################################################# + +x-tagGroups: + - name: Shelley (Sequential) + tags: + - Wallets + - Addresses + - Coin Selections + - Transactions + - Migrations + - Stake Pools + + - name: Byron (Random) + tags: + - Byron Wallets + - Byron Addresses + - Byron Coin Selections + - Byron Transactions + - Byron Migrations + + - name: Miscellaneous + tags: + - Network + - Proxy + +paths: + /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}/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 + + /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. + + > ⚠️ On the incentivized testnet, pools are instead ordered by + descending `desirability`. + + Some pools _may_ also have metadata attached to them. + parameters: + - *parametersIntendedStakeAmount + responses: *responsesListStakePools + + /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: | +

status: in development

+ + Submit one or more transactions which transfers all funds from a Shelley + wallet to a set of addresses. + + This operation attempts to preserve the UTxO "shape" of a wallet as far as possible. + That is, coins will not be agglomerated. Therefore, if the wallet has + a large UTxO set, several transactions may be needed. + + A typical usage would be when one wants to move all funds from an old wallet to another + by providing addresses coming from the new wallet. + parameters: + - <<: *parametersWalletId + name: walletId + requestBody: + required: true + content: + application/json: + schema: *ApiShelleyWalletMigrationPostData + responses: *responsesMigrateWallet + + get: + operationId: getShelleyWalletMigrationInfo + tags: ["Migrations"] + summary: Calculate Cost + description: | +

status: in development

+ + Calculate the exact cost of sending all funds from particular Shelley wallet + to a set of addresses. + parameters: + - <<: *parametersWalletId + name: walletId + responses: *responsesGetWalletMigrationInfo + + /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. + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - <<: *ApiByronWalletRandomPostData + title: random + - <<: *ApiByronWalletRandomXPrvPostData + title: random (from xprv) + - <<: *ApiByronWalletIcarusPostData + title: icarus + - <<: *ApiByronWalletTrezorPostData + title: trezor + - <<: *ApiByronWalletLedgerPostData + title: ledger + - <<: *ApiAccountPostData + title: icarus/trezor/ledger (from xpub) + 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}/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. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSelectCoinsData + responses: *responsesSelectCoins + + /byron-wallets/{walletId}/migrations: + post: + operationId: migrateByronWallet + tags: ["Byron Migrations"] + summary: Migrate + description: | +

status: stable

+ + Submit one or more transactions which transfers all funds from a Byron + wallet to a set of addresses. + + This operation attempts to preserve the UTxO "shape" of a wallet as far as possible. + That is, coins will not be agglomerated. Therefore, if the wallet has + a large UTxO set, several transactions may be needed. + + A typical usage would be when one wants to move all funds from an old wallet to another (Shelley + or Byron) by providing addresses coming from the new wallet. + parameters: + - <<: *parametersWalletId + name: walletId + requestBody: + required: true + content: + application/json: + schema: *ApiByronWalletMigrationPostData + responses: *responsesMigrateWallet + + get: + operationId: getByronWalletMigrationInfo + tags: ["Byron Migrations"] + summary: Calculate Cost + description: | +

status: stable

+ + Calculate the exact cost of sending all funds from particular Byron wallet to + a set of addresses. + parameters: + - <<: *parametersWalletId + name: walletId + responses: *responsesGetWalletMigrationInfo + + /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. + requestBody: + content: + application/octet-stream: + schema: *signedTransactionBlob + responses: *responsesPostExternalTransaction