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 a Circle Account, 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 multiple currencies. At this time we support USD Coin (USDC), Euro Coin (EUROC), Bitcoin (BTC), and Ethereum (ETH).
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.
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
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.
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.
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.
Updated 8 days ago