Quickstart: Send stablecoin payouts

This guide shows how to send a stablecoin payout with Managed Payments. You add a blockchain recipient to your address book. You wait until the recipient is active. You create a payout from a sub-account or the main wallet. You confirm that the payout completes.

Prerequisites

Before you start, ensure you have:

Managed Payments onboarding done and API keys for the environment you use. This guide uses the sandbox host api-sandbox.circle.com.
Roles for address book and stablecoin payouts for your setup. Circle sets roles when you onboard.
A sub-account wallet ID for source when you don’t pay from the main wallet alone. Read Managed Payments and Sub-account architecture.
(Optional) A webhook endpoint for address book and payout events. See Set up a webhook endpoint.

Sequence diagram

Steps

Create an address book recipient
Wait until the recipient is active
Create a payout
Confirm the payout completed

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

Circle Singapore (CIRCLE_SG) entities must include beneficiary identity and ownership on create. For a hosted (custodial) beneficiary, add:

{
  "identity": {
    "type": "individual",
    "firstName": "Ada",
    "lastName": "Lovelace"
  },
  "ownership": {
    "type": "third_party",
    "custody": {
      "type": "hosted",
      "vaspId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

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, delayed withdrawals can keep a new entry inactive until it activates (see the following note).

Delayed withdrawals are off by default for Managed Payments. You can’t turn them on or off yourself; contact Circle customer support if your setup needs a different configuration. When delayed withdrawals are on, new address book entries start inactive. Wait until they’re active before you pay.

curl --location --request POST 'https://api-sandbox.circle.com/v1/addressBook/recipients' \
--header 'Accept: application/json' \
--header 'X-Request-Id: fb7980ad-fd01-468b-98ff-2d9ecff67f86' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "9352ec9e-5ee6-441f-ab42-186bc71fbdde",
  "chain": "ETH",
  "address": "0x65BFCf1a6289a0b77b4D3F7d12005a05949FD8C3",
  "metadata": {
    "email": "satoshi@circle.com",
    "bns": "testbns",
    "nickname": "test nickname desc"
  }
}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import {
  AddressBookRecipientRequest,
  Chain,
  Circle,
  CircleEnvironments,
} from "@circle-fin/circle-sdk";
import crypto from "crypto";

const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

async function createAddressBookRecipient(): Promise<void> {
  const reqBody: AddressBookRecipientRequest = {
    idempotencyKey: crypto.randomUUID(),
    chain: Chain.Eth,
    address: "0x65BFCf1a6289a0b77b4D3F7d12005a05949FD8C3",
    metadata: {
      email: "satoshi@circle.com",
      bns: "testbns",
      nickname: "test nickname desc",
    },
  };
  const resp =
    await circle.cryptoAddressBook.createAddressBookRecipient(reqBody);
  console.log(resp.data);
}

void createAddressBookRecipient();

Response

{
  "data": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "pending",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}

2. Wait until the recipient is active

You cannot pay an inactive recipient. Use webhooks or polling until status is active.

Option 1: Webhook notification

After you subscribe, you get updates when address book recipients change. This sample shows an active recipient.

Address book recipient webhook notification

{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "addressBookRecipient": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "active",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}

Option 2: Poll the recipient

Call get an address book recipient until data.status is active.

curl --location --request GET 'https://api-sandbox.circle.com/v1/addressBook/recipients/dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe' \
--header 'Accept: application/json' \
--header 'X-Request-Id: 55990729-c59f-4cda-9edd-838cefaa1e42' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

function delay(ms: number): Promise<void> {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

async function pollRecipientActive(recipientId: string): Promise<void> {
  const pollIntervalMs = 500;
  while (true) {
    const resp =
      await circle.cryptoAddressBook.getAddressBookRecipient(recipientId);
    const status = resp.data?.data?.status;
    if (status === "active") {
      console.log(resp.data);
      return;
    }
    await delay(pollIntervalMs);
  }
}

void pollRecipientActive("dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe");

Response

{
  "data": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "active",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}

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 sub-account. 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.Circle Singapore (CIRCLE_SG) purpose of transfer: These entities must set purposeOfTransfer on the payout using a code from the payment reason codes reference.

Main wallet funding: For Managed Payments, source.useMainWalletFunding defaults to true. When it is 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 sub-account as source, sets useMainWalletFunding on source, and uses an amount that needs identities for Travel Rule coverage. Replace placeholder IDs with your own values.

curl --location --request POST 'https://api-sandbox.circle.com/v1/payouts' \
--header 'Accept: application/json' \
--header 'X-Request-Id: ff422eab-52fa-4a6e-bf07-b6b522786468' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "source": {
    "type": "wallet",
    "id": "12345",
    "useMainWalletFunding": true,
    "identities": [
      {
        "type": "individual",
        "name": "Satoshi Nakamoto",
        "addresses": [
          {
            "line1": "100 Money Street",
            "line2": "Suite 1",
            "city": "Boston",
            "district": "MA",
            "postalCode": "01234",
            "country": "US"
          }
        ]
      }
    ]
  },
  "destination": {
    "type": "address_book",
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
  },
  "amount": {
    "amount": "3000.14",
    "currency": "USD"
  },
  "toAmount": {
    "currency": "USD"
  }
}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import {
  Circle,
  CircleEnvironments,
  CryptoPayoutCreationRequest,
  CryptoPayoutDestinationType,
  IdentityTypeEnum,
  MoneyCurrencyEnum,
  ToAmountCurrencyEnum,
  TransferSourceWalletLocationTypeEnum,
} from "@circle-fin/circle-sdk";
import crypto from "crypto";

/** Managed Payments: `useMainWalletFunding` on `source` (SDK types may lag the API). */
type PayoutSourceWallet = NonNullable<CryptoPayoutCreationRequest["source"]> & {
  useMainWalletFunding?: boolean;
};

const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

async function createManagedPaymentsPayout(): Promise<void> {
  const sourceWallet: PayoutSourceWallet = {
    type: TransferSourceWalletLocationTypeEnum.Wallet,
    id: "12345",
    useMainWalletFunding: true,
    identities: [
      {
        type: IdentityTypeEnum.Individual,
        name: "Satoshi Nakamoto",
        addresses: [
          {
            line1: "100 Money Street",
            line2: "Suite 1",
            city: "Boston",
            district: "MA",
            postalCode: "01234",
            country: "US",
          },
        ],
      },
    ],
  };

  const reqBody: CryptoPayoutCreationRequest = {
    idempotencyKey: crypto.randomUUID(),
    source: sourceWallet,
    destination: {
      type: CryptoPayoutDestinationType.AddressBook,
      id: "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    },
    amount: {
      amount: "3000.14",
      currency: MoneyCurrencyEnum.Usd,
    },
    toAmount: {
      currency: ToAmountCurrencyEnum.Usd,
    },
  };

  const resp = await circle.payouts.createPayout(reqBody);
  console.log(resp.data);
}

void createManagedPaymentsPayout();

Response

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "currency": "USD"
    },
    "status": "pending",
    "updateDate": "2020-04-10T02:13:30.000Z",
    "createDate": "2020-04-10T02:13:30.000Z"
  }
}

4. Confirm the payout completed

Use webhooks or polling with get a payout to confirm the payout finished onchain.

Option 1: Webhook notification

Payout webhook notification

{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payout",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "payout": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.00",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "0.30",
      "currency": "USD"
    },
    "status": "complete",
    "createDate": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z"
  }
}

Option 2: Poll the payout

curl --location --request GET 'https://api-sandbox.circle.com/v1/payouts/b8627ae8-732b-4d25-b947-1df8f4007a29' \
--header 'Accept: application/json' \
--header 'X-Request-Id: d36f3c00-9c98-4610-bfea-83995379995e' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

function delay(ms: number): Promise<void> {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

async function pollPayoutComplete(payoutId: string): Promise<void> {
  const pollIntervalMs = 500;
  while (true) {
    const resp = await circle.payouts.getPayout(payoutId);
    const status = resp.data?.data?.status;
    if (status === "complete") {
      console.log(resp.data);
      return;
    }
    await delay(pollIntervalMs);
  }
}

void pollPayoutComplete("b8627ae8-732b-4d25-b947-1df8f4007a29");

Response

{
  "data": {
    "id": "2f3bca9a-2d0e-4aef-a511-026eefd3cc6f",
    "destination": {
      "type": "address_book",
      "id": "eaca84eb-69fb-53d3-9dac-f69cb5f1541a"
    },
    "amount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "externalRef": "0x41f8f2cd555e247716f3e9bc97366ac04a848fd2fde76732c894c6843fc6f8db",
    "createDate": "2023-08-14T20:30:19.145913Z",
    "updateDate": "2023-08-14T22:05:55.406292Z",
    "sourceWalletId": "1000594146",
    "fees": {
      "amount": "1.00",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "0.01",
      "currency": "USD"
    },
    "status": "complete"
  }
}

Fiat payouts

Managed Payments

Stablecoin payments

Quickstart: Send stablecoin payouts

Prerequisites

Sequence diagram

Steps

1. Create an address book recipient

2. Wait until the recipient is active

Option 1: Webhook notification

Option 2: Poll the recipient

3. Create a payout

4. Confirm the payout completed

Option 1: Webhook notification

Option 2: Poll the payout

​Prerequisites

​Sequence diagram

​Steps

​1. Create an address book recipient

​2. Wait until the recipient is active

​Option 1: Webhook notification

​Option 2: Poll the recipient

​3. Create a payout

​4. Confirm the payout completed

​Option 1: Webhook notification

​Option 2: Poll the payout

Prerequisites

Sequence diagram

Steps

1. Create an address book recipient

2. Wait until the recipient is active

Option 1: Webhook notification

Option 2: Poll the recipient

3. Create a payout

4. Confirm the payout completed

Option 1: Webhook notification

Option 2: Poll the payout