Construct
status: stable
Create a transaction to be signed from the wallet.
Path parameters
-
walletId
string(hex) Required Minimum length is
40
, maximum length is40
.
Body
Required
-
payments
array[object] 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 autxo_too_small
error, together with a revised ada amount that does satisfy the minimum UTxO rule.
At least
0
elements. -
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:
All top-level keys must be integers between
0
and2^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)
to2^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
orbool
values. When reading metadata from chain, be aware that integers may exceed the javascript numeric range, and may need special "bigint" parsing.-
encrypt_metadata
object If used then metadata in a transaction is going to be encrypted by AES 256 using CBC mode which is a default method (called base). PBKDF2 password stretching is used to get a 32-byte secret key and a 16-byte initialization vector required in the cipher. PBKDF2 encryption algorithm using HMAC with the SHA256 hash algorithm is employed, and 10000 iterations to get key and iv pair are used. Cipher algorithm uses 8-byte salt, PKCS#7 padding as specified in https://datatracker.ietf.org/doc/html/rfc5652#section-6.3 is applied. Only metadata value under
msg
field is encrypted. Ifmsg
field is missing error will be emitted. Metadata encryption is in accordance to CIP 83 (https://cips.cardano.org/cips/cip83/). -
mint_burn
array[object] An entry for each unique asset to be minted and/or burned, containing helpful information.
At least
1
element. vote
string | string(bech32) Decentralized representative (DRep) that the wallet is delegating its vote to. One can abstain, give no confidence vote, or vote for a representative specified by a key hash or script hash. Vote delegation can be done together with stake delegation action.
One of: Values are
abstain
orno_confidence
.DRep's key hash.
Format should match the following pattern:
^(drep)1[0-9a-z]*$
.DRep's script hash.
Format should match the following pattern:
^(drep_script)1[0-9a-z]*$
.-
delegations
array[object] status: stable
A list of staking actions (joining, rejoining or leaving from stake pools). Using '0H' stake key index is supported at this moment. This will change with multi-account support. Only one delegation action can be used.
At least
0
elements.A delegation action for a given stake key denoted by its soft index. Pool id is only required for "join". Stake key index are required for both actions.
-
validity_interval
object Specify only invalid_before or invalid_hereafter or both.
Please note that, if not set, the default values are:
"invalid_before": {"quantity":0, "unit":"slot"}
"invalid_hereafter":{"quantity":7200, "unit":"second"}
Which translates to 2h transaction TTL.
reference_policy_script_template
string | object Optional policy script template that could be used as a script reference in another transaction. In the current transaction, the script will be included as the first output (
index = 0
). The script is constructed by replacing the cosigner with the policy public key of the wallet. In future transactions, the reference script can be used by any wallet multiple times by referencing the current transactionid
andindex = 0
. The script template must contain a single cosigner only, but it may include time locks.One of: Leaf value for a script designating a cosigner co-sharing the script.
Format should match the following pattern:
^(cosigner#)[0-9]*$
.-
encoding
string Encoding of transaction CBOR returned in response (base64 by default).
Values are
base16
orbase64
.
Responses
-
415 application/json
Unsupported Media Type
-
406 application/json
Not Acceptable
-
404 application/json
Not Found
-
400 application/json
Bad Request
-
403 application/json
Forbidden
One of: invalid_wallet_typeobject already_withdrawingobject utxo_too_smallobject cannot_cover_feeobject no_utxos_availableobject not_enough_moneyobject insufficient_collateralobject transaction_is_too_bigobject created_multidelegation_transactionobject created_multiaccount_transactionobject created_wrong_policy_script_templateobject asset_name_too_longobject mint_or_burn_asset_quantity_out_of_boundsobject invalid_validity_boundsobject validity_interval_not_inside_script_timelockobject shared_wallet_incompleteobject staking_invalidobject voting_in_invalid_eraobject withdrawal_not_possible_without_voteobject invalid_metadata_encryptionobject -
202 application/json
Accepted
curl \
--request POST https://localhost:8090/v2/wallets/{walletId}/transactions-construct \
--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}}]}},"encrypt_metadata":{"method":"basic","passphrase":"Secure Passphrase"},"mint_burn":[{"policy_script_template":"string","asset_name":"string","operation":{"mint":{"receiving_address":"addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g","quantity":42}}}],"vote":"abstain","delegations":[{"join":{"pool":"pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm","stake_key_index":"1852H"}}],"validity_interval":{"invalid_before":{"quantity":10.0,"unit":"second"},"invalid_hereafter":{"quantity":10.0,"unit":"second"}},"reference_policy_script_template":"string","encoding":"base16"}'
{
"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
}
}
]
}
},
"encrypt_metadata": {
"method": "basic",
"passphrase": "Secure Passphrase"
},
"mint_burn": [
{
"policy_script_template": "string",
"asset_name": "string",
"operation": {
"mint": {
"receiving_address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
"quantity": 42
}
}
}
],
"vote": "abstain",
"delegations": [
{
"join": {
"pool": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm",
"stake_key_index": "1852H"
}
}
],
"validity_interval": {
"invalid_before": {
"quantity": 10.0,
"unit": "second"
},
"invalid_hereafter": {
"quantity": 10.0,
"unit": "second"
}
},
"reference_policy_script_template": "string",
"encoding": "base16"
}
{
"message": "string",
"code": "unsupported_media_type"
}
{
"message": "string",
"code": "not_acceptable"
}
{
"message": "string",
"code": "no_such_wallet",
"info": {
"wallet_id": "2512a00e9653fe49a44a5886202e24d77eeb998f"
}
}
{
"message": "string",
"code": "bad_request"
}
{
"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": "transaction_is_too_big"
}
{
"message": "string",
"code": "created_multidelegation_transaction"
}
{
"message": "string",
"code": "created_multiaccount_transaction"
}
{
"message": "string",
"code": "created_wrong_policy_script_template"
}
{
"message": "string",
"code": "asset_name_too_long"
}
{
"message": "string",
"code": "mint_or_burn_asset_quantity_out_of_bounds"
}
{
"message": "string",
"code": "invalid_validity_bounds"
}
{
"message": "string",
"code": "validity_interval_not_inside_script_timelock"
}
{
"message": "string",
"code": "shared_wallet_incomplete"
}
{
"message": "string",
"code": "staking_invalid"
}
{
"message": "string",
"code": "voting_in_invalid_era"
}
{
"message": "string",
"code": "withdrawal_not_possible_without_vote"
}
{
"message": "string",
"code": "invalid_metadata_encryption"
}
{
"transaction": "string",
"coin_selection": {
"inputs": [
{
"address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
"amount": {
"quantity": 42000000,
"unit": "lovelace"
},
"assets": [
{
"policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
"asset_name": "string",
"quantity": 42
}
],
"id": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1",
"derivation_path": [
"1852H"
],
"index": 42
}
],
"outputs": [
{
"address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
"amount": {
"quantity": 42000000,
"unit": "lovelace"
},
"assets": [
{
"policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
"asset_name": "string",
"quantity": 42
}
]
}
],
"change": [
{
"address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
"amount": {
"quantity": 42000000,
"unit": "lovelace"
},
"assets": [
{
"policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
"asset_name": "string",
"quantity": 42
}
],
"derivation_path": [
"1852H"
]
}
],
"collateral": [
{
"address": "addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g",
"amount": {
"quantity": 42000000,
"unit": "lovelace"
},
"id": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1",
"derivation_path": [
"1852H"
],
"index": 42
}
],
"withdrawals": [
{
"stake_address": "stake1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2x",
"derivation_path": [
"1852H"
],
"amount": {
"quantity": 42000000,
"unit": "lovelace"
}
}
],
"certificates": [
{
"certificate_type": "join_pool",
"pool": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm",
"reward_account_path": [
"string"
]
}
],
"deposits_taken": [
{
"quantity": 42000000,
"unit": "lovelace"
}
],
"deposits_returned": [
{
"quantity": 42000000,
"unit": "lovelace"
}
],
"metadata": "string"
},
"fee": {
"quantity": 42000000,
"unit": "lovelace"
}
}