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]
  
  An asset on the Cardano blockchain. An asset is uniquely identified by its policy_id and asset_name (together, these form the asset id).
  
  Two assets with the same asset_name and policy_id are interchangeable. Yet, different assets with a same policy_id but different asset_name are treated as separate assets, as are two assets with the same asset_name but different policy_id.
  
  An asset on the Cardano blockchain. An asset is uniquely identified by its policy_id and asset_name (together, these form the asset id).
  
  Two assets with the same asset_name and policy_id are interchangeable. Yet, different assets with a same policy_id but different asset_name are treated as separate assets, as are two assets with the same asset_name but different policy_id.
  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
Any of:
full object | null simple 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:

All top-level keys must be integers between 0 and 2^64 - 1.

Each metadata value is tagged with its type.

Strings must be at most 64 bytes when UTF-8 encoded.

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.
Hide attribute Show attribute

Additional properties: object

One of:
String object Int object ByteString object List object Map object

Hide attribute Show attribute

map array[object | null] Required

Hide map attributes Show map attributes object | null

k

v
⚠️ 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:

All top-level keys must be integers between 0 and 2^64 - 1.

Each metadata value is tagged with its type.

Strings must be at most 64 bytes when UTF-8 encoded.

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.
Hide attribute Show attribute

Additional properties: string | integer | array | object

One of:
String string Int integer List array Map object
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.
- 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]
  
  An asset on the Cardano blockchain. An asset is uniquely identified by its policy_id and asset_name (together, these form the asset id).
  
  Two assets with the same asset_name and policy_id are interchangeable. Yet, different assets with a same policy_id but different asset_name are treated as separate assets, as are two assets with the same asset_name but different policy_id.
  
  An asset on the Cardano blockchain. An asset is uniquely identified by its policy_id and asset_name (together, these form the asset id).
  
  Two assets with the same asset_name and policy_id are interchangeable. Yet, different assets with a same policy_id but different asset_name are treated as separate assets, as are two assets with the same asset_name but different policy_id.
  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

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

May occur when there's not enough money in the wallet to cover a requested payment.

code string Required

Value is not_enough_money.
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.
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.
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.
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.
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.
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.
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
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  
  Coins, in Lovelace. Only relates to 'Ada'. Refer to assets for multi-assets wallets instead.
  
  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 \
 -X POST https://localhost:8090/v2/wallets/{walletId}/payment-fees \
 -H "Content-Type: application/json" \
 -d '{"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,"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,
    "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 (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": "not_enough_money"
}

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

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

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

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

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

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

Response examples (404)

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

Response examples (406)

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

Response examples (415)

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

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