Skip to main content
Circle APIs are a set of functions and procedures that allow you to use USDC for payments, payouts, and transfers. Circle’s APIs are built around several resources that represent payments, payouts, transfers, and their associated objects.

​
Primary resources

​
Payout object

A payout object represents a payout to a customer, vendor, or supplier.

​
Example

JSON
{
  "id": "df3b8e5f-9579-4c1f-9fa9-deac7f4be55c",
  "sourceWalletId": "1000038499",
  "destination": {
    "id": "4d260293-d17c-4309-a8da-fa7850f95c10",
    "type": "address_book",
  },
  "amount": {
    "amount": "10.0",
    "currency": "USD"
  },
  "fees": {
    "amount": 3.0,
    "currency": "USD"
  },
  "status": "complete",
  "errorCode": "insufficient_funds",
  "riskEvaluation": {
    "decision": "denied",
    "reason": "3000"
  },
  "return": { ... },
  "createDate": "2020-12-24T11:19:20.561Z",
  "updateDate": "2020-12-24T12:01:00.523Z",

}

​
Attributes

id string
A UUID for the payout.
sourceWalletId string
The identifier of the source wallet used to fund a payout.
destination object
The Destination object the payout is being made to.
amount object
A Money object representing the total amount that is paid to the destination.
toAmount object
A Money object representing the amount that is paid to the destination currency. Only included for crypto payouts.
fees object
A Money object representing fees associated with this payment.
status string
Status of the payout. pending indicates that the payout is in process; complete indicates it finished successfully; failed indicates it failed.
externalRef string
External network identifier which will be present once provided from the applicable network.
errorCode string
Indicates the failure reason of a payout. Only present for payouts in failed state. Possible values are insufficient_funds, transaction_denied, transaction_failed, and transaction_returned.
riskEvaluation object
An object with two attributes, decision and reason.
return object
A Return object if the payout was returned.
createDate string
ISO-8601 UTC date/time format.
updateDate string
ISO-8601 UTC date/time format.

​
Transfer object

A transfer object represents a transfer of funds from a Circle wallet to a blockchain address, from a blockchain address to a Circle wallet, or between two Circle wallets.

​
Example

JSON
{
  "id": "0d46b642-3a5f-4071-a747-4053b7df2f99",
  "source": {
    "type": "blockchain",
    "chain": "ETH",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
  },
  "destination": {
    "type": "wallet",
    "id": "12345"
  },
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63",
  "status": "pending",
  "riskEvaluation": {
    "decision": "approved",
    "reason": "1234"
  },
  "createDate": "2020-04-10T02:29:53.888Z"
}

​
Attributes

id string
A UUID for the transfer.
source object
A Source object representing the source of the transfer.
destination object
A Destination object representing the destination of the transfer.
amount object
A Money object representing the amount transferred between source and destination.
transactionHash string
A hash that uniquely identifies an onchain transaction. This is only available when either source or destination are of type blockchain.
status string
Status of the transfer. Status pending indicates that the transfer is in the process of running; complete indicates it finished successfully; failed indicates it failed.
createDate string
ISO-8601 UTC date/time format.

​
Nested resources

The following are resources that are commonly used in other objects.

​
Source and destination objects

Payments, payouts, and transfers reference source and destination objects, which as the names suggest, tell you where the funds are coming from and where they’re going. Sources and destinations can have the following types:
  • wire for wire payments and payouts
  • blockchain for transfers to/from blockchain addresses
  • wallet for transfers to/from a Circle wallet
JSON
// "blockchain"
// A "chain" and "address" together represent the blockchain location.
{
  "type": "blockchain",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "chain": "ETH"
}

// "wallet"
// The "id" is the id of the Circle wallet.
{
  "type": "wallet",
  "id": "12345"
}

​
Money object

Monetary amounts across Circle APIs are represented as money objects, which consist of an amount and a currency. Two currencies are supported, USD and EUR, with the amount represented as a string containing the whole units and two decimals. In the example below, the amount is represented as 3.14 and the currency as USD.
JSON
{
  "amount": "3.14",
  "currency": "USD"
}

​
Blockchain addresses

JSON
{
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "currency": "USD",
  "chain": "ETH"
}
⌘I