> For the complete documentation index, see [llms.txt](https://docs.payram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payram.com/onboarding-guide/wallet-integration.md).

# Wallet Integration

***

## **Prerequisites**

Before you proceed with setting up your wallets, make sure the following steps are completed:

* Install [PayRam](/deployment-guide/quick-setup.md) and ensure it is fully set up on your server.
* Successfully [configure the Blockchain node](/onboarding-guide/node-details-configuration.md) where you plan to accept payments.

***

## Understanding some key terms

* Before configuring your wallets, it's essential to understand how the different wallet types work together in our payment system. This section explains the key components and their relationships
  * Master account
  * Deposit wallets
  * Cold wallet
  * Sweep contract

### <sub>Master account</sub>

* The master account is the merchant’s primary blockchain account that serves as the foundation for generating deposit wallet addresses. Every deposit wallet provided to customers for making payments is derived from this master account, ensuring all payment addresses remain linked to a single, consistent source. This setup allows the system to track, manage, and associate payments accurately under the merchant’s account
* In addition to generating deposit wallets, the master account is also used to deploy the sweep contract.

### Deposit wallets

* A deposit wallet is a blockchain address where customers send their payments. All deposit wallets are derived from the merchant’s master account and can exist on different supported blockchains. Each deposit wallet acts as a unique payment destination for a transaction or customer, while still being linked to the same master account for tracking and management purposes.

### Cold wallet

* A cold wallet is a secure blockchain wallet used for storing funds offline or in a highly secure environment. Unlike deposit wallets, which are generated for receiving payments from customers, the cold wallet serves as the merchant’s main storage address where funds are ultimately consolidated. Cold wallets are not directly exposed to customers, reducing the risk of unauthorized access and improving overall fund security.

{% hint style="info" %} <mark style="color:$primary;">**NOTE**</mark> <mark style="color:$info;">: While configuring wallets, make sure to use different wallets for the master account and the cold wallet. Do not use the same wallet for both; always configure separate ones.</mark>
{% endhint %}

***

## Configuring deposit wallets

{% hint style="warning" %} <mark style="color:$warning;">**Have your cold wallet address ready before you start.**</mark> <mark style="color:$info;">You are asked for it during setup, and you cannot accept payments on Ethereum, Base or Tron without one. You must control its private keys — PayRam never stores them. Use a different wallet from your master account.</mark>
{% endhint %}

{% stepper %}
{% step %}

### Choose a network

* Go to **Wallet management → Deposit wallet**, select **+ Set Up Deposit Wallet**, and pick the network.

<figure><img src="/files/7PDJv5xztH2oL1olRQYt" alt="Choosing a network"><figcaption></figcaption></figure>

* **EVM** covers Base, Ethereum and Polygon, and **Tron** follows the same steps below. **Bitcoin** differs — it derives addresses from a secret phrase instead of deploying a contract, so follow [Configuring a Bitcoin deposit wallet](#configuring-a-bitcoin-deposit-wallet) instead.
  {% endstep %}

{% step %}

### Choose the project

* Search for the project this wallet belongs to. Projects that already have a wallet on this network show **Wallet already present**; the rest show **Ready**.

<figure><img src="/files/HmAl437glw6RTYo40GXw" alt="Picking a project"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Connect your master wallet

* Name the wallet, then select **Connect wallet** and approve it in your browser wallet. The master wallet deploys the contract that generates a unique deposit address for every customer.

<figure><img src="/files/WKyvtonCbpP79VNUNGLV" alt="Setting up the master wallet"><figcaption></figcaption></figure>

{% hint style="warning" %} <mark style="color:$warning;">**Use the same master wallet for Base, Ethereum and Polygon.**</mark> <mark style="color:$info;">All three sit under one EVM deposit wallet, and your customers' deposit addresses are derived from the master account — sharing it means a customer keeps the same address on all three chains. Use a different one and they get different addresses per chain.</mark>

<mark style="color:$info;">If you already deployed on one of the three, PayRam names the exact address you must connect and will not let you continue until your browser wallet is switched to it.</mark>
{% endhint %}
{% endstep %}

{% step %}

### Add your cold wallet and deploy

* Enter the cold wallet address that swept funds go to, then select **Deploy contract** and confirm the transaction in your wallet.

<figure><img src="/files/HMFRGzF7vYYdW5qqDf4q" alt="Setting the cold wallet before deploying"><figcaption></figcaption></figure>

{% hint style="warning" %} <mark style="color:$warning;">**Before you deploy:**</mark> <mark style="color:$info;">the cold wallet must be different from the master wallet, and your master wallet needs native currency on that network — ETH for Ethereum and Base, POL for Polygon, TRX for Tron — because deploying is an on-chain transaction.</mark>
{% endhint %}
{% endstep %}

{% step %}

### Confirm it is ready

* PayRam generates a batch of deposit addresses, unassigned until customers arrive. Use **Create Test Payment Link** to verify the flow with a $1 payment.

<figure><img src="/files/eRCHnysR9eV5txh28IwS" alt="The deposit wallet is ready"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Repeat for each network

* Deploying covers one network at a time. The wallet list shows how many are live — **1/3 ready to accept payments** means only one EVM chain is deployed so far.

<figure><img src="/files/WSRjV04roWRoCvvuOSbD" alt="Deposit wallets and their per-network status"><figcaption></figcaption></figure>

* Run the same steps for the remaining networks under the same EVM deposit wallet, connecting that same master wallet each time.
  {% endstep %}
  {% endstepper %}

***

## Configuring a Bitcoin deposit wallet

Bitcoin has no contract to deploy. Deposit addresses are derived from a secret phrase you supply, so there is no master wallet and no on-chain transaction.

The first two steps are the same — **+ Set Up Deposit Wallet**, choose **Bitcoin**, then choose the project. After that:

{% stepper %}
{% step %}

### Enter your secret phrase

* Name the wallet, then enter the 12-word secret phrase your deposit addresses will be derived from.

<figure><img src="/files/GCr39OAirnmDfven7uq8" alt="Entering the Bitcoin secret phrase"><figcaption></figcaption></figure>

{% hint style="warning" %} <mark style="color:$warning;">**Store the phrase yourself.**</mark> <mark style="color:$info;">It is not saved by PayRam — it is used to generate the addresses and then discarded. You need the same phrase to sweep funds later, and losing it means losing access.</mark>
{% endhint %}

* Select **Save & Generate Addresses**.
  {% endstep %}

{% step %}

### Add a cold wallet (optional)

* Enter any BTC address you control as the destination for collected funds, or select **Skip** and add one later from the wallet details.

<figure><img src="/files/J3s7j2p6oCojjeBr5uM1" alt="Adding an optional Bitcoin cold wallet"><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: Unlike the EVM and Tron chains, Bitcoin funds are not swept automatically. You collect them manually with the PayRam Business App — see</mark> [<mark style="color:$info;">Bitcoin Funds Sweep Guide</mark>](/onboarding-guide/funds-sweeping/bitcoin-funds-sweep-guide.md)<mark style="color:$info;">.</mark>
{% endhint %}
{% endstep %}

{% step %}

### Confirm it is ready

* PayRam generates the deposit addresses, and the wallet is ready to accept Bitcoin payments.

<figure><img src="/files/1MZuPyIb63thFekzLItr" alt="The Bitcoin deposit wallet is ready"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

***

### Best practices

* Your mnemonic never leaves the browser — only derived public keys reach the server.
* Double-check your cold wallet address. Funds are swept there automatically.
* Start with one network, confirm everything works, then enable the rest.

***

You have set up your wallets and can start receiving payments. Next, [generate a test payment link](/onboarding-guide/testing-payment-links.md) to confirm the flow end to end.