Balance

POST /wallets/{walletId}/transactions-balance

status: under development

Balance a transaction body of a given transaction, add needed inputs/outputs, so as the transaction can be signed from the wallet.

Path parameters

walletId string(hex) Required

Minimum length is 40, maximum length is 40.

application/json

Body Required

transaction string(base64|base16) Required

The CBOR-encoded transaction, represented in either hex or base64 encoding. This always includes the transaction body and the witness set, even if the latter is empty.
inputs array[object]

Mapping from inputs (id, ix) in the supplied transaction binary to outputs (amount, assets, ...). It is not required to include inputs present in the cardano-node UTxO, as cardano-wallet will automatically query for them.

In other words, this field can be left empty unless the supplied transaction contains inputs referring to pending transactions.
Hide inputs attributes Show inputs attributes object
- id string(hex) Required
  
  A unique identifier for this transaction
  
  Minimum length is 64, maximum length is 64.
- index integer Required
  
  Minimum value is 0.
- 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.
- datum string(hex)
  
  A datum hash.
  
  Minimum length is 64, maximum length is 64.
- 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.
redeemers array[object]

A list of redeemers data with their purpose. The redeemers in the transaction binary will be overwritten by this value.
One of:
spending object minting object rewarding object
Hide attributes Show attributes

purpose string Required

Value is spending.

data string(base16) Required

input object Required

Hide input attributes Show input attributes object

id string(hex) Required

A unique identifier for this transaction

Minimum length is 64, maximum length is 64.

index integer Required

Minimum value is 0.
Hide attributes Show attributes

purpose string Required

Value is minting.

data string(base16) Required

policy_id string(hex) Required

Maximum length is 56.
Hide attributes Show attributes

purpose string Required

Value is rewarding.

data string(base16) Required

stake_address string(bech32) Required
encoding string

Encoding of transaction CBOR returned in response (base64 by default).

Values are base16 or base64.

Responses

400 application/json

Bad Request
One of:
bad_request object redeemer_script_failure object redeemer_target_not_found object redeemer_invalid_data object translation_error object unresolved_inputs object input_resolution_conflicts object
Hide attributes Show attributes

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

message string Required

Occurs when balancing transaction with failing scripts.

code string Required

Value is redeemer_script_failure.
Hide attributes Show attributes

message string Required

Occurs when balancing transaction with reedemers that point to unknown entities.

code string Required

Value is redeemer_target_not_found.
Hide attributes Show attributes

message string Required

Occurs when data in provided redeemers do not decode to valid Plutus data.

code string Required

Value is redeemer_invalid_data.
Hide attributes Show attributes

message string Required

Occurs when any data in a provided transaction cannot be translated in a given era

code string Required

Value is translation_error.
Hide attributes Show attributes

message string Required

There are inputs in the transaction for which the corresponding outputs could not be found.

code string Required

Value is unknown_inputs.
Hide attributes Show attributes

message string Required

At least one of the provided inputs has an asset quantity or address that is different from that recorded in the wallet's UTxO set.

code string Required

Value is input_resolution_conflicts.
403 application/json

Forbidden
One of:
already_withdrawing object node_not_yet_in_recent_era object balance_tx_conflicting_networks object balance_tx_existing_collateral object balance_tx_existing_key_witnesses object balance_tx_existing_collateral_return_outputs object balance_tx_existing_total_collateral object balance_tx_internal_error object cannot_cover_fee object insufficient_collateral object invalid_wallet_type object no_utxos_available object not_enough_money object transaction_already_balanced object transaction_is_too_big object utxo_too_small object tx_not_in_node_era object balance_tx_inline_plutus_v3_script_not_supported_in_babbage object translation_byron_tx_out_in_context object
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.
Occurs when the operation requires the node to be in a recent era, but is not.

Hide attributes Show attributes

message string Required

code string Required

Value is node_not_yet_in_recent_era.

info object

Hide info attributes Show info attributes object

node_era string Required

Values are byron, shelley, allegra, mary, alonzo, babbage, or conway.

recent_eras array[string] Required

Values are byron, shelley, allegra, mary, alonzo, babbage, or conway.
Hide attributes Show attributes

message string Required

There are withdrawals for multiple networks (e.g. both mainnet and testnet) in the provided transaction. This makes no sense, and I'm confused.

code string Required

Value is balance_tx_conflicting_networks.
Hide attributes Show attributes

message string Required

I cannot balance transactions with pre-defined collateral.

code string Required

Value is balance_tx_existing_collateral.
Hide attributes Show attributes

message string Required

The transaction could not be balanced, because it contains existing key-witnesses which would be invalid after the transaction body is modified. Please sign the transaction after it is balanced instead.

code string Required

Value is balance_tx_existing_key_witnesses.
Hide attributes Show attributes

message string Required

Balancing transactions with pre-defined collateral return outputs is not yet supported.

code string Required

Value is balance_tx_existing_collateral_return_outputs.
Hide attributes Show attributes

message string Required

I cannot balance transactions with pre-defined total collateral.

code string Required

Value is balance_tx_existing_total_collateral.
Hide attributes Show attributes

message string Required

Balancing transaction failed for an internal reason.

code string Required

Value is balance_tx_internal_error.
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 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 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

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

Occurs when a transaction is already balanced.

code string Required

Value is transaction_already_balanced.
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.
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

The transaction could be deserialised, just not in the era of the local node.

code string Required

Value is tx_not_in_node_era.
Hide attributes Show attributes

message string Required

Inline Plutus V3 scripts are not supported in Babbage.

code string Required

Value is balance_tx_inline_plutus_v3_script_not_supported_in_babbage.
Hide attributes Show attributes

message string Required

The given transaction contains a Byron-style TxOut which i not supported when executing Plutus scripts.

code string Required

Value is translation_byron_tx_out_in_context.
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.
202 application/json

Accepted
Hide response attribute Show response attribute object
- transaction string(base64|base16) Required
  
  The CBOR-encoded transaction, represented in either hex or base64 encoding. This always includes the transaction body and the witness set, even if the latter is empty.

POST /wallets/{walletId}/transactions-balance

curl \
 --request POST https://localhost:8090/v2/wallets/{walletId}/transactions-balance \
 --header "Content-Type: application/json" \
 --data '{"transaction":"string","inputs":[{"id":"1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1","index":42,"address":"addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g","amount":{"quantity":42000000,"unit":"lovelace"},"datum":"16f30f4e8d665d53eb4ab6028bd0ac971809d514c92d423856bc91c49e928faf","assets":[{"policy_id":"65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b","asset_name":"string","quantity":42}]}],"redeemers":[{"purpose":"spending","data":"string","input":{"id":"1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1","index":42}}],"encoding":"base16"}'

Request examples

{
  "transaction": "string",
  "inputs": [
    {
      "id": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1",
      "index": 42,
      "address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
      "amount": {
        "quantity": 42000000,
        "unit": "lovelace"
      },
      "datum": "16f30f4e8d665d53eb4ab6028bd0ac971809d514c92d423856bc91c49e928faf",
      "assets": [
        {
          "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
          "asset_name": "string",
          "quantity": 42
        }
      ]
    }
  ],
  "redeemers": [
    {
      "purpose": "spending",
      "data": "string",
      "input": {
        "id": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1",
        "index": 42
      }
    }
  ],
  "encoding": "base16"
}

Response examples (400)

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

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

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

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

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

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

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

Response examples (403)

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

{
  "message": "string",
  "code": "node_not_yet_in_recent_era",
  "info": {
    "node_era": "byron",
    "recent_eras": [
      "byron"
    ]
  }
}

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

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

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

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

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

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

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

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

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

{
  "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": "transaction_already_balanced"
}

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

{
  "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": "tx_not_in_node_era"
}

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

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

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 (202)

{
  "transaction": "string"
}