Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets into your product or service, or power your internet marketplace.

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 a Circle Business 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 - however currently only USD is supported.

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 generate 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.

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 Circle Wallets 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.

Updated about a month ago



Wallets, Addresses and Transfers


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.