# Request a change with an intent

In this tutorial you'll learn how to change your system with an intent using the Ripple Custody API.

You can use these steps for the majority of intent types, such as adding and updating entities in your environment, and performing blockchain transactions.

## Learning objectives

By the end of this tutorial, you should be able to:

- Run a dry run operation to help define the appropriate format and details for your intent.
- Submit an intent for approval.
- Follow the status of an intent through to successful execution.


## Request a change — flow

The workflow to request a change in Ripple Custody is as follows:

1. **Perform a dry run** — Dry run the transaction to check for errors and get fee estimates.
2. **Submit the intent** — Request the change.
3. **Check the result** — Track the status of the request through the system change workflow.


## Request a change — instructions

### Get information about errors and fees with a dry run

Prepare the payload you want to use, and then run it through a dry run operation. This fulfills two separate objectives:

- Checks the operation for errors.
- If this is a blockchain transaction, obtains an estimate of the fees needed for the transaction.


The XRP Ledger does not return fee estimates.

This step is optional, but highly recommended. The dry run step is especially important for blockchain transactions, as it can help you calculate the cost to execute the transaction on the ledger.

You do not need to authenticate or pay a fee for a dry run, so you can run it as many times as you want.

#### Prepare the request body

Prepare the request body of the update you want to request, with a `payload` block specific to your request. For more information on the standard dry run request body format, see [Dry run and signature request body](/products/custody/v1.19/api/reference/intent-structure#dry-run-and-signature-request-body).

The format of the `payload` block depends on the entity you want to update and, for transaction orders, on the blockchain:

- For environment and accounting entity updates: Use the `payload` relevant for the entity, such as the one in [Create a user](/products/custody/v1.19/api/environment/user/create#payload-example).
- For simple blockchain transactions, such as sending assets: Use a transfer order `payload`, such as the native asset example in [Send assets](/products/custody/v1.19/api/accounting/send-assets#send-the-assets).
- For complex blockchain transactions, such as smart contract deployment: Use a transaction order `payload`, such as the one in [Deploy a smart contract on an EVM ledger](/products/custody/v1.19/api/accounting/smart-contracts#payload-example).


Tip!
The main differences between transfer order and transaction order payloads to remember are as follows:

- For transaction orders:
  - The main `payload` section you need to pay attention to is the `parameters` block. This block contains the fields required for the specific blockchain ledger.
  - You can use different fee strategies to set the fee level.
- For transfer orders:
  - The `payload` format for all blockchain ledgers is the same.
  - You can only use a priority fee strategy.


[Learn more about transfer orders and transaction orders](/products/custody/v1.19/overview/blockchain/transactions/transaction-initiation)
[Learn more about fee strategies](/products/custody/v1.19/overview/blockchain/transactions/transaction-fees)

#### Perform the dry run

Perform a dry run with the request body you prepared. For more information, see [Perform the dry run](/products/custody/v1.19/api/get-started/key-operations/update/dry-run#perform-the-dry-run).

Ripple Custody returns a response in a format specific to the update request type.

- All responses contain a `result` of the dry run. If the result is `Failure`, you can find more details in the `reason` and `hint` fields. For more information, see [Troubleshooting](#troubleshooting).
- Transaction responses contain an `estimate` of the fee amount, which you can use to help define the fee strategy for the transaction.


#### Check the result and rerun

If you receive an error or want to adjust the fees, update the `payload` block and run the dry run again.

### Submit the intent

Now you have an idea of how to format your request and, if applicable, any fees you need to pay for a transaction, you can move on to the creation of the request itself.

#### Create the intent request

Create the request using the steps in [Propose intents](/products/custody/v1.19/api/get-started/key-operations/update/intent-proposal). You're going to use the request body you created for the dry run.

Remember!
To receive a similar result to the dry run, you need to ensure you use the same intent type and `payload` block as you used before.

The actual fees you need to pay for transactions are calculated in real time based on the current status of the ledger, and may change from the dry run fees.

#### Note the request ID

If you did not provide a `requestId`, when the transaction returns a status code of `202 Accepted`, make a note of the `requestId` returned in the response body. You're going to use this to track the status of your request.

### Track the change through the intent workflow

Once you have submitted your intent, you can track the status of the intent by following it through the standard intent workflow:

1. Request execution.
2. Intent approval.
3. Entity creation.


For more information about the intent workflow, see [Governance workflow](/products/custody/v1.19/overview/governance#governance-workflow).

#### Check the request

Check the status of the request. If the request itself does not execute successfully, the intent cannot proceed.

To check the status of the request, follow the steps described in [Check the request](/products/custody/v1.19/api/get-started/key-operations/update/check#check-the-request).

#### Check the intent

Check the status of the intent. You can follow the intent through the approval process.

To check the status of the intent, follow the steps described in [Check the intent](/products/custody/v1.19/api/get-started/key-operations/update/check#check-the-intent).

#### Check the entity

When the intent is successfully approved, check the entity was created or updated as expected.

To check the status of the entity, follow the steps described in [Check the entity](/products/custody/v1.19/api/get-started/key-operations/update/check#check-the-entity).

##### Transaction checks

When you check the status of a transaction order entity, you can also view the underlying transaction and transfer entities, as described in [View transactions](/products/custody/v1.19/api/accounting/transactions/view).

The following example shows one failed transaction and one successful transaction:


```json
{
    "items": [
        {
            "id": "660635b0-b2c4-4f09-9558-0b6c6de34851",
            "ledgerId": "stellar-testnet-june-2023",
            "orderReference": {
                "id": "f039c4c4-f537-4fb0-9a37-66638f942398",
                "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1"
            },
            "relatedAccounts": [
                {
                    "id": "7a29d2ff-1349-40f5-ba88-d3bc63086db4",
                    "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
                    "sender": true
                }
            ],
            "processing": {
                "hint": "InternalError",
                "status": "Broadcasting"
            },
            "registeredAt": "2023-12-19T13:57:29.889Z",
            "ledgerTransactionData": null
        },
        {
            "id": "e237921b-6606-4d2b-98db-dfc337f09e5d",
            "ledgerId": "solana-devnet",
            "orderReference": {
                "id": "2c4bc542-23f2-48a1-9144-65f614116340",
                "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1"
            },
            "relatedAccounts": [
                {
                    "id": "b0a8c0fb-628c-40c0-ad35-c2eac0214ded",
                    "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
                    "sender": false
                },
                {
                    "id": "5e09d9b9-f1e3-456a-acc7-6cfa7440621d",
                    "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
                    "sender": true
                }
            ],
            "processing": {
                "status": "Completed"
            },
            "registeredAt": "2023-12-19T13:37:41.812Z",
            "ledgerTransactionData": {
                "ledgerStatus": "Confirmed",
                "failure": null,
                "ledgerTransactionId": "2uiEJqEf3XDaMTC8vfaaagY4Ed4kk6uBAUuxxeub95o9VrmM4C5utGYwPoxMpNdBnLLwz7qCWfMoAmC6GaiVkMZU",
                "rawTransaction": "4oXTpSjpdHj3f8emwFhgopn1F4xCF8G2qgDKMxz4zq4tfeGXbx52J3BpsPqVwWq7kB8f1iCZJdZ7aZwxo6dFjZYkijg6S3DHLeQKvkdD55a1q8Es75n7HHNGkkwkaL5DCDRGZUbSiDXxXc1NuPDqhTxP3f6C6eCYt4S6HEGkuzA5TJSrmaEydTGNNCjwrHXnBcNA5gr5g9zceWqLa9Z6KbQ839kefbjXCUVGqbjUQ49uyUsZBTaUchsLbbGw4ay3F5BYnszfWW2HAvXQhFKANwmtwYF5u3qvD9GST",
                "statusLastUpdatedAt": "2023-12-19T13:38:06.145Z",
                "ledgerData": null
            }
        }
    ],
    "count": 2,
    "currentStartingAfter": null,
    "nextStartingAfter": "d5c8b04e-94da-45d1-91e6-8e952e4c1dbd"
}
```

The following fields contain information about the status of the transaction:

- `processing.status`: The status of the transaction in Ripple Custody, along with a `hint` if the transaction was not executed successfully.
- `ledgerTransactionData.ledgerStatus`: The status of the transaction on the blockchain.


For more information, see [Transaction statuses](/products/custody/v1.19/overview/blockchain/transactions/transaction-processing#transaction-statuses).

## Troubleshooting

### Hints

You can find a list of hints and their meanings in the API reference, as follows:

- For dry run failures, see the 200 response schema for the [dry run](/products/custody/v1.19/api/reference/openapi/intents/intentdryrun) operation, by selecting `result.type` as `Failure`.
- For transaction failures, see the 200 response schema for the [Get transaction details](/products/custody/v1.19/api/reference/openapi/transactions/gettransaction) operation, by selecting the relevant `processing.status`.