Most of the REST API endpoints allow optional data to be included in their responses. It could be related entities, derived properties, account info standard data , or CSPR rates at the moment of the entity creation. Please check the endpoint documentation to find out what optional properties could be included in the responses.
Requests
Optional data can be included using the includes query param that specifies a comma-separated list of all optional data that should be included. The includes query param options can be one of three forms:
Scalar values
To include a scalar value its name should be specified the includes list.
Objects
Similar to scalar values to include an object its name should be specified in the includes list. However, for objects it's possible to specify a subset of fields that should be returned using the object querying syntax, which looks like this:
Copy includes=account_info{info{owner{name,branding{logo}}}} The request above will return only the name and the branding.logo properties of the account info object
Functions
When the included data requires extra parameters, it is included as a function. The function form provides a possibility to specify the needed input. For example, to include the USD to CSPR rate, the USD currency ID 1 should be passed as a parameter to the rate function, like this:
Examples
Scalar values
The WriteTransfer transforms that are used to track the native token transfers, contain the recipient account hash. It's possible, however, to include the corresponding public key if it is known to us. To learn more, visit the Transfer REST API page.
Copy curl -X 'GET' \
'https://api.testnet.cspr.cloud/transfers?includes=to_public_key' \
-H 'accept: application/json' \
-H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'
Copy {
"data" : [
{
"amount" : "2500000000" ,
"deploy_hash" : "0000015dd8b8065e31af7785cd174fa10bebf380f39515ffc3a8a536aee819a0" ,
"from_purse" : "uref-b8b87efb3d0f6d6f5f4b3bed8a9b017acfcb7ecaf555ec42d852864622e71c9b-007" ,
"id" : 0 ,
"initiator_account_hash" : "42204997767147bb78f0045b50272cdfbf90bd10544f9e51d66e0560166de456" ,
"timestamp" : "2021-10-12T06:20:59Z" ,
"to_account_hash" : "a8ae349a49ede9df992637e4c9141b5075352b4d607711bd1cf30a76403406c6" ,
"to_public_key" : "01da93a224201b9936f535502643fe07a922b2010993cdad093acb0112d810c1a8" ,
"to_purse" : "uref-6626e023ab7ab4837be36a9e61dffcfe239d987039727c9f56408527e48d3968-004" ,
"transform_key" : "c3fca49f9193ec730e9170a02360d0a96d9f3c07c9b898b6c6494d67b417d886"
} ,
{
"amount" : "2500000000" ,
"deploy_hash" : "00000498bf7c3994f804a4f8a99378350e02ebf5633774ced4faa2ae6dad88a3" ,
"from_purse" : "uref-6626e023ab7ab4837be36a9e61dffcfe239d987039727c9f56408527e48d3968-007" ,
"id" : 0 ,
"initiator_account_hash" : "a8ae349a49ede9df992637e4c9141b5075352b4d607711bd1cf30a76403406c6" ,
"timestamp" : "2021-10-13T12:26:47Z" ,
"to_account_hash" : "42204997767147bb78f0045b50272cdfbf90bd10544f9e51d66e0560166de456" ,
"to_public_key" : "01c978cd9eb96143ed89f0523c07787207ff4eb84756197a6a1d9093bcd51da4ed" ,
"to_purse" : "uref-b8b87efb3d0f6d6f5f4b3bed8a9b017acfcb7ecaf555ec42d852864622e71c9b-004" ,
"transform_key" : "7fd3d2892dc61f43269a55aaeec21158c283717549caf7a820e9cfa966e6df1d"
} ,
...
{
"amount" : "1000000000000" ,
"deploy_hash" : "000026eeab921c16335f65f54ea050efca9cf352840a1025f87b4deaa3bbdd95" ,
"from_purse" : "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007" ,
"id" : null ,
"initiator_account_hash" : "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446" ,
"timestamp" : "2021-10-20T23:59:25Z" ,
"to_account_hash" : "1b43092d00330439d874c1e4b38bf68b6c9a043aacf72da350e65e46d13e0c51" ,
"to_public_key" : "01ec83a2a60742294ab33aa86b6cd6c71662d1f37e9a270edc1e768e1a7deaa5c7" ,
"to_purse" : "uref-f4d64726bf61c2b1f53ce9b137a64a063e8225a98f1cb6ed1a9966ccf983b480-004" ,
"transform_key" : "f4d64726bf61c2b1f53ce9b137a64a063e8225a98f1cb6ed1a9966ccf983b480"
}
] ,
"item_count" : 5297116 ,
"page_count" : 529712
} Objects
An entity is called related if its identifier is present among the requested entity's properties. To include a related entity you need to specify its name in the includes query param. In the example below, we include contract package and contract entry point objects in the deploy list data. To learn more, visit the Including related entities page.
Copy curl -X 'GET' \
'https://api.testnet.cspr.cloud/deploys?includes=contract_package,contract_entrypoint \
-H ' accept: application/json ' \
-H ' authorization: 55f79117-fc4d-4d60-9956-65423f39a06a '
Copy {
"item_count" : 6664918 ,
"page_count" : 666492 ,
"data" : [
{
"args" : {
"amount" : {
"cl_type" : "U512" ,
"parsed" : "100000000000"
} ,
"post_id" : {
"cl_type" : "U64" ,
"parsed" : 1
} ,
"source_purse" : {
"cl_type" : "URef" ,
"parsed" : "uref-dbee6bd5057140ef79760ff97ee225f219c095a6b520e9fdb1083005b3e91adf-007"
}
} ,
"block_hash" : "2f535ee1f7a841bf33fb3af6c841ee5ac81b331e4f033e2700829800d406cd6a" ,
"caller_public_key" : "019d71f9869046408292ec32e78e613ac5f7b320fd268cd8c0ae3c95dc5d6dca62" ,
"contract_entrypoint" : {
"action_type_id" : null ,
"contract_hash" : "8069372ccd59c538d93404313182f8c47579b5aa4fe23060ae2f6ef83a4aa7c0" ,
"contract_package_hash" : "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad" ,
"id" : 1685659 ,
"name" : "bid"
} ,
"contract_hash" : "8069372ccd59c538d93404313182f8c47579b5aa4fe23060ae2f6ef83a4aa7c0" ,
"contract_package" : {
"contract_package_hash" : "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad" ,
"description" : null ,
"icon_url" : null ,
"latest_version_contract_type_id" : null ,
"metadata" : {} ,
"name" : null ,
"owner_public_key" : "01a0c97ba1ba5a973eeee369e9480ea15665278699873876a18eaf09c361f8e9c1" ,
"timestamp" : "2023-12-17T16:32:42Z"
} ,
"contract_package_hash" : "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad" ,
"cost" : "20894638930" ,
"deploy_hash" : "c2a83a2409f65447d8495768a6f99fee7247135680461ed4b3d6d936995c7630" ,
"entry_point_id" : 1685659 ,
"error_message" : null ,
"execution_type_id" : 2 ,
"payment_amount" : "150000000000" ,
"status" : "processed" ,
"timestamp" : "2023-12-17T17:52:39Z"
} ,
...
{
"args" : {
"token_owner" : {
"cl_type" : "Key" ,
"parsed" : {
"Account" : "account-hash-2142a81faac0670b76ef0e1be2925ddb9cd7493cc99b2fa591161b82c808a7e3"
}
}
} ,
"block_hash" : "0daaee30d1a87b4323221e43d08ce4365ab88681f47b18cc247336fa6773d731" ,
"caller_public_key" : "014d657f276686b711251f32fb9fa36c0852aaab43f4f6bb6cbc7794d4d54cf67e" ,
"contract_entrypoint" : {
"action_type_id" : null ,
"contract_hash" : "f07497ba5e71e52643e620d4722419c22870638ee3f5412c9cbc204c00b3b0b0" ,
"contract_package_hash" : "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41" ,
"id" : 1685652 ,
"name" : "register_owner"
} ,
"contract_hash" : "f07497ba5e71e52643e620d4722419c22870638ee3f5412c9cbc204c00b3b0b0" ,
"contract_package" : {
"contract_package_hash" : "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41" ,
"description" : null ,
"icon_url" : null ,
"latest_version_contract_type_id" : 7 ,
"metadata" : {
"burn_mode" : 0 ,
"events_mode" : 0 ,
"holder_mode" : 2 ,
"identifier_mode" : 0 ,
"metadata_mutability" : 1 ,
"minting_mode" : 1 ,
"name" : "enhanced-nft-1" ,
"nft_kind" : 1 ,
"nft_metadata_kind" : 0 ,
"ownership_mode" : 2 ,
"symbol" : "ENFT-1" ,
"total_supply_uref" : "uref-bc550f42fe8898a51bc0daae90ce910f4b5a042a306efa8f95032813089ad195-007" ,
"whitelist_mode" : 0
} ,
"name" : "enhanced-nft-1" ,
"owner_public_key" : "01a0c97ba1ba5a973eeee369e9480ea15665278699873876a18eaf09c361f8e9c1" ,
"timestamp" : "2023-12-17T16:29:40Z"
} ,
"contract_package_hash" : "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41" ,
"cost" : "681461970" ,
"deploy_hash" : "be2db151ba267cff9630b54c45b0aeb704d7d512f12670f7995af7cedad27d27" ,
"entry_point_id" : 1685652 ,
"error_message" : null ,
"execution_type_id" : 2 ,
"payment_amount" : "5000000000" ,
"status" : "processed" ,
"timestamp" : "2023-12-17T17:26:36Z"
}
]
} Functions
Entities that have the timestamp property can optionally include the CSPR rate at that time in the requested currency, which is passed as an argument to the rate function. In the example below, we include the USD to CSPR rate in the account transfers response. To learn more, visit the Including CSPR rates page.
Copy curl -X 'GET' \
'https://api.testnet.cspr.cloud/accounts/8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f/transfers?includes=rate(1)' \
-H 'accept: application/json' \
-H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'
Copy {
"data" : [
{
"amount" : "10000000000000" ,
"deploy_hash" : "4237b9518b7f0dda69235fedc92badd4e5206cd9b3ad2e9f599fe34416d9e3ab" ,
"from_purse" : "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007" ,
"id" : 20230516 ,
"initiator_account_hash" : "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446" ,
"rate" : 0.0488488 ,
"timestamp" : "2023-05-16T22:01:16Z" ,
"to_account_hash" : "8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f" ,
"to_purse" : "uref-fb2c1f47c593e5f27735c92217d7c99f85516467a1cb446214ae22fc46d8559e-004" ,
"transform_key" : "abf1343e47952a57ab001ec423398a773dfd96f3f32a905daeb6bc47db0db2dc"
} ,
{
"amount" : "1000000000000" ,
"deploy_hash" : "4d14f8f9cd95aabdfdea930aa9472bf966264d25f57986b005810e11d1c05017" ,
"from_purse" : "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007" ,
"id" : null ,
"initiator_account_hash" : "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446" ,
"rate" : 0.0295418 ,
"timestamp" : "2022-11-14T13:14:02Z" ,
"to_account_hash" : "8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f" ,
"to_purse" : "uref-fb2c1f47c593e5f27735c92217d7c99f85516467a1cb446214ae22fc46d8559e-004" ,
"transform_key" : "b0a27297a03107cd66c270d9bc7b33086f3ceb9c2e8c4058e72a4285c73273bd"
}
] ,
"item_count" : 2 ,
"page_count" : 1
} The rate property of the first result in the response above holds the CSPR rate from May 16th, 2023, and the second result has the rate from November 11th, 2022.
Last updated 5 months ago
