# Forwarding Transactions

Use SmartApp Forwarding to set template for automatic forwarding of received amount to another Virtual account. Amount of forwarding transaction can be expressed as `fixed` of `percentage` amount of incoming transaction. You can add multiple forwarding transactions for each Virtual account.

<figure><img src="https://3218614644-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoAQr9l0l72LlC4cHtGP0%2Fuploads%2FkUcW9nr7LRTFUqjg0eFD%2FSmartApp_Forwarding.png?alt=media&#x26;token=f9d2dd17-bc9d-47d6-8aaa-4e2c7225a76b" alt=""><figcaption></figcaption></figure>

## Create forwarding

Forwarding is transaction post-process routing.&#x20;

After transaction or deposit is processed all Apps.Forwards are triggered. If any condition is resolved TRUE  array of transactions is executed.

Set `value_type` as `FIXED` or `PERCENTAGE` and add `value` value. This fixed or percentage amount of original transaction that is forwarded as transaction.value in new, forwarded transactions.

### Condition Evaluation

The conditions are evaluated based on the attributes of the transaction. The conditions within an array act as logical OR operators, and the fields within the same condition object act as logical AND operators.

For the conditions array to be considered met, at least one condition within the array must be true. For a condition to be true, all specified fields within that condition object must match the corresponding fields in the transaction.

Additionally, it's important to note that min and max can be used together to specify a range, and if either min or max is alone, the transaction value is matched against that specific value.

Condition example

Explained:&#x20;

IF\
transaction arrived from account with id 656a0fd58e907523577a53f6, AND is of type paymentAND with transaction amount between 20 to 25 BTC\
OR\
transaction destination is alias ALIAS1 AND transaction amount exactly 0.002 BTC.

```json
"condition": [
    {
        "source": {
            "account": "656a0fd58e907523577a53f6"
        },
        "type": "payment",
        "asset": "BTC",        
        "amount": {
            "min": "20",
            "max": "25"
        }
    },
    {
        "destination": {
            "alias": "ALIAS1"
        },
        "asset": "BTC",        
        "amount": {
            "min": "0.002"
        }
        
    }
]
```

### Result Transaction

If condition is met for the transaction currently being processed, resulting transactions will be executed thus forwarding received amount to new destinations.

Forwarding transactions example

Explained:

Do 2 forwards. \
1\. send 10% of incoming transaction amount to account 65562b757789a763c76fed81\
2\. send 0.0001 BTC to alias alias2.

```json
"transactions": [
    {
        "destination": {
            "account": "65562b757789a763c76fed81"
        },
        "value_type": "PERCENTAGE",
        "value": "10",
        "asset": "BTC"
    },
    {
        "destination": {
            "alias": "alias2"
        },
        "value_type": "FIXED",
        "value": "0.0001",
        "asset": "BTC"
    }
]
```

## Create Apps.Forward

When creating new Apps.Forward you can use additional fields.

Use `data` object to add custom fields for this operation.

Use `description` object to add custom fields for this operation.

{% tabs %}
{% tab title="cURL" %}

<pre class="language-shell"><code class="lang-shell"><strong>echo 'Automatically forward 0.3% of incoming amount'
</strong>
curl --location --request POST 'https://api.orangepill.cloud/v1/apps/forward' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933dffabb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "condition": [
        {
            "source": {
                "account": "656a0fd58e907523577a53f6"
            },
            "type": "payment",
            "asset": "BTC",        
            "amount": {
                "min": "20",
                "max": "25"
            }
        },
        {
            "destination": {
                "alias": "ALIAS1"
            },
            "asset": "BTC",        
            "amount": {
                "min": "0.002"
            }
            
        }
    ]
    ,
    "transactions": [
        "destination": {
            "account": "6340be52dffbdb56217f6a7b"
        },
        "value_type": "PERCENTAGE",    
        "value": 0.3,
        "asset": "BTC",
        "data": {
            "description": "Pay 0.3% fee"
        }
    ],
    "data": {
        "field1": "value1"
    },
    "description": "Default fees" 
}'
</code></pre>

{% endtab %}
{% endtabs %}

In response we get new forwarding object.

```json
{
    "id": "675ab191e9023f356dfa6396",
    "condition": [
        {
            "source": {
                "account": "656a0fd58e907523577a53f6"
            },
            "type": "payment",
            "asset": "BTC",        
            "amount": {
                "min": "20",
                "max": "25"
            }
        },
        {
            "destination": {
                "alias": "ALIAS1"
            },
            "asset": "BTC",        
            "amount": {
                "min": "0.002"
            }
            
        }
    ]
    ,
    "transactions": [
        "destination": {
            "account": "6340be52dffbdb56217f6a7b"
        },
        "value_type": "PERCENTAGE",    
        "value": 0.3,
        "asset": "BTC",
        "data": {
            "description": "Pay 0.3% fee"
        }
    ],
    "data": {
        "field1": "value1"
    },
    "description": "Default fees" 
    "owner": "639675ab191e9023f356dfa6",
    "created_at": 1671242774572,
    "error": null
}
```

## List Forwardings

You can list all Forwardings or filter it by account.

{% tabs %}
{% tab title="cURL" %}

<pre class="language-shell"><code class="lang-shell"><strong>echo 'list payments with status PENDING'
</strong>
curl --location --request GET 'https://api.orangepill.cloud/v1/apps/payment/6fbdb56217f6a7b340be52df' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'Content-Type: application/json'
</code></pre>

{% endtab %}
{% endtabs %}

In response we get array of `forwarding` objects.&#x20;

```json
[{
    "id": "675ab191e9023f356dfa6396",
    "condition": [
        {
            "source": {
                "account": "656a0fd58e907523577a53f6"
            },
            "type": "payment",
            "asset": "BTC",        
            "amount": {
                "min": "20",
                "max": "25"
            }
        },
        {
            "destination": {
                "alias": "ALIAS1"
            },
            "asset": "BTC",        
            "amount": {
                "min": "0.002"
            }
            
        }
    ]
    ,
    "transactions": [
        "destination": {
            "account": "6340be52dffbdb56217f6a7b"
        },
        "value_type": "PERCENTAGE",    
        "value": 0.3,
        "asset": "BTC",
        "data": {
            "description": "Pay 0.3% fee"
        }
    ],
    "data": {
        "field1": "value1"
    },
    "description": "Default fees" 
    "owner": "639675ab191e9023f356dfa6",
    "created_at": 1671242774572,
    "error": null
}
]
```

## Update Apps.Forward

You can update Apps.Forwrad and impact all new transcations. Transactions already processed will not be impacted by this change.

To update Apps.Forward you need the ID of that entity.

{% tabs %}
{% tab title="cURL" %}

<pre class="language-shell"><code class="lang-shell"><strong>echo 'Automatically forward 0.5% of incoming amount'
</strong>
curl --location --request PATCH 'https://api.orangepill.cloud/v1/apps/forward/675ab191e9023f356dfa6396' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933dffabb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "condition": [
        {
            "source": {
                "account": "656a0fd58e907523577a53f6"
            },
            "type": "payment",
            "asset": "BTC",        
            "value": {
                "min": "30",
                "max": "35"
            }
        },
        {
            "destination": {
                "alias": "ALIAS1"
            },
            "asset": "BTC",        
            "value": {
                "min": "0.004"
            }
            
        }
    ]
    ,
    "transactions": [
        "destination": {
            "account": "6340be52dffbdb56217f6a7b"
        },
        "value_type": "PERCENTAGE",    
        "value": 0.5,
        "asset": "BTC",
        "data": {
            "description": "Pay 0.5% fee"
        }
    ],
    "data": {
        "field1": "value1"
    },
    "description": "Default fees" 
}'
</code></pre>

{% endtab %}
{% endtabs %}

In response we get updated forwarding object.

```json
{
    "id": "675ab191e9023f356dfa6396",
    "condition": [
        {
            "source": {
                "account": "656a0fd58e907523577a53f6"
            },
            "type": "payment",
            "asset": "BTC",        
            "value": {
                "min": "30",
                "max": "35"
            }
        },
        {
            "destination": {
                "alias": "ALIAS1"
            },
            "asset": "BTC",        
            "value": {
                "min": "0.004"
            }
            
        }
    ]
    ,
    "transactions": [
        "destination": {
            "account": "6340be52dffbdb56217f6a7b"
        },
        "value_type": "PERCENTAGE",    
        "value": 0.5,
        "asset": "BTC",
        "data": {
            "description": "Pay 0.5% fee"
        }
    ],
    "data": {
        "field1": "value1"
    },
    "description": "Default fees" 
    "owner": "639675ab191e9023f356dfa6",
    "created_at": 1671242774572,
    "error": null
}
```

## Delete Apps.Forward

You can delete Apps.Forwrad and disable automatic routing for all new transcations. Transactions already processed will not be impacted by this change.

To delete Apps.Forward you need the ID of that entity.

{% tabs %}
{% tab title="cURL" %}

<pre class="language-shell"><code class="lang-shell"><strong>echo 'Automatically forward 0.5% of incoming amount'
</strong>
curl --location --request DELETE 'https://api.orangepill.cloud/v1/apps/forward/675ab191e9023f356dfa6396' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933dffabb' \
--header 'Content-Type: application/json' 
</code></pre>

{% endtab %}
{% endtabs %}

In response we get id of deleted forwarding object.

```json
"675ab191e9023f356dfa6396"
```