Forwarding Transactions

Use Apps.Forward to set automatic forwarding from virtual accounts.

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.

Create forwarding

Forwarding is transaction post-process routing.

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:

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.

"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.

"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.

cURL

echo 'Automatically forward 0.3% of incoming amount'

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" 
}'

In response we get new forwarding object.

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

cURL

echo 'list payments with status PENDING'

curl --location --request GET 'https://api.orangepill.cloud/v1/apps/payment/6fbdb56217f6a7b340be52df' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'Content-Type: application/json'

In response we get array of forwarding objects.

[{
    "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.

cURL

echo 'Automatically forward 0.5% of incoming amount'

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" 
}'

In response we get updated forwarding object.

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

cURL

echo 'Automatically forward 0.5% of incoming amount'

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' 

In response we get id of deleted forwarding object.

"675ab191e9023f356dfa6396"