In production, all new addresses are marked inactive for the first 24 hours and therefore blocked for payout until that time period has passed. If you would like to override this rule, please work with your customer service representative.
The Crypto Payouts API allows you to send USDC and EURC. To use the Crypto Payouts functionality, the recipient blockchain address needs to be added into the Address Book directory before using that address to perform an onchain send.
In this quickstart you will create a recipient, ensure the recipient is active, payout the recipient, and check that the funds have successfully been sent to the recipient. The interaction model with Circle APIs is similar to other fiat payouts methods.
Let’s first create a recipient to send funds to.
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": "[email protected]",
"bns": "testbns",
"nickname": "test nickname desc"
}
}'
{
"data": {
"id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
"chain": "ETH",
"address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
"metadata": {
"nickname": "test nickname desc",
"email": "[email protected]",
"bns": "testbns"
},
"status": "pending",
"updateDate": "2022-09-22T14:16:34.985353Z",
"createDate": "2022-09-22T14:16:34.985353Z"
}
}
Prior to sending the payout you must ensure the recipient status is marked active.
In production, all new addresses are marked inactive for the first 24 hours and therefore blocked for payout until that time period has passed. If you would like to override this rule, please work with your customer service representative.
If you have configured webhook notifications you will receive a recipient
notification for each status update. In this case you will look for the
“status”: “active”
.
{
"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": "[email protected]",
"bns": "testbns"
},
"status": "active",
"updateDate": "2022-09-22T14:16:34.985353Z",
"createDate": "2022-09-22T14:16:34.985353Z"
}
}
Poll the GET endpoint until the “status”: “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'
{
"data": {
"id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
"chain": "ETH",
"address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
"metadata": {
"nickname": "test nickname desc",
"email": "[email protected]",
"bns": "testbns"
},
"status": "active",
"updateDate": "2022-09-22T14:16:34.985353Z",
"createDate": "2022-09-22T14:16:34.985353Z"
}
}
Once you have successfully created a recipient, you will create a payout providing the recipient’s ID (address ID), originating funds (currency + amount) and the currency the recipient would like to receive.
If toAmount.currency
is not provided, amount.currency
is used as receiving currency.
The source.identities
object is required for payouts >= $3,000. The object
refers to the organization sending the funds, not the recipient. This is to
ensure compliance with the FINCEN Travel Rule. For more information see the
Travel Rule On-Chain section.
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",
"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"
}
}'
{
"data": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"sourceWalletId": "12345",
"destination": {
"type": "address_book",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"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"
}
}
Last step, ensure the funds were sent and delivered on chain to the recipient.
If you have configured webhook notifications you will receive a notification for each status update.
{
"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": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": {
"amount": "3000.14",
"currency": "USD"
},
"toAmount": {
"amount": "2.318536607984667",
"currency": "ETH"
},
"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"
}
}
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'
{
"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"
}
}