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.Additional requirements for Circle Singapore (CIRCLE_SG) entities
Additional requirements for Circle Singapore (CIRCLE_SG) entities
Circle Singapore (Obtain
CIRCLE_SG) entities must include beneficiary identity
and ownership on create. For a hosted (custodial) beneficiary, add: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.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).
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 becomesactive, or check its status right before you create a payout.
- Webhook
- Polling
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. Setdestination 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.
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.
source, sets useMainWalletFunding on
source, and uses an amount that needs identities for Travel Rule coverage.
Replace placeholder IDs with your own values.
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 whenstatus is
complete.
- Webhook
- Polling
Use webhooks for production. When the payout completes, you receive a
mint.payout notification with the final amounts and fees:Payout webhook notification