Random

POST /wallets/{walletId}/coin-selections/random

status: stable

Select coins to cover the given set of payments.

Uses the Random-Improve coin selection algorithm.

Path parameters

  • walletId string(hex) Required

    Minimum length is 40, maximum length is 40.

application/json

Body object Required

One of:
Normal payment object Delegation object Reward redemption object

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:
    already_withdrawing object utxo_too_small object no_utxos_available object not_enough_money object insufficient_collateral object cannot_cover_fee object inputs_depleted object invalid_coin_selection object output_token_quantity_exceeds_limit object output_token_bundle_size_exceeds_limit object
  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • inputs array[object] Required

      A list of transaction inputs

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

      • id string(hex) Required

        A unique identifier for this transaction

        Minimum length is 64, maximum length is 64.

      • derivation_path array[string] Required

        An individual segment within a derivation path.

        The H suffix indicates a Hardened child private key, which means that children of this key cannot be derived from the public key. Indices without a H suffix are called Soft.

        At least 1 element.

      • index integer Required

        Minimum value is 0.

    • outputs 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 outputs attributes Show outputs 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.

    • change array[object] Required

      A list of transaction change outputs.

      At least 0 elements.

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

      • derivation_path array[string] Required

        An individual segment within a derivation path.

        The H suffix indicates a Hardened child private key, which means that children of this key cannot be derived from the public key. Indices without a H suffix are called Soft.

        At least 1 element.

    • collateral array[object]

      A list of transaction inputs used for collateral

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

      • id string(hex) Required

        A unique identifier for this transaction

        Minimum length is 64, maximum length is 64.

      • derivation_path array[string] Required

        An individual segment within a derivation path.

        The H suffix indicates a Hardened child private key, which means that children of this key cannot be derived from the public key. Indices without a H suffix are called Soft.

        At least 1 element.

      • index integer Required

        Minimum value is 0.

    • withdrawals array[object]

      A list of withdrawals from stake addresses.

      At least 0 elements.

      Hide withdrawals attributes Show withdrawals attributes object
      • stake_address string(bech32) Required
      • derivation_path array[string] Required

        An individual segment within a derivation path.

        The H suffix indicates a Hardened child private key, which means that children of this key cannot be derived from the public key. Indices without a H suffix are called Soft.

        At least 1 element.

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

      • Additional properties are NOT allowed
    • certificates array[object]
      Hide certificates attributes Show certificates attributes object
      • certificate_type string Required

        Values are join_pool, quit_pool, or register_reward_account.

      • pool string(hex|bech32)

        A unique identifier for the pool.

      • reward_account_path array[string] Required

        At least 5 but not more than 5 elements.

    • deposits_taken array[object]

      A list of deposits associated with a transaction.

      At least 0 elements.

      Hide deposits_taken attributes Show deposits_taken attributes object
      • quantity integer Required

        Minimum value is 0.

      • unit string Required

        Value is lovelace.

    • deposits_returned array[object]

      A list of deposits associated with a transaction.

      At least 0 elements.

      Hide deposits_returned attributes Show deposits_returned attributes object
      • quantity integer Required

        Minimum value is 0.

      • unit string Required

        Value is lovelace.

    • metadata string(base64)

      Transaction metadata, serialized according to the expected on-chain binary format, base64-encoded.
POST /wallets/{walletId}/coin-selections/random 
curl \
 --request POST https://localhost:8090/v2/wallets/{walletId}/coin-selections/random \
 --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}}]}}}'
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
          }
        }
      ]
    }
  }
}
{
  "delegation_action": {
    "action": "quit",
    "pool": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm"
  }
}
{
  "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"
  ],
  "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
          }
        }
      ]
    }
  }
}
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": "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": "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": "cannot_cover_fee"
}
{
  "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
  }
}
Response examples (200) 
{
  "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"
}