🔐 Register an account zpub
Code samples
POST /api/v1/btc/xpub
curl -X POST 'https://settla.net/api/v1/btc/xpub' \
-H 'X-API-Key: $SETTLA_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xpub": "zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtymD9xYYfG1m4wAcvPhXNfE3EfH1r1ADqtfSdVCToUG868RvUUkgDKf31mGDtKsAYz2oz2AGutZYs",
"label": "shop-1"
}'
Only an extended PUBLIC key is accepted. The service neither accepts nor stores private keys or mnemonics: zprv/xprv are rejected with 422. Signing stays on the client side; the signed transaction is broadcast through /api/v1/btc/transactions/send-raw.
Only a zpub is accepted — xpub and ypub are rejected, because they correspond to a different script type (P2PKH and P2WPKH-in-P2SH), and silently handing out a bech32 address for them would send the client's funds somewhere the client is not watching.
Addresses are derived as 0/{index} below the supplied account key, i.e. the same bc1q… addresses a wallet shows for m/84'/0'/0'/0/{index}.
Body parameter
{
"xpub": "zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtymD9xYYfG1m4wAcvPhXNfE3EfH1r1ADqtfSdVCToUG868RvUUkgDKf31mGDtKsAYz2oz2AGutZYs",
"label": "shop-1"
}
🛠️ Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » xpub | body | string | true | Account-level BIP84 extended public key (zpub), base58check. |
| » label | body | string | false | none |
Example responses
201 Response
{
"id": 1,
"chain": "BTC",
"fingerprint": "1a2b3c4d",
"label": "shop-1",
"xpub_preview": "zpub6rFR…tZYs",
"next_index": 3,
"issued_count": 3,
"created_at": "2025-07-23T15:16:00Z"
}
🔁 Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Key registered (repeat calls with the same key return the same record) | Inline |
| 422 | Unprocessable Entity | Key could not be parsed, is a private key, or is not a zpub | None |
🔄 Response Schema
Status Code 201
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » id | integer | false | none | none |
| » chain | string | false | none | none |
| » fingerprint | string | false | none | First 4 bytes of hash160(pubkey), hex — lets the client tell its keys apart. |
| » label | string¦null | false | none | none |
| » xpub_preview | string | false | none | Masked key; the full value is never returned, it would reveal the whole address history. |
| » next_index | integer | false | none | none |
| » issued_count | integer | false | none | none |
| » created_at | string(date-time) | false | none | none |