Estimate Fee

POST /wallets/{walletId}/payment-fees

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.

Path parameters

walletId string(hex) Required

Minimum length is 40, maximum length is 40.

application/json

Body object Required

payments array[object] Required
A list of target outputs with amounts specified.

When creating a new transaction, the wallet software ensures that all user-specified transaction outputs have ada amounts that satisfy the ledger minimum UTxO rule:
- If a user-specified transaction output has an ada amount that is zero, the wallet software will automatically assign a minimal amount of ada to the output so that it satisfies the ledger minimum UTxO rule.
- If a user-specified transaction output has an ada amount that is non-zero, the wallet software will verify that the specified amount is large enough to satisfy the ledger minimum UTxO rule. If the amount is not large enough, the wallet software will return a utxo_too_small error, together with a revised ada amount that does satisfy the minimum UTxO rule.
At least 0 elements.
Hide payments attributes Show payments attributes object
- address string(base58|bech32) Required
  
  A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes which represents an address on the Cardano blockchain. Sequences in Base58 encoding are expected to be legacy Byron addresses, whereas sequences in Bech32 encoding correspond to current Shelley addresses.
  
  For more details, see CIP-0019 — Cardano addresses .
- amount object Required
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  Hide amount attributes Show amount attributes object
  
  quantity integer Required
  
  Minimum value is 0.
  
  unit string Required
  
  Value is lovelace.
- assets array[object]
  
  A flat list of assets (possibly empty).
  Hide assets attributes Show assets attributes object
  
  policy_id string(hex) Required
  
  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.
  
  Minimum length is 56, maximum length is 56.
  
  asset_name string(hex) Required
  
  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).
  
  Maximum length is 64.
  
  quantity integer Required
  
  Number of assets for the given policy_id and asset_name.
  
  Minimum value is 0.

withdrawal

string

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

Value is self.

metadata object | null
⚠️ 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.
Any of:
full object | null simple object | null
time_to_live object

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.
Hide time_to_live attributes Show time_to_live attributes object
- quantity number Required
  
  Minimum value is 0.0.
- unit string Required
  
  Value is second.

payments array[object] Required
A list of target outputs with amounts specified.

When creating a new transaction, the wallet software ensures that all user-specified transaction outputs have ada amounts that satisfy the ledger minimum UTxO rule:
- If a user-specified transaction output has an ada amount that is zero, the wallet software will automatically assign a minimal amount of ada to the output so that it satisfies the ledger minimum UTxO rule.
- If a user-specified transaction output has an ada amount that is non-zero, the wallet software will verify that the specified amount is large enough to satisfy the ledger minimum UTxO rule. If the amount is not large enough, the wallet software will return a utxo_too_small error, together with a revised ada amount that does satisfy the minimum UTxO rule.
At least 0 elements.
Hide payments attributes Show payments attributes object
- address string(base58|bech32) Required
  
  A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes which represents an address on the Cardano blockchain. Sequences in Base58 encoding are expected to be legacy Byron addresses, whereas sequences in Bech32 encoding correspond to current Shelley addresses.
  
  For more details, see CIP-0019 — Cardano addresses .
- amount object Required
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  Hide amount attributes Show amount attributes object
  
  quantity integer Required
  
  Minimum value is 0.
  
  unit string Required
  
  Value is lovelace.
- assets array[object]
  
  A flat list of assets (possibly empty).
  Hide assets attributes Show assets attributes object
  
  policy_id string(hex) Required
  
  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.
  
  Minimum length is 56, maximum length is 56.
  
  asset_name string(hex) Required
  
  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).
  
  Maximum length is 64.
  
  quantity integer Required
  
  Number of assets for the given policy_id and asset_name.
  
  Minimum value is 0.
withdrawal array[string(bip-0039-mnemonic-word{english})] Required

When provided, attempts to withdraw rewards from the default stake address corresponding to the given mnemonic.

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

withdrawal field reward balance result

any recovery phrase too small x Error 403 withdrawal_not_beneficial

any recovery phrase big enough ✓ withdrawal generated

At least 15 but not more than 24 elements.

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

Responses

415 application/json

Unsupported Media Type
Hide response attributes Show response attributes object
- message string Required
  
  May occur when providing an invalid 'Content-Type' header.
- code string Required
  
  Value is unsupported_media_type.
406 application/json

Not Acceptable
Hide response attributes Show response attributes object
- message string Required
  
  May occur when providing an invalid 'Accept' header.
- code string Required
  
  Value is not_acceptable.
404 application/json

Not Found
Hide response attributes Show response attributes object
- message string Required
  
  May occur when a given walletId does not match with any known wallets (because it has been deleted, or has never existed).
- code string Required
  
  Value is no_such_wallet.
- info object
  
  Hide info attribute Show info attribute object
  
  wallet_id string(hex) Required
  
  A unique identifier for the wallet
  
  Minimum length is 40, maximum length is 40.
400 application/json

Bad Request
Hide response attributes Show response attributes object
- message string Required
  
  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 string Required
  
  Value is bad_request.
403 application/json

Forbidden
One of:
invalid_wallet_type object already_withdrawing object utxo_too_small object cannot_cover_fee object no_utxos_available object not_enough_money object insufficient_collateral object inputs_depleted object invalid_coin_selection object output_token_quantity_exceeds_limit object output_token_bundle_size_exceeds_limit object transaction_is_too_big object
Hide attributes Show attributes

message string Required

May occur when trying to perform an operation not supported by this type of wallet.

code string Required

Value is invalid_wallet_type.
Hide attributes Show attributes

message string Required

May occur when submitting a withdrawal while another withdrawal is pending.

code string Required

Value is already_withdrawing.
Hide attributes Show attributes

message string Required

Occurs when a requested output has a quantity of lovelace that is below the minimum required by the ledger.

code string Required

Value is utxo_too_small.

info object

Hide info attributes Show info attributes object

tx_output_index integer Required

Minimum value is 0.

tx_output_lovelace_specified object Required

Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.

Hide tx_output_lovelace_specified attributes Show tx_output_lovelace_specified attributes object

quantity integer Required

Minimum value is 0.

unit string Required

Value is lovelace.

tx_output_lovelace_required_minimum object Required

Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.

Hide tx_output_lovelace_required_minimum attributes Show tx_output_lovelace_required_minimum attributes object

quantity integer Required

Minimum value is 0.

unit string Required

Value is lovelace.
Hide attributes Show attributes

message string Required

May occur when a transaction can't be balanced for fees.

code string Required

Value is cannot_cover_fee.
Hide attributes Show attributes

message string Required

Indicates that the wallet has no unspent transaction outputs (UTxOs) available. A transaction must spend at least one UTxO in order to be accepted for inclusion on the Cardano blockchain.

code string Required

Value is no_utxos_available.
Hide attributes Show attributes

message string Required

Indicates that there's not enough money in the wallet for the operation to succeed.

The 'shortfall' object indicates the additional quantity of each asset that would be needed in order for the operation to succeed.

code string Required

Value is not_enough_money.

info object

Hide info attribute Show info attribute object

shortfall object Required

The additional quantity of each asset that would be needed in order for the operation to succeed.

Hide shortfall attributes Show shortfall attributes object

ada object Required

Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.

Hide ada attributes Show ada attributes object

quantity integer Required

Minimum value is 0.

unit string Required

Value is lovelace.

assets array[object] Required

A flat list of assets (possibly empty).

Hide assets attributes Show assets attributes object

policy_id string(hex) Required

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.

Minimum length is 56, maximum length is 56.

asset_name string(hex) Required

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

Maximum length is 64.

quantity integer Required

Number of assets for the given policy_id and asset_name.

Minimum value is 0.
Hide attributes Show attributes

message string Required

May occur when the total balance of pure ada UTxOs in the wallet is insufficient to cover the minimum collateral amount required for a transaction requiring collateral.

code string Required

Value is insufficient_collateral.
Hide attributes Show attributes

message string Required

May occur when there's enough money to pay for a payment, but not enough UTxO to allow for paying each output independently.

code string Required

Value is inputs_depleted.
Hide attributes Show attributes

message string Required

Should never happen unless the server screwed up with the creation of a coin selection.

code string Required

Value is invalid_coin_selection.
Hide attributes Show attributes

message string Required

Returned when a user-specified transaction output contains, for some asset, a token quantity that exceeds the limit supported by the protocol.

code string Required

Value is output_token_quantity_exceeds_limit.

info object

Hide info attributes Show info attributes object

address string(base58|bech32) Required

A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes which represents an address on the Cardano blockchain. Sequences in Base58 encoding are expected to be legacy Byron addresses, whereas sequences in Bech32 encoding correspond to current Shelley addresses.

For more details, see CIP-0019 — Cardano addresses .

policy_id string(hex) Required

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.

Minimum length is 56, maximum length is 56.

asset_name string(hex) Required

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

Maximum length is 64.

quantity integer Required

Number of assets for the given policy_id and asset_name.

Minimum value is 0.

max_quantity integer Required

Number of assets for the given policy_id and asset_name.

Minimum value is 0.
Hide attributes Show attributes

message string Required

Returned when a user-specified transaction output contains a token bundle whose serialized length exceeds the limit supported by the protocol.

code string Required

Value is output_token_bundle_size_exceeds_limit.

info object

Hide info attributes Show info attributes object

address string(base58|bech32) Required

A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes which represents an address on the Cardano blockchain. Sequences in Base58 encoding are expected to be legacy Byron addresses, whereas sequences in Bech32 encoding correspond to current Shelley addresses.

For more details, see CIP-0019 — Cardano addresses .

bundle_size integer Required

Minimum value is 0.
Hide attributes Show attributes

message string Required

May occur when the wallet can't cover for all requested outputs without making the transaction too large.

code string Required

Value is transaction_is_too_big.
202 application/json

Accepted
Hide response attributes Show response attributes object
- estimated_min object Required
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  
  Hide estimated_min attributes Show estimated_min attributes object
  
  quantity integer Required
  
  Minimum value is 0.
  
  unit string Required
  
  Value is lovelace.
- estimated_max object Required
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  
  Hide estimated_max attributes Show estimated_max attributes object
  
  quantity integer Required
  
  Minimum value is 0.
  
  unit string Required
  
  Value is lovelace.
- minimum_coins array[object] Required
  
  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.
  
  At least 0 elements.
  
  Hide minimum_coins attributes Show minimum_coins attributes object
  
  quantity integer Required
  
  Minimum value is 0.
  
  unit string Required
  
  Value is lovelace.
- deposit object Required
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  
  Hide deposit attributes Show deposit attributes object
  
  quantity integer Required
  
  Minimum value is 0.
  
  unit string Required
  
  Value is lovelace.

POST /wallets/{walletId}/payment-fees

curl \
 --request POST https://localhost:8090/v2/wallets/{walletId}/payment-fees \
 --header "Content-Type: application/json" \
 --data '{"payments":[{"address":"addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g","amount":{"quantity":42000000,"unit":"lovelace"},"assets":[{"policy_id":"65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b","asset_name":"string","quantity":42}]}],"withdrawal":"self","metadata":{"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}}]}},"time_to_live":{"quantity":10.0,"unit":"second"}}'

Request examples

{
  "payments": [
    {
      "address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
      "amount": {
        "quantity": 42000000,
        "unit": "lovelace"
      },
      "assets": [
        {
          "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
          "asset_name": "string",
          "quantity": 42
        }
      ]
    }
  ],
  "withdrawal": "self",
  "metadata": {
    "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
          }
        }
      ]
    }
  },
  "time_to_live": {
    "quantity": 10.0,
    "unit": "second"
  }
}

{
  "payments": [
    {
      "address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
      "amount": {
        "quantity": 42000000,
        "unit": "lovelace"
      },
      "assets": [
        {
          "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
          "asset_name": "string",
          "quantity": 42
        }
      ]
    }
  ],
  "withdrawal": [
    "squirrel",
    "material",
    "silly",
    "twice",
    "direct",
    "slush",
    "pistol",
    "razor",
    "become",
    "junk",
    "kingdom",
    "flee",
    "squirrel",
    "silly",
    "twice"
  ]
}

Response examples (415)

{
  "message": "string",
  "code": "unsupported_media_type"
}

Response examples (406)

{
  "message": "string",
  "code": "not_acceptable"
}

Response examples (404)

{
  "message": "string",
  "code": "no_such_wallet",
  "info": {
    "wallet_id": "2512a00e9653fe49a44a5886202e24d77eeb998f"
  }
}

Response examples (400)

{
  "message": "string",
  "code": "bad_request"
}

Response examples (403)

{
  "message": "string",
  "code": "invalid_wallet_type"
}

{
  "message": "string",
  "code": "already_withdrawing"
}

{
  "message": "string",
  "code": "utxo_too_small",
  "info": {
    "tx_output_index": 42,
    "tx_output_lovelace_specified": {
      "quantity": 42000000,
      "unit": "lovelace"
    },
    "tx_output_lovelace_required_minimum": {
      "quantity": 42000000,
      "unit": "lovelace"
    }
  }
}

{
  "message": "string",
  "code": "cannot_cover_fee"
}

{
  "message": "string",
  "code": "no_utxos_available"
}

{
  "message": "string",
  "code": "not_enough_money",
  "info": {
    "shortfall": {
      "ada": {
        "quantity": 42000000,
        "unit": "lovelace"
      },
      "assets": [
        {
          "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
          "asset_name": "string",
          "quantity": 42
        }
      ]
    }
  }
}

{
  "message": "string",
  "code": "insufficient_collateral"
}

{
  "message": "string",
  "code": "inputs_depleted"
}

{
  "message": "string",
  "code": "invalid_coin_selection"
}

{
  "message": "string",
  "code": "output_token_quantity_exceeds_limit",
  "info": {
    "address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
    "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
    "asset_name": "string",
    "quantity": 42,
    "max_quantity": 42
  }
}

{
  "message": "string",
  "code": "output_token_bundle_size_exceeds_limit",
  "info": {
    "address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
    "bundle_size": 42
  }
}

{
  "message": "string",
  "code": "transaction_is_too_big"
}

Response examples (202)

{
  "estimated_min": {
    "quantity": 42000000,
    "unit": "lovelace"
  },
  "estimated_max": {
    "quantity": 42000000,
    "unit": "lovelace"
  },
  "minimum_coins": [
    {
      "quantity": 42000000,
      "unit": "lovelace"
    }
  ],
  "deposit": {
    "quantity": 42000000,
    "unit": "lovelace"
  }
}