API Resources & Objects

Circle's Programmable Wallets APIs are built around several resources representing transactions, challenges, and associated objects.

Primary Resources

Transactions Object

A transactions object represents an on-chain action, such as receiving a blockchain transfer, sending a blockchain transfer, or executing/deploying a smart contract.

Example Transaction Object:

{
     "id": "f274b4b3-05c5-5a82-91e0-972def7ed6a9",
     "blockchain": "ETH",
     "tokenId": "b18e71aa-c9a9-5f58-a02c-21b2f9e349e1",
     "walletId": "0188df2c-bded-7c12-8c96-e71ce22af10d",
		 "refId": "35550ef8-335f-46d1-8332-2436e92b5702",
     "sourceAddress": "0x62b86f126249a23df418d7ceee43d3316cd68392",
     "destinationAddress": "0x36986c392d57ceb3a7a901642b2e9cf9a8021c76",
     "transactionType": "OUTBOUND",
     "custodyType": "ENDUSER",
     "state": "COMPLETED",
     "amounts": [
         "0.001"
     ],
     "nfts": null,
     "txHash": "0xc190b62b48519e7e8f2834aa0cc44c5a6051f74404fac64d1ff01ca142585719",
     "blockHash": "0xaf0f18a19da7f18b197757d8cac086f64870708459102a616ca015afd5fd0942",
     "blockHeight": 9267444,
     "networkFee": "0.000021000000294",
     "firstConfirmDate": "2023-06-30T17:45:48Z",
     "operation": "TRANSFER",
     "userId": "5e32593e-1a94-4928-aae4-d5793ec938e9",
     "abiParameters": null,
     "createDate": "2023-06-30T17:45:35Z",
     "updateDate": "2023-06-30T17:46:58Z"
}

Transaction Attributes

Field	Type	Description
id	uuid	The unique transaction id.
blockchain	Blockchain	The blockchain is associated with the transaction. For more information, refer to Supported Blockchains and Currencies.
userId	String	The unique id of the user associated with this transaction.
tokenId	uuid	The id is associated with the specific token used in this transaction.
walletId	uuid	The unique id of the wallet associated with this transaction.
sourceAddress	String	The blockchain address represents the source of the transaction.
destinationAddress	String	The blockchain address represents the destination address of the transaction.
transactionType	String	The type of transaction. Possible values: `inbound, outbound`.
custodyType	String	The type of custody for the associated wallet. Possible values: `enduser, developer`.
state	String	The status of the transaction. Possible values: `initiated, queued, sent, confirmed, completed, canceled, failed`.
amounts	Array [String]	The amount transferred from the source to the destination. The amount value will be relative to the token associated with the transaction.
nfts	object	An Nft object represents the characteristics of any NFTs associated with the transaction.
errorReason	String-	Indicates the failure reason for a transaction. Only present for transactions in a failed state. See API Errors for a list of possible codes.
createDate	String	The time that the transaction request was submitted in ISO-8601 UTC date/time format.
updateDate	String	The time of the last update date in ISO-8601 UTC date/time format.

Challenge Object

A challenge object represents the different types and statuses of a user challenge.

Example Challenge Object:

{
    "challenges": {
    "id": "decdab5e-663a-5a3d-b586-96e83132ecfd",
    "type": "CREATE_TRANSACTION",
    "status": "COMPLETE",
    "correlationIds": [
       "42349f28-75e5-5a4e-8bfc-0fe958a6f973"
    ]
}

Challenge Attributes


id	uuid	The unique challenge id.
userId	String	The unique id of the user associated with this transaction.
type	String	The type of end-user operation that the challenge represents. Each of these operations requires an approval and pin entry from the end user. Possible values: `set_pin, restore_pin, change_pin, set_security_questions, create_wallet, create_transaction, accelerate_transaction, cancel_transaction, contract_execution`.
status	String	The status of the challenge. Possible values: pending, in_progress, complete, failed, expired.
correlationIds	Array[String]	If the challenge status is `complete`, the value will be the following for different challenge types (see rows below):
		`set_pin, restore_pin, change_pin, set_security_questions` -> null
		`create_wallet` -> The id of the wallet that was created.
		`create_transaction, accelerate_transaction, cancel_transaction` -> The id of the transaction that was created.
errorCode	int	Indicates the failure reason for a challenge. Only present for challenges in a `failed` state.
errorMessage	String	Indicates the failure reason for a challenge. Only present for challenges in a `failed` state.

User Object

A user object represents the different status and id of a user.

Example User Object:

{
     "id": "5e32593e-1a94-4928-aae4-d5793ec938e9",
     "status": "ENABLED",
     "createDate": "2023-06-21T18:14:13Z",
     "pin": {
        "status": "ENABLED",
        "securityQuestionStatus": "ENABLED",
        "failedAttempts": 0,
        "failedAnswerAttempts": 0
     }
}

User Attributes


id	uuid	The unique user id.
status	String	The current status of this user. Possible values: `enabled, disabled`.
createDate	time.Time	The time that the user was created in ISO-8601 UTC date/time format.

Wallet Object

A wallet object represents the different information around an end user's wallet(s)

Example Wallet Object:

{
     "id": "0188df2c-bded-71ff-8710-40e521ac3e26",
     "state": "LIVE",
     "walletSetId": "0188df2c-bdd8-7e79-b9f1-bede953d9bd6",
     "custodyType": "ENDUSER",
     "userId": "5e32593e-1a94-4928-aae4-d5793ec938e9",
     "address": "0x62b86f126249a23df418d7ceee43d3316cd68392",
     "addressIndex": 0,
     "blockchain": "MATIC",
     "updateDate": "2023-06-21T18:17:11Z",
     "createDate": "2023-06-21T18:17:11Z"
}

Wallet Attributes


id	uuid	The unique wallet id.
state	String	The current state of the associated wallet. Possible values: `live, frozen`.
walletSetId	uuid	The unique id of the WalletSet that this wallet belongs to.
custodyType	String	The type of custody for the associated wallet. Possible values: `enduser, developer`.
userId	String	The unique id user id for the associated user.
refId	String	Optional ref id input for the associated wallet.
name	String	Optional name input for the associated wallet.
address	String	The blockchain address for the associated wallet.
addressIndex	Integer	The index associated with the associated blockchain address
blockchain	String	The blockchain is associated with the transaction. For more information, refer to Supported Blockchains and Currencies.
createDate	String	The time that the transaction request was submitted in ISO-8601 UTC date/time format.
updateDate	String	The time of the last update date in ISO-8601 UTC date/time format.

Token Object

A token object represents the different information around any token held within wallets.

Example Token Object:

{
     "id": "ea6cd9a4-3c5e-5a41-9f8c-a7f858286043",
     "blockchain": "ETH",
     "tokenAddress": "0x07865c6e87b9f70255377e024ace6630c1eaa37f",
     "standard": "ERC20",
     "name": "USD Coin",
     "symbol": "USDC",
     "decimals": 6,
     "isNative": false,
     "updateDate": "2023-05-03T05:25:19Z",
     "createDate": "2023-05-03T05:25:19Z"
}

Token Attributes


id	uuid	The unique token id.
blockchain	String	The blockchain is associated with the transaction. Possible values, i.e. supported blockchains, can be found here.
IsNative	bool	Whether the specified token is the native token for the blockchain. E.g. ETH for Ethereum.
tokenAddress	String	The on-chain token address for the associated token.
standard	String	The token standard applicable to the associated token. Possible values: `ERC20, ERC721, ERC1155`
name	String	The name of the associated token.
symbol	String	The symbol of the associated token
decimals	Integer	The number of decimals the associated token supports.
createDate	String	The time that the transaction request was submitted in ISO-8601 UTC date/time format.
updateDate	String	The time of the last update date in ISO-8601 UTC date/time format.

NFT Object

An nft object represents the different characteristics of any nfts held in a given wallet.

Example NFT Object:

{
     "nftTokenId": "10",
     "Token": {
        "id": "bd41ad79-0ef8-5054-adaf-154c2395f3e7",
        "blockchain": "ETH",
        "tokenAddress": "0xa20687c31af8f548467f2469e0978614500eb716",
        "standard": "ERC721",
        "name": "MinNFT",
        "symbol": "Min-NFT",
        "decimals": 0,
        "isNative": false,
        "updateDate": "2023-06-09T06:36:44Z",
        "createDate": "2023-06-09T06:36:44Z"
     },
     "amount": "1",
     "metadata": "QmWbzRKxWAc4n99LLrEs189wx5QssVZNd56hn4PPGQyt68",
     "updateDate": "2023-06-27T21:58:45Z"
}

NFT Attributes


nftTokenId	String	The unique token id of the associated NFT.
token	object	The token object relevant to the associated NFT.
amount	String	The amount of the associated NFTs held in a target wallet. For non-fungible token standards, like ERC721, it will always be “1”; for semi-fungible token standards like ERC1155, it will be the amount of tokens held.
metadata	String	Metadata of the associated NFT. The content of metadata will be the same as the response from calling the abi tokenURI.
blockHeight	Integer	Blockheight that info has been updated
updateDate	String	The time of the last update date in ISO-8601 UTC date/time format.