# Cross-chain token transfers

***

### **Prerequisites**

All steps of the are a prerequisite. In particular, make sure:

* You have created and deployed both subnets.
* The relayer for subnet 1 is running.
* You have exported the IPC address of user 1 and user 2 as `$IPC_ADDRESS_OF_USER_1` and  `$IPC_ADDRESS_OF_USER_2` , respectively (the `bitcoin-ipc` container exports them by default).

{% hint style="info" %}
Run all following commands from inside the `bitcoin-ipc` container, except if you used the Alternative deployment method.
{% endhint %}

{% hint style="success" %}
We have prepared this [technical video](https://www.youtube.com/watch?v=_ERk-rS0_Cg) which demonstrates cross-chain token transfers (it loosely follows the steps in this guide, and additionally shows how Bitcoin-IPC subnets can be connected to Metamask).
{% endhint %}

***

### Step 1: Set env variables for ease of use

* Create a env variable  `$SOURCE_SUBNET_ID` with the SubnetID of the **first** subnet.
* Create a env variable  `$TARGET_SUBNET_ID` with the SubnetID of the **second** subnet.

### Step 2: Transfer tokens between subnets

To transfer tokens from address `IPC_ADDRESS_OF_USER_1`  in subnet `SOURCE_SUBNET_ID` to address `IPC_ADDRESS_OF_USER_2`  in subnet `TARGET_SUBNET_ID`, we use the following command.

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash"># from inside the container
<strong>ipc-cli --config-path ~/.ipc/user1/config.toml cross-msg transfer --source-subnet $SOURCE_SUBNET_ID --destination-subnet $TARGET_SUBNET_ID --source-address $IPC_ADDRESS_OF_USER_1 --destination-address $IPC_ADDRESS_OF_USER_2 222200
</strong></code></pre>

The command returns the epoch in the source subnet in which the transfer was submitted.

{% hint style="warning" %}
**Caveat:**

Please make sure the sender has enough balance in the source subnet. If that's not the case, ipc-cli returns an error like "Actor balance less than needed".

Using the numbers in this demo, user 1 should have at 0.5 wBTC in subnet A — if you have performed additional release operations in the previous step you might have to perform an addition fund to user 1.
{% endhint %}

#### Check balance updates

The balance of user 1 one the source subnet is updated immediately. Observe the *balancer* script or run:

{% code overflow="wrap" %}

```bash
# from inside the container
ipc-cli wallet balances --subnet $SOURCE_SUBNET_ID --wallet-type btc | grep  $IPC_ADDRESS_OF_USER_1
```

{% endcode %}

For the target subnet, **wait until the next checkpoint is created and finalized in the source subnet** (parameter `--bottomup-check-period` of `ipc-cli subnet create` ). Then you can check the balances in the output of the *balancer* script or use:

{% code overflow="wrap" %}

```bash
# from inside the container
ipc-cli wallet balances --subnet $TARGET_SUBNET_ID --wallet-type btc | grep  $IPC_ADDRESS_OF_USER_2
```

{% endcode %}

{% hint style="success" %}

#### **Implementation details for the transfer**

1. ipc-cli submits a transfer transaction to the source subnet.
2. When finalized in the source subnet, the transaction appears in a checkpoint message. You can see these messages using the `list-bottomup-bundle` command (described earlier) for subnet `SOURCE_SUBNET_ID`.&#x20;
3. The relayer submits the checkpoint message to bitcoin.
4. The bitcoin monitor parses the checkpoint message, once it becomes finalized on the bitcoin network. You can look at the output of any bitcoin monitor. You should see that it picked up the checkpoint transaction (keyoword `IpcCheckpointSubnetMsg`) containing a transfer (`IpcCrossSubnetTransfer`) , followed by a second bitcoin transaction (keyword `IpcBatchTransferMsg`).
5. When validators of subnet `TARGET_SUBNET_ID` ask its parent subnet (bitcoin) for new top-down messages, the monitor will return the transfer transaction. You can see these transactions using the `list-topdown-msgs` command (described earlier) for subnet `TARGET_SUBNET_ID`.&#x20;

{% endhint %}

You can also test the opposite direction, sending funds from subnet B to subnet A. The command is analogous to the one above. However, make sure you **run a relayer for subnet B** first.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bitcoin-scaling-labs-docs.gitbook.io/ipc-btc-scaling-docs/user-guide-for-using-subnets/publish-your-docs-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.