Skip to main content
Send USDC from your Managed Payments account to an onchain recipient. You add the recipient’s blockchain address to your address book, confirm that the entry is active, create a payout from a subaccount or the main wallet, and confirm that the payout completes. For how recipients and payouts progress, see Stablecoin payin and payout lifecycle.

Prerequisites

Before you begin, ensure that you’ve:
  • Completed Managed Payments onboarding and obtained API keys for the environment you use. The examples use the sandbox host api-sandbox.circle.com.
  • (Optional) Set up a webhook endpoint for address book and payout events. See Set up a webhook endpoint.

Step 1: Create an address book recipient

Outbound sends use destinations in your address book. Create a recipient with create an address book recipient.
Circle Singapore (CIRCLE_SG) entities must include beneficiary identity and ownership on create. For a hosted (custodial) beneficiary, add:
Obtain vaspId from list address book VASPs (GET /v1/addressBook/vasps). For a self-hosted beneficiary, set ownership.custody.type to self_hosted (omit vaspId) and provide the nested PII object matching identity.type for Travel Rule compliance. See create an address book recipient for the full SG schema.Circle LLC (United States) entities register a recipient with just chain and address; the VASP directory and vaspId don’t apply and aren’t available.
Don’t create a payout until the recipient is active. The status you get when you create a recipient depends on your setup. For example, a new entry stays inactive for 24 hours by default (see the following warning).
Plan for a 24-hour hold on new payout addresses. A new recipient moves from pending to inactive and stays there for 24 hours. You can’t pay it until it becomes active. Register recipients well before go-live so the hold doesn’t delay your first payouts. The hold comes from the Delayed Withdrawals setting, which is on by default. If you turn it off, the change takes effect only after a 48-hour lockout.The hold protects your account from unauthorized changes. To check the setting, open the Circle hub (sandbox: hub-sandbox.circle.com) and go to Settings > Security > Delayed Withdrawals. Keep it on unless your security team approves a different setup.
The response returns the new recipient’s id, which you use as the payout destination. In this example, status is pending:
Response

Step 2: Confirm the recipient is active

You can’t pay an inactive recipient. Use webhooks to learn when a recipient becomes active, or check its status right before you create a payout.
Use webhooks for production. After you subscribe, you get a notification whenever a recipient’s status changes. When the recipient activates, you receive a notification with status set to active:
Address book recipient webhook notification

Step 3: Create a payout

Create the payout with create a payout. Set destination to the address book entry. Set amount and optional toAmount. Set source when you use a subaccount. If you omit source, the API withdraws from the main wallet.
Receiving currency and Travel Rule: If you omit toAmount.currency, the API uses amount.currency as the receiving currency.The source.identities object is required for payouts greater than or equal to $3,000. The object describes the originator (your organization), not the recipient, for Financial Crimes Enforcement Network (FinCEN) Travel Rule compliance.Enforcement depends on account configuration. purposeOfTransfer is also required on Circle Singapore (CIRCLE_SG), Circle SAS (CIRCLE_FR), and some Circle LLC (United States) payouts. Use a PMT code from PMT000 to PMT030 except PMT006. See payment reason codes.
For Managed Payments, source.useMainWalletFunding defaults to true. When it’s true, the API tops up from the main wallet if the source wallet lacks funds. Set source.useMainWalletFunding to false to require the full amount on the source wallet only.
Insufficient funds: If a payout fails because funds are not ready yet, confirm your wire completed and USDC is available for the source wallet. See the Wires API and Settlement flows.
The example uses a subaccount as source, sets useMainWalletFunding on source, and uses an amount that needs identities for Travel Rule coverage. Replace placeholder IDs with your own values.
The response returns the payout id with status set to pending:
Response

Step 4: Confirm the payout completed

Use webhooks or polling with get a payout to confirm the payout finished onchain. The payout is done when status is complete.
Use webhooks for production. When the payout completes, you receive a mint.payout notification with the final amounts and fees:
Payout webhook notification