# Optional properties

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](https://github.com/make-software/casper-account-info-contract), 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:

```
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:

```
includes=rate(1)
```

## 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](https://docs.cspr.cloud/1.2.x/rest-api/transfer) page.

```bash
curl -X 'GET' \
  'https://api.testnet.cspr.cloud/transfers?includes=to_public_key' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'
```

```json
{
  "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](https://docs.cspr.cloud/1.2.x/documentation/highlights/including-related-entities) page.

```bash
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'
```

```json
{
  "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](https://docs.cspr.cloud/1.2.x/documentation/highlights/including-cspr-rates) page.

```bash
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'
```

```json
{
  "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.