The Crypto Payouts API allows you to send USDC, EURC, BTC, ETH and MATIC (on Polygon). The API will also come with an embedded exchange functionality for converting to and from USDC. If you are not performing an exchange you can directly send the currency in custody (e.g. ETH in custody can be paid out in ETH without exchanges). If you are looking for exchanges, below are the source and destination currencies and the destination chain we support.

Source	Destination	Chain
BTC	USDC	ALGO, AVAX, ETH , FLOW, HBAR, MATIC, SOL, TRX, XLM
USDC	BTC	BTC
ETH	USDC	ALGO, AVAX, ETH , FLOW, HBAR, MATIC, SOL, TRX, XLM
USDC	ETH	ETH
MATIC	USDC	ALGO, AVAX, ETH , FLOW, HBAR, MATIC, SOL, TRX, XLM
USDC	MATIC	MATIC

👍
Exchange without custody of tokens
With Exchanges, customers need not hold the custody of native tokens (E.g. MATIC) and instead do a real-time conversion of USDC in the source wallet to MATIC while paying out.

📘
GET exchange rate quote
Circle also provides a tentative exchange rate in real time for the specific trading pairs.

🚧
Limits

Crypto Payouts has a transactional limit of $25,000 and daily limit of $250,000 (limits are calculated in USD irrespective of the currency chosen). Please work with your customer representative for custom limits.

Circle's exchange functionality is limited to U.S. and Canadian customers.

To use the Crypto Payouts functionality, the recipient blockchain address needs to be added into the Address Book directory using, before using the address to do an on-chain send.

Quickstart

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 very similar to other fiat payouts methods.

1. Create recipient in address book

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

2. Check recipient status

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.

Option 1: Webhook Notifications

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

Option 2: Polling

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

3. Payout recipient

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 the amount.currency will be used as receiving currency.

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": "ETH"
  }
}'

{  
 "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": "ETH"  
   },  
   "status": "pending",  
   "updateDate": "2020-04-10T02:13:30.000Z",  
   "createDate": "2020-04-10T02:13:30.000Z"  
 }  
}

4. Check payout status

Last step, ensure the funds were sent and delivered on chain to the recipient.

Option 1: Webhook Notifications

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

Option 2: Polling

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