Account Transaction Policies

Account transaction policies enable you to define policies on transactions or transfers for a given account. Policies can specify amount or frequency limits for a given asset for a given account. If the policy conditions are met, you can specify that a group or groups of users must approve or deny the transaction.

Prerequisites

  • Decide upon the rules for your policies. For a given asset, decide if you wish to limit transactions by:

    • amount range - specify a minimum and maximum amount.

    • frequency - specify either transaction frequency (number of transactions in a given time period) or amount frequency (maximum aggregate amount in a given time period).

  • You'll group your rules into rule groups. A rule must belong to one rule group. Rule groups enable you to define different types of rules that require different authorizations.

  • Identify the target accounts to which you wish to apply transaction policies.

  • Identify the users who can authorize the transactions. The users will be placed into one or more authorization groups.

  • Identify which authorization groups can authorize which rules.

  • Identify how many users per authorization group are needed to authorize a given rule. For example, Group X includes users a, b, and c. Group Y includes users d and e. For rule P, require two users from Group X and one user from Group Y.

API resources

In order to define and enact policies, you'll use the following resources:

  • accounts - the account to which a transaction policy is applied

  • rule groups - a set of rules associated with one or more accounts

  • rules - decision logic applied to one or more types of transactions/transfers of a specific asset

  • authorization groups - group of users that are associated with a rule group

  • authorization rule groups - links an authorization group with a rule by specifying how many people of that group would be needed to approve the transaction

  • authorization items - the outcome of a rule applied to a transaction

Steps to setup an account transaction policy

  1. Create a Rule Group object by using POST /v2/rule-groups.

  2. Add a Rule object to a Rule Group created in step 1 by using POST /v2/rules.

  • If applying the rule to a currency, specify the currency-type (values: "AUD" "CAD" "EUR" "GBP" "JPY" "USD").

  • If applying the rule to an asset, specify the asset-id.

  • Specify transfer-types (values: "Account Cash Transfer", "Asset Transfer", "Funds Transfer", "Internal Asset Transfer", "Sub Asset Transfer")

  • You can apply either an Amount Rule Amount or Frequency Rule:

    • Amount - this type of rule uses the amount of the transactions to decide if it should be applied

    • Frequency - this is a velocity rule that allows you to specify either the number of transactions or the maximum aggregate amount.

Rule examples

Amount Rule for BTC internal asset transfers and asset transfers (contributions and disbursements) where the amount is between 0.1 and 100.

{
"data": {
"type": "rules",
"attributes": {
"rule-group-id": "{{rule-groups-id-1}}",
"transfer-types" : [ "asset_transfer","internal_asset_transfer"],
"rule-type": "amount",
"asset-id": "{{asset-id-btc}}",
"transfer-amount-minimum": 0.1,
"transfer-amount-maximum": 100
}
}
}

Frequency Rule for USD funds transfers. This rule will apply for funds transfers done when the aggregate maximum of 1000 USD has been exceeded in the past 500 hours.

{
"data": {
"type": "rules",
"attributes": {
"rule-group-id": "024b6d6e-a7d4-4c64-b178-f23552019811",
"rule-type": "frequency",
"transfer-types": ["funds_transfer"],
"currency-type": "USD",
"transfer-amount-maximum": 1000,
"past-hours": 500
}
}
}
  1. Associate an Authorization Group to a Rule Group created in step 1 by using POST /v2/authorization-groups.
{
"data": {
"type": "authorization-groups",
"attributes": {
"rule-group-id" : "{{rule-groups-id}}",
"label": "test",
"user-emails": ["john.doe@company.com", "jane.doe@company.com"]
}
}
}
  1. Associate a Rule to an Authorization Group. The Authorization Group and the Rule must belong to the same Rule Group. In this object you specify how many of the users within the Authorization Group must authorize the transaction. Use POST /v2/authorization-rule-groups.

Authorization rule group examples

If you want Rule A to require approval from 2 users of Authorization Group A (that has 5 users) and approval from 1 user in Authorization Group B, the following Authorization Rule Groups would be required.

Authorization Rule Group 1

{
"data": {
"type": "authorization-rule-groups",
"attributes": {
"rule-id" : "{{rule-A-id}}",
"authorization-group-id": "{{authorization-group-A-id}}",
"label": "For Rule A require 2 users from group A to authorize",
"number-of-users": 2
}
}
}

Authorization Rule Group 2

{
"data": {
"type": "authorization-rule-groups",
"attributes": {
"rule-id" : "{{rule-A-id}}",
"authorization-group-id": "{{authorization-group-B-id}}",
"label": "For Rule A require 1 user from group B to authorize",
"number-of-users": 1
}
}
}
  1. Once your Rule Group has all the necessary Rules linked with the correct Authorization Groups, you can then attach it to an Account object using POST /v2/accounts/{{accounts-id}}/set-rule-group.
{
"data": {
"type": "accounts",
"attributes": {
"rule-group-id" : "{{rule-groups-id-1}}"
}
}
}
  1. Use the Authorization Items resource to retrieve all pending authorizations and to Approve or Deny the items.
  • GET /v2/authorization-items

  • POST /v2/authorization-items/{authorization-item-id}/approve

  • POST /v2/authorization-items/{authorization-item-id}/deny

Last updated on