Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 27 additions & 6 deletions docs/guides/chain-fusion/bitcoin.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -388,42 +388,61 @@ async fn withdraw(btc_address: String, amount: u64) -> RetrieveBtcResult {
</TabItem>
</Tabs>

### Interact with ckBTC using icp-cli
### Deposit, mint, and transfer (icp-cli)

This walkthrough covers the full ckBTC deposit flow: getting a deposit address, checking the confirmation requirement, minting ckBTC, and transferring to another principal.

First, export your principal from your active identity (every command below reuses it):

```bash
export MY_PRINCIPAL=$(icp identity principal)
```

Get a deposit address:
**Step 1: Get a deposit address**

```bash
icp canister call mqygn-kiaaa-aaaar-qaadq-cai get_btc_address \
"(record { owner = opt principal \"$MY_PRINCIPAL\"; subaccount = null })" \
-n ic
```

Check for new deposits and mint ckBTC:
Send BTC to the returned address from any Bitcoin wallet.

**Step 2: Check the confirmation requirement**

The minter does not mint ckBTC until the depositing Bitcoin transaction reaches a minimum number of confirmations. Query the current threshold before waiting:

```bash
icp canister call mqygn-kiaaa-aaaar-qaadq-cai get_minter_info '()' -n ic
```

The response includes `min_confirmations` (how many Bitcoin confirmations are required before minting, currently 6 on mainnet), `kyt_fee` (the know-your-transaction check fee charged per deposit, in satoshis), and `retrieve_btc_min_amount` (the minimum withdrawal amount, currently 50,000 satoshis).

**Step 3: Mint ckBTC**

Once the Bitcoin transaction has the required confirmations, call `update_balance` to trigger minting:

```bash
icp canister call mqygn-kiaaa-aaaar-qaadq-cai update_balance \
"(record { owner = opt principal \"$MY_PRINCIPAL\"; subaccount = null })" \
-n ic
```

Check ckBTC balance (amount in satoshis):
A `Minted` record in the response confirms that ckBTC was credited to your account. If the response is `Err(NoNewUtxos { current_confirmations = opt N })`, the transaction exists but has not yet reached the required count.

**Step 4: Check your balance**

```bash
icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_balance_of \
"(record { owner = principal \"$MY_PRINCIPAL\"; subaccount = null })" \
-n ic
```

Transfer ckBTC (10 satoshi fee, amount in satoshis):
**Step 5: Transfer ckBTC**

Set the recipient principal: `export RECIPIENT="<paste-recipient-principal>"`. The 10 satoshi fee is charged in addition to the `amount`.

```bash
export RECIPIENT="<paste-recipient-principal>"
icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \
"(record {
to = record { owner = principal \"$RECIPIENT\"; subaccount = null };
Expand All @@ -435,6 +454,8 @@ icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \
})" -n ic
```

`created_at_time = null` skips deduplication: if you run this command twice, both transfers execute. In production canister code, set this field to the current nanosecond timestamp so that retried calls are rejected as duplicates rather than sending twice. See [Transferring assets (ICRC-1)](../digital-assets/ledgers.md#transferring-assets-icrc-1) for details.

### Common mistakes

- **Not calling `update_balance` after a BTC deposit.** The minter does not auto-detect deposits. Your application must call `update_balance` to trigger minting.
Expand Down
Loading