Wallets, Addresses and Transfers

Wallets

A wallet is the fundamental store of funds across the Circle platform. Think of wallets like bank accounts. We often refer to wallets on the Circle platform as "hosted wallets".

When you signup for Circle Mint, you automatically get a master wallet (which you can query using the get configuration endpoint). You can subsequently create as many additional wallets as you wish using the create wallet endpoint.

Wallets have balances. Each wallet hosted with Circle can hold balances in any of our supported chains. See supported chains and currencies for more detail.

Wallets are the destination for settlement of payments processed via the Payments API. You are able to transfer funds across hosted wallets. You are also able send funds from a wallet to external blockchain destinations. Similarly, you can have a wallet receive funds from external blockchain sources.

Wallet Addresses

An address is an identifier on a given blockchain that can be used to receive cryptocurrency funds. It is typically a string of alphanumeric characters, such as 0x8381470ED67C3802402dbbFa0058E8871F017A6F.

Since the wallets you control are capable of receiving funds from external blockchain sources, you are able to generate an address for your wallets by using the create address endpoint. Blockchain transfers to that address will eventually credit your wallet balance (read more about confirmations here).

Different blockchains, like Bitcoin and Ethereum, have different address formats. For technical reasons, it may not be possible to receive all tokens that exist on a given blockchain using the same address.

As a result, when you generate a new address for one of your wallets using the Wallets API you will specify both the chain and the currency you wish to receive using that address.

You may generate as many addresses as you wish for a given wallet by using the create address endpoint.

🚧

When communicating one of your wallet addresses to an external party, it is extremely important to preserve the exact format and capitalization of the address. Otherwise funds transferred by the external party may end up somewhere else.

🚧

Addresses generated for your master wallet using the Accounts API may appear within the Circle Mint dashboard’s deposit flow. If you are using addresses appended to your master wallet for third party deposits, it is extremely important to embed logic to avoid misdirecting funds.

❗️

It is extremely important to ensure that only the appropriate currency on the appropriate chain gets sent to your wallet addresses. Otherwise transferred funds may be permanently lost.

Wallet Transfers

A wallet transfer is an operation that transfers funds (a) from an external blockchain address to a Circle hosted wallet, (b) between two Circle hosted wallets, or (c) from a Circle hosted wallet to an external blockchain address.

Wallet transfers are the main mechanism for moving money in the Accounts API. You can create wallet transfers by using the create transfer endpoint.

📘

When you transfer external funds to an address associated with a Circle hosted wallet and the wallet is successfully credited, Circle's platform may subsequently move the underlying cryptocurrency to another address. This is normal behavior and your wallet maintains the proper balance irrespective of any such moves. You cannot accurately determine the balance of a Circle hosted wallet by inspecting its blockchain addresses. Instead, you must use the Circle API.

Wallet transfers between two wallets are instantaneous and free. Wallet transfers from a wallet to an external blockchain address will take some time while the blockchain processes your transaction, and may incur fees in the future.

❗️

Use supported chains and currencies only

Transferring unsupported currencies using the Accounts API may result in a permanent loss of funds. You can verify the token contract details for supported currencies here.