Create / Restore

POST /wallets

status: stable

Create and restore a wallet from a mnemonic sentence or account public key.

application/json

Body object Required

One of:
shelley object shelley (from xpub) object

Restore from root private key

  • name string Required

    Minimum length is 1, maximum length is 255.

  • mnemonic_sentence array[string(bip-0039-mnemonic-word{english})] Required

    A list of mnemonic words

    At least 15 but not more than 24 elements.

  • mnemonic_second_factor array[string(bip-0039-mnemonic-word{english})]

    An optional passphrase used to encrypt the mnemonic sentence.

    At least 9 but not more than 12 elements.

  • passphrase string Required

    A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds)

    Minimum length is 10, maximum length is 255.

  • address_pool_gap integer

    Number of consecutive unused addresses allowed.

    IMPORTANT DISCLAIMER: Using values other than 20 automatically makes your wallet invalid with regards to BIP-44 address discovery. It means that you will not be able to fully restore your wallet in a different software which is strictly following BIP-44.

    Beside, using large gaps is not recommended as it may induce important performance degradations. Use at your own risks.

    IMPORTANT DISCLAIMER 2: There is no way to import addresses generated outside (e.g. using cardano-addresses) into the wallet. Wallet only discovers transactions on its used and unused addresses that are within its currently seen address_pool_gap. Transactions on addresses that "belong" to the wallet but happen to be beyond its address_pool_gap will not be visible to the wallet. This is a technical limitation of the industry standard BIP-44. See also CIP-1852.

    Minimum value is 10, maximum value is 100000. Default value is 20.

  • one_change_address_mode boolean

    Default value is false.

  • restoration_mode string | object

    The wallet restoration mode determines since when the wallet should be restored from the blockchain.

    One of:
    Restore from genesis string Restore from tip string Restore from block object

    Restore the wallet from the genesis block. This will cause the wallet to be restored from the very beginning of the blockchain.

    Value is from_genesis.

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.
  • 409 application/json

    Conflict

    Hide response attributes Show response attributes object
    • message string Required

      May occur when a otherwise valid request would yield a wallet that already exists.

    • code string Required

      Value is wallet_already_exists.
  • 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.
  • 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.
  • 201 application/json

    Created

    Hide response attributes Show response attributes object
    • id string(hex) Required

      A unique identifier for the wallet

      Minimum length is 40, maximum length is 40.

    • address_pool_gap integer Required

      Number of consecutive unused addresses allowed.

      IMPORTANT DISCLAIMER: Using values other than 20 automatically makes your wallet invalid with regards to BIP-44 address discovery. It means that you will not be able to fully restore your wallet in a different software which is strictly following BIP-44.

      Beside, using large gaps is not recommended as it may induce important performance degradations. Use at your own risks.

      IMPORTANT DISCLAIMER 2: There is no way to import addresses generated outside (e.g. using cardano-addresses) into the wallet. Wallet only discovers transactions on its used and unused addresses that are within its currently seen address_pool_gap. Transactions on addresses that "belong" to the wallet but happen to be beyond its address_pool_gap will not be visible to the wallet. This is a technical limitation of the industry standard BIP-44. See also CIP-1852.

      Minimum value is 10, maximum value is 100000. Default value is 20.

    • balance object Required

      Wallet current Ada balance(s).

      Additional properties are allowed.

      Hide balance attributes Show balance attributes object
      • available object Required

        Available Ada UTxO balance (funds that can be spent without condition).

        Additional properties are allowed.

        Hide available attributes Show available attributes object
        • quantity integer Required

          Minimum value is 0.

        • unit string Required

          Value is lovelace.

      • reward object Required

        The Ada balance of the reward account for this wallet.

        Additional properties are allowed.

        Hide reward attributes Show reward attributes object
        • quantity integer Required

          Minimum value is 0.

        • unit string Required

          Value is lovelace.

      • total object Required

        Total Ada balance (available balance plus pending change and reward balance).

        Additional properties are allowed.

        Hide total attributes Show total attributes object
        • quantity integer Required

          Minimum value is 0.

        • unit string Required

          Value is lovelace.

    • assets object Required

      Current non-Ada asset holdings of the wallet.

      The amount of assets available to spend may be less than the total unspent assets due to transaction change amounts which are yet to be fully confirmed (pending).

      Additional properties are allowed.

      Hide assets attributes Show assets attributes object
      • available array[object] Required

        Available UTxO asset balances (funds that can be spent without condition).

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

      • total array[object] Required

        Total asset balances (available balances plus pending change balances).

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

    • delegation object Required

      Delegation settings

      Additional properties are allowed.

      Hide delegation attributes Show delegation attributes object
      • active object Required

        Currently active delegation status.

        Additional properties are allowed.

        Hide active attributes Show active attributes object
        • status string Required

          Values are not_delegating, delegating, voting, or delegating_and_voting.

        • target string(hex|bech32)

          A unique Stake-Pool identifier (present only if status = delegating)

        • voting 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:
          casting a default vote string vote to a drep represented by key hash (deprecated) string(bech32) vote to a drep represented by script hash string(bech32) vote to a drep represented by key hash string(bech32)

          Values are abstain or no_confidence.

      • next array[object] Required

        Next delegation status becomes active at the start of the second epoch after the corresponding delegation certificate was discovered. The exact moment is specified by changes_at

        Hide next attributes Show next attributes object
        • status string Required

          Values are not_delegating, delegating, voting, or delegating_and_voting.

        • target string(hex|bech32)

          A unique Stake-Pool identifier (present only if status = delegating)

        • voting 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:
          casting a default vote string vote to a drep represented by key hash (deprecated) string(bech32) vote to a drep represented by script hash string(bech32) vote to a drep represented by key hash string(bech32)

          Values are abstain or no_confidence.

        • changes_at object Required

          Additional properties are allowed.

          Hide changes_at attributes Show changes_at attributes object
          • epoch_number integer Required

            An epoch is a time period which is divided into slots.

            Minimum value is 0.

          • epoch_start_time string(iso-8601-date-and-time) Required
    • name string Required

      Minimum length is 1, maximum length is 255.

    • passphrase object

      Information about the wallet's passphrase

      Additional properties are allowed.

      Hide passphrase attribute Show passphrase attribute object
    • state object Required

      Whether a wallet is ready to use or still syncing

      Additional properties are allowed.

      Hide state attributes Show state attributes object
      • status string Required

        Values are ready, syncing, or not_responding.

      • progress object

        if: status == syncing

        Additional properties are allowed.

        Hide progress attributes Show progress attributes object
        • quantity number Required

          Minimum value is 0, maximum value is 100.

        • unit string Required

          Value is percent.

    • tip object Required

      A reference to a particular time slot, and the block height at that point.

      Additional properties are allowed.

      Hide tip attributes Show tip attributes object
      • absolute_slot_number integer Required

        The 0-based slot index starting from genesis of the blockchain.

        Minimum value is 0.

      • slot_number integer Required

        The zero-based slot index within an epoch.

        Minimum value is 0.

      • epoch_number integer Required

        An epoch is a time period which is divided into slots.

        Minimum value is 0.

      • time string(iso-8601-date-and-time) Required
      • height object Required

        Additional properties are allowed.

        Hide height attributes Show height attributes object
        • quantity integer Required

          Minimum value is 0.

        • unit string Required

          Value is block.
POST /wallets 
curl \
 --request POST 'https://localhost:8090/v2/wallets' \
 --header "Content-Type: application/json" \
 --data '{"name":"Alan's Wallet","mnemonic_sentence":["squirrel","material","silly","twice","direct","slush","pistol","razor","become","junk","kingdom","flee","squirrel","silly","twice"],"mnemonic_second_factor":["squirrel","material","silly","twice","direct","slush","pistol","razor","become"],"passphrase":"Secure Passphrase","address_pool_gap":20,"one_change_address_mode":false,"restoration_mode":"from_genesis"}'
Request examples 
{
  "name": "Alan's Wallet",
  "mnemonic_sentence": [
    "squirrel",
    "material",
    "silly",
    "twice",
    "direct",
    "slush",
    "pistol",
    "razor",
    "become",
    "junk",
    "kingdom",
    "flee",
    "squirrel",
    "silly",
    "twice"
  ],
  "mnemonic_second_factor": [
    "squirrel",
    "material",
    "silly",
    "twice",
    "direct",
    "slush",
    "pistol",
    "razor",
    "become"
  ],
  "passphrase": "Secure Passphrase",
  "address_pool_gap": 20,
  "one_change_address_mode": false,
  "restoration_mode": "from_genesis"
}
{
  "name": "Alan's Wallet",
  "account_public_key": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1",
  "address_pool_gap": 20
}
Response examples (415) 
{
  "message": "string",
  "code": "unsupported_media_type"
}
Response examples (409) 
{
  "message": "string",
  "code": "wallet_already_exists"
}
Response examples (406) 
{
  "message": "string",
  "code": "not_acceptable"
}
Response examples (400) 
{
  "message": "string",
  "code": "bad_request"
}
Response examples (201) 
{
  "id": "2512a00e9653fe49a44a5886202e24d77eeb998f",
  "address_pool_gap": 20,
  "balance": {
    "available": {
      "quantity": 42000000,
      "unit": "lovelace"
    },
    "reward": {
      "quantity": 42000000,
      "unit": "lovelace"
    },
    "total": {
      "quantity": 42000000,
      "unit": "lovelace"
    }
  },
  "assets": {
    "available": [
      {
        "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
        "asset_name": "string",
        "quantity": 42
      }
    ],
    "total": [
      {
        "policy_id": "65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b",
        "asset_name": "string",
        "quantity": 42
      }
    ]
  },
  "delegation": {
    "active": {
      "status": "delegating",
      "target": "1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1"
    },
    "next": [
      {
        "status": "not_delegating",
        "changes_at": {
          "epoch_number": 14,
          "epoch_start_time": "2020-01-22T10:06:39Z"
        }
      }
    ]
  },
  "name": "Alan's Wallet",
  "passphrase": {
    "last_updated_at": "2019-02-27T14:46:45Z"
  },
  "state": {
    "status": "ready"
  },
  "tip": {
    "absolute_slot_number": 8086,
    "slot_number": 1337,
    "epoch_number": 14,
    "time": "2019-02-27T14:46:45Z",
    "height": {
      "quantity": 1337,
      "unit": "block"
    }
  }
}