BTbtcpayserver
Derivations

Get a new unused address

Changed on

Retrieves a new unused address from the specified derivation scheme. This endpoint allows you to generate new addresses for receiving funds, ensuring that you do not reuse addresses.

get/v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/addresses/unused

Request

Path parameters

cryptoCodestring required

The cryptocurrency code to track (e.g., 'BTC' for Bitcoin, 'LTC' for Litecoin).

derivationSchemestring required

The derivation scheme (See documentation)

Query parameters

feature'Deposit' | 'Change' | 'Direct' | 'Custom'

Optional. Specifies the type of address to generate:

  • Deposit: Get a deposit address from the external chain (0/x).
  • Change: Get a change address from the internal chain (1/x).
  • Direct: Get an address from the direct chain (x).
  • Custom: Use customKeyPathTemplate if configured. Default is Deposit.
skipinteger

Optional. The number of addresses to skip. Useful for getting multiple unused addresses. Default is 0.

reserveboolean

Optional. If set to true, the returned address will be marked as used. Default is false.

autoTrackboolean

Track the derivation scheme automatically if it is not already tracked.

Response

Successfully retrieved an unused address.

trackedSourcestring nullable

The tracked source identifier, typically representing the derivation scheme being used.

featurestring

Specifies the type of address generated. Possible values are:

  • Deposit: A deposit address from the external chain (0/x).
  • Change: A change address from the internal chain (1/x).
  • Direct: An address from the direct chain (x).
  • Custom: An address using a custom key path template.
derivationStrategystring

The derivation strategy used to derive addresses, typically the extended public key (xpub) with optional suffixes indicating the script type.

keyPathstring nullable

The derivation path used to generate this address, e.g., 0/123. (Only for standard derivation schemes)

indexinteger nullable

The derivation path index of this address

scriptPubKeystring

The scriptPubKey of the generated address in hexadecimal format.

addressstring

The generated address, in base58 or bech32 format, depending on the script type.

redeemstring nullable

The redeem script associated with the address (if applicable). Returns the SegWit redeem script if the derivation scheme is P2SH-P2WPKH or P2WPKH, or the P2SH redeem script if the script type is P2SH.

blindingKeystring nullable

The blinding private key (Liquid Only)

Example response

{
  "trackedSource": "DERIVATIONSCHEME:tpubD6NzVbkrYhZ4WcPozSqALNCrJEt4C45sPDhEBBuok...",
  "feature": "Deposit",
  "derivationStrategy": "tpubD6NzVbkrYhZ4WcPozSqALNCrJEt4C45sPDhEBBuok...",
  "keyPath": "0/123",
  "index": 123,
  "scriptPubKey": "001460c25d29559774803f262acf5ee5c922eff52ccd",
  "address": "tb1qvrp96224ja6gq0ex9t84aewfythl2txdkpdmu0",
  "redeem": "0014e2eb89edba1fe6c6c0863699eeb78f6ec3271b45",
  "blindingKey": "9b73aab73a972485defe9d1d27217267eb17541a393e19d820549acf3fe69308"
}

Changes

  • 52231f42c765Revision changes
    • info

      added the new optional query request parameter autoTrack

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

  • 7a5c59ac1e4dRevision changes
    • info

      added the optional property to the response with the status