Quickstart: Send stablecoin payouts

Send USDC from your Managed Payments account to an onchain recipient. You add the recipient’s blockchain address to your address book, wait for the entry to become 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.

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();

The response returns the new recipient’s id, which you use as the payout destination. In this example, status is pending:

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"
  }
}

Step 2: Wait until the recipient is active

You can’t pay an inactive recipient. Use webhooks or polling to confirm that status is active.

Webhook
Polling

After you subscribe, you get updates when address book recipients change. When the recipient activates, you receive a notification with status set to active:

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"
  }
}

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");

The recipient is ready when status is active:

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"
  }
}

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.

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"
  },
  "purposeOfTransfer": "PMT001"
}'

/**
 * 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,
    },
    purposeOfTransfer: "PMT001",
  };

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

void createManagedPaymentsPayout();

The response returns the payout id with status set to pending:

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"
  }
}

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.

Webhook
Polling

When the payout completes, you receive a payout notification with the final amounts and fees:

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"
  }
}

Poll the payout until status is complete:

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": "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"
    },
    "externalRef": "0x41f8f2cd555e247716f3e9bc97366ac04a848fd2fde76732c894c6843fc6f8db",
    "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"
  }
}

Fiat payouts

Managed Payments

Stablecoin payments

Quickstart: Send stablecoin payouts

Prerequisites

Step 1: Create an address book recipient

Step 2: Wait until the recipient is active

Step 3: Create a payout

Step 4: Confirm the payout completed

​Prerequisites

​Step 1: Create an address book recipient

​Step 2: Wait until the recipient is active

​Step 3: Create a payout

​Step 4: Confirm the payout completed

Prerequisites

Step 1: Create an address book recipient

Step 2: Wait until the recipient is active

Step 3: Create a payout

Step 4: Confirm the payout completed