> ## Documentation Index > Fetch the complete documentation index at: https://docs.dfns.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Policy > Setup a new Policy for your organization. Every policy requires a rule to be specified. Upon policy evaluation, the configuration specified in the rule will be used to determine whether the policy should trigger or not for a given activity. By exposing controls on permissions and policies, Dfns enables the specification of an admin quorum to approve sensitive actions which could change system governance. Note Dfns does not expose a separate "admin quorum" concept like some of our competitors - we simply enable this use case as another configuration of the policy engine itself. This was chosen to promote flexibility as not every customer will have the same requirements around creating and managing admin quorums. #### Authentication ✅ Organization User (`CustomerEmployee`)\ ❌ Delegated User (`EndUser`)\ ✅ Service Account #### Required Permissions `Policies:Create`: Always required. ## OpenAPI ````yaml /openapi.yaml post /v2/policies openapi: 3.1.0 info: version: 1.795.3 title: Dfns servers: - url: https://api.dfns.io description: Default - Europe - url: https://api.uae.dfns.io description: UAE - url: https://api.dfns.ninja description: Staging security: [] paths: /v2/policies: post: tags: - Policies summary: Create Policy description: |- Setup a new Policy for your organization. Every policy requires a rule to be specified. Upon policy evaluation, the configuration specified in the rule will be used to determine whether the policy should trigger or not for a given activity. By exposing controls on permissions and policies, Dfns enables the specification of an admin quorum to approve sensitive actions which could change system governance. Note Dfns does not expose a separate "admin quorum" concept like some of our competitors - we simply enable this use case as another configuration of the policy engine itself. This was chosen to promote flexibility as not every customer will have the same requirements around creating and managing admin quorums. requestBody: content: application/json: schema: oneOf: - type: object properties: name: type: string activityKind: type: string enum: - Registry:Addresses:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: {} required: - name - activityKind - rule - action additionalProperties: false description: '' title: Registry:Addresses:Modify - type: object properties: name: type: string activityKind: type: string enum: - Permissions:Assign rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: permissionId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false required: - permissionId additionalProperties: false required: - name - activityKind - rule - action additionalProperties: false description: >- A "`Permissions:Assign`" activity represents any activity which involves assigning a permission (or revoking it, aka "deleting a permission assignment"). These activities are Assignment change requests, created as a result of calling either: * the endpoint [Assign Permission](https://docs.dfns.co/api-reference/permissions/assign-permission) * the endpoint [Revoke Permission](https://docs.dfns.co/api-reference/permissions/revoke-permission) title: Permissions:Assign - type: object properties: name: type: string activityKind: type: string enum: - Permissions:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: permissionId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false required: - permissionId additionalProperties: false required: - name - activityKind - rule - action additionalProperties: false description: >- A "`Permissions:Modify`" activity represents any activity which involves updating or archiving a permission. These activities are Permission change requests, created as a result of calling either: * the endpoint [Update Permission](https://docs.dfns.co/api-reference/permissions/update-permission) * the endpoint [Delete Permission](https://docs.dfns.co/api-reference/permissions/delete-permission) title: Permissions:Modify - type: object properties: name: type: string activityKind: type: string enum: - Policies:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval filters: type: object properties: policyId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false required: - policyId additionalProperties: false required: - name - activityKind - rule - action additionalProperties: false description: > A "`Policies:Modify`" activity represents any activity which involves updating or archiving a policy. These activities are Policy change requests, created as a result of calling either: * the endpoint [Update Policy](https://docs.dfns.co/api-reference/policies/update-policy) * the endpoint [Delete Policy](https://docs.dfns.co/api-reference/policies/delete-policy) title: Policies:Modify - type: object properties: name: type: string activityKind: type: string enum: - Registry:ContractSchemas:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: {} required: - name - activityKind - rule - action additionalProperties: false description: >- A "`Registry:ContractSchemas:Modify`" activity represents any activity which modifies a Contract Schema registered for execution in the Dfns Dashboard title: Registry:ContractSchemas:Modify - type: object properties: name: type: string activityKind: type: string enum: - Wallets:Sign rule: oneOf: - type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger - type: object properties: kind: type: string enum: - TransactionRecipientWhitelist configuration: type: object properties: addresses: type: array items: type: string minLength: 1 description: Whitelisted recipient addresses required: - addresses additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the destination address *is NOT whitelisted*. title: TransactionRecipientWhitelist - type: object properties: kind: type: string enum: - TransactionAmountLimit configuration: type: object properties: limit: type: number description: Amount limit in `currency` currency: type: string enum: - USD description: Fiat currency, currently only `USD` required: - limit - currency additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the wallet activity detected is transferring some value which amount is greater than a given limit. Note: If the fiat amount of the wallet activity cannot be evaluated for any reason (eg. market prices are not available, or eg. the amount cannot be inferred from a wallet signature request, etc.), by default the rule will trigger the policy (this is called "failing closed" and is generally considered a security best practice). title: TransactionAmountLimit - type: object properties: kind: type: string enum: - TransactionAmountVelocity configuration: type: object properties: limit: type: number description: Amount limit in `currency` currency: type: string enum: - USD description: Currency for the amount limit above timeframe: type: integer minimum: 1 maximum: 43200 description: >- Time period in minutes. Minimum 1, Maximum 43,200. required: - limit - currency - timeframe additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the cumulative amount transferred from a given wallet within a given timeframe is greater than a specified limit. The aggregate amount evaluated is based only on the wallet that triggered the policy. title: TransactionAmountVelocity - type: object properties: kind: type: string enum: - TransactionCountVelocity configuration: type: object properties: limit: type: number description: Count limit timeframe: type: integer minimum: 1 maximum: 43200 description: >- Time period in minutes. Minimum 1, Maximum 43,200. required: - limit - timeframe additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the number of wallet activities for a given wallet within a given timeframe, is greater than a specified limit. The aggregate number of transactions evaluated is based only on the wallet that triggered the policy. title: TransactionCountVelocity - type: object properties: kind: type: string enum: - ChainalysisTransactionPrescreening configuration: type: object properties: alerts: type: object properties: alertLevel: type: string enum: - LOW - MEDIUM - HIGH - SEVERE categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - alertLevel - categoryIds exposures: type: object properties: direct: type: object properties: categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - categoryIds required: - direct addresses: type: object properties: categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - categoryIds userIdTemplate: type: string minLength: 1 maxLength: 50 pattern: >- ^([a-zA-Z0-9_:-]|{wallet\.id}|{wallet\.externalId})+$ default: dfns description: >- Value sent to Chainalysis as the "user ID". Used by Chainalysis for grouping transaction screenings. This template can include variables, included in brackets. The following variables are currently supported: `{wallet.id}` and `{wallet.externalId}`. As an example, if you set `userIdTemplate: "dfns:{wallet.id}_{wallet.externalId}"`, when your wallet receives a transaction that gets screened by a Chainalysis policy, the "user ID" sent to Chainalysis will be `dfns:wa-xxx_yyy` (`wa-xxx` being the wallet ID, and `yyy` being the wallet external ID). fallbackBehaviours: type: object properties: skipUnscreenableTransaction: type: boolean skipUnsupportedNetwork: type: boolean skipUnsupportedAsset: type: boolean skipChainalysisFailure: type: boolean required: - skipUnscreenableTransaction - skipUnsupportedNetwork - skipUnsupportedAsset - skipChainalysisFailure required: - alerts - exposures - addresses - fallbackBehaviours additionalProperties: false required: - kind - configuration additionalProperties: false description: >+ This rule can only be used once the Chainalysis integration is activated from the Dfns dashboard settings. (see more on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) integration page). It's a rule based on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) KYT integration (Know-Your-Transaction). Upon transfer attempt, we will first register the transfer with Chainalysis (as a ["withdrawal attempt"](https://docs.chainalysis.com/api/kyt/#registration-register-a-withdrawal-attempt)), and fetch the screening results (alerts, exposures, addresses detected). Based on the results, and the configuration of this rule, the policy will be triggered. It's called "Pre"-screening, because the scanned transaction is not on chain yet, it's still a transaction attempt (before the transaction actually make it on chain). ```json { "rule": { "kind": "ChainalysisTransactionPrescreening", "configuration": { "alerts": { "alertLevel": "LOW", "categoryIds": [] }, "exposures": { "direct": { "categoryIds": [] } }, "addresses": { "categoryIds": [] }, "fallbackBehaviours": { "skipUnscreenableTransaction": false, "skipUnsupportedNetwork": false, "skipUnsupportedAsset": false, "skipChainalysisFailure": false } } } } ``` **Configuration** | Property | Type | Description | | --- | --- | --- | | `alerts`

`.alertLevel`* | `string` | Minimum alert level above which the rule should trigger, if any [alert is returned in Chainalysis results](https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-alerts). Can be `LOW`, `MEDIUM`, `HIGH`, or `SEVERE` | | `alerts`

`.categoryIds`* | list of integers | List of Chainalysis category IDs (see [here](https://docs.chainalysis.com/api/kyt/#categories)). If you leave this list empty, alerts of any category will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list. | | `exposures`

`.direct`

`.categoryIds`* | list of integers | List of Chainalysis category IDs (see [here](https://docs.chainalysis.com/api/kyt/#categories)). If you leave this list empty, a [direct exposure](https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-direct-exposure) of any category detected by chainalysis will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list. | | `addresses`

`.categoryIds`* | list of integers | List of Chainalysis category IDs (see [here](https://docs.chainalysis.com/api/kyt/#categories)). If you leave this list empty, an [address](https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-address-identifications) of any category identified by chainalysis will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list. | | `fallbackBehaviours`

`.skipUnscreenableTransaction`* | boolean | Behaviour if the wallet activity is not screenable (eg. if it's a signature request of a hash). If true, a transaction which is "unscreenable" will just be skipped, and policy will not trigger | | `fallbackBehaviours.skipUnsupportedNetwork`* | boolean | Behaviour if the wallet activity is on a network not supported by chainalysis, or not yet supported in the dfns-chainalysis integration. If true, an unsupported network will just be skipped, and policy will not trigger | | `fallbackBehaviours.skipUnsupportedAsset`* | boolean | Behaviour if the wallet activity is with a asset not supported by chainalysis, or not yet supported in the dfns-chainalysis integration. If true, an unsupported asset will just be skipped, and policy will not trigger | | `fallbackBehaviours.skipChainalysisFailure`* | boolean | Behaviour if any issue with Chainalysis calls (timeout, results took too long, rate limiting errors, any error). If true, will skip if any error happens | title: ChainalysisTransactionPrescreening - type: object properties: kind: type: string enum: - GlobalLedgerTransactionPrescreening configuration: type: object properties: riskScoreThreshold: type: integer minimum: 0 maximum: 100 description: >- Risk score threshold (0-100). Policy triggers if address/transaction risk score >= threshold fallbackBehaviours: type: object properties: skipUnscreenableTransaction: type: boolean description: >- skip all wallet requests that cannot be screened (eg. raw signatures) skipUnsupportedNetwork: type: boolean description: >- skip transfer requests to a network not supported yet in our GlobalLedger integration skipUnsupportedAsset: type: boolean description: >- skip transfer requests of an asset not supported by our GlobalLedger integration skipGlobalLedgerFailure: type: boolean description: >- skips any errors from GlobalLedger API request required: - skipUnscreenableTransaction - skipUnsupportedNetwork - skipUnsupportedAsset - skipGlobalLedgerFailure required: - riskScoreThreshold - fallbackBehaviours additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule uses GlobalLedger KYT for pre-screening outgoing transfers by checking the destination address risk score. Upon transfer attempt, we will query GlobalLedger's address risk API, and check if the risk score (0-100) is at or above the configured threshold, or if any alerts show up. If so, the policy will be triggered. It's called "Pre"-screening, because the scanned transaction is not on chain yet, it's still a transaction attempt. title: GlobalLedgerTransactionPrescreening - type: object properties: kind: type: string enum: - TravelRuleTransactionPrescreening configuration: type: object properties: vendor: type: string enum: - Notabene autoTriggerTimeoutSeconds: type: integer minimum: 0 autoClearAfterDeliveredTimeoutSeconds: type: integer minimum: 0 required: - vendor - autoTriggerTimeoutSeconds additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule can only be used once the Notabene integration is activated from the Dfns dashboard settings (see more on [Notabene](https://docs.dfns.co/integrations/travel-rule/notabene) integration page). It's a rule based on [Notabene](https://docs.dfns.co/integrations/travel-rule/notabene) [TravelRule](https://docs.dfns.co/integrations/travel-rule) integration. It ***ONLY*** applies to Dfns [Transfer Asset](https://docs.dfns.co/api-reference/wallets/transfer-asset) Api Calls. It is NOT supported for Transfers initiated via the dashboard. Upon transfer attempt with an optional [TravelRule](https://docs.dfns.co/api-reference/wallets/transfer-asset#body-travel-rule) payload, we will call Notabene's APIs on your behalf to both confirm the validity of the travel rule message and submit it for processing. Dfns then waits for a response from the counterparty (for custodial transfers) or Notabene (for non-custodial transfers). It's called "Pre"-screening, because the transaction is not on chain yet, it's still a transaction attempt (before the transaction actually make it on chain). title: TravelRuleTransactionPrescreening action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block - type: object properties: kind: type: string enum: - NoAction required: - kind additionalProperties: false description: |2- This action kind means that nothing will happen after policy rule evaluation. It's meant to be used with policy rules "`ChainalysisTransactionPrescreening`" or "`ChainalysisTransactionScreening`". This action is for when you just want the KYT analysis rule to be run, and then if triggered, those result returned in a `policy.triggered` [Webhook Event](https://docs.dfns.co/api-reference/webhook-events). ```json { "action": { "kind": "NoAction" } } ``` title: NoAction filters: type: object properties: walletId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false walletTags: type: object properties: hasAny: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 hasAll: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 additionalProperties: false additionalProperties: false required: - name - activityKind - rule - action additionalProperties: false description: > A "`Wallets:Sign`" activity represents any activity which involves signing with a wallet. Currently, in our API, these can be: * a Transfer Request (created using the endpoint [Transfer Asset from Wallet](https://docs.dfns.co/api-reference/wallets/transfer-asset)) * a Transaction Request (created using the endpoint [Broadcast Transaction from Wallet](https://docs.dfns.co/api-reference/wallets/sign-and-broadcast-transaction)) * a Signature Request (created using the endpoint [Generate Signature from Wallet](https://docs.dfns.co/api-reference/keys/generate-signature)) title: Wallets:Sign - type: object properties: name: type: string activityKind: type: string enum: - Wallets:IncomingTransaction rule: oneOf: - type: object properties: kind: type: string enum: - ChainalysisTransactionScreening configuration: type: object properties: alerts: type: object properties: alertLevel: type: string enum: - LOW - MEDIUM - HIGH - SEVERE categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - alertLevel - categoryIds exposures: type: object properties: direct: type: object properties: categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - categoryIds required: - direct userIdTemplate: type: string minLength: 1 maxLength: 50 pattern: >- ^([a-zA-Z0-9_:-]|{wallet\.id}|{wallet\.externalId})+$ default: dfns description: >- Value sent to Chainalysis as the "user ID". Used by Chainalysis for grouping transaction screenings. This template can include variables, included in brackets. The following variables are currently supported: `{wallet.id}` and `{wallet.externalId}`. As an example, if you set `userIdTemplate: "dfns:{wallet.id}_{wallet.externalId}"`, when your wallet receives a transaction that gets screened by a Chainalysis policy, the "user ID" sent to Chainalysis will be `dfns:wa-xxx_yyy` (`wa-xxx` being the wallet ID, and `yyy` being the wallet external ID). fallbackBehaviours: type: object properties: skipUnscreenableTransaction: type: boolean skipUnsupportedNetwork: type: boolean skipUnsupportedAsset: type: boolean skipChainalysisFailure: type: boolean required: - skipUnscreenableTransaction - skipUnsupportedNetwork - skipUnsupportedAsset - skipChainalysisFailure required: - alerts - exposures - fallbackBehaviours additionalProperties: false required: - kind - configuration additionalProperties: false description: > This rule can only be used once the Chainalysis integration is activated from the Dfns dashboard settings. (see more on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) integration page). This rule can be used on a policy of `activityKind` = `Wallets:IncomingTransaction`, and with the action kind `NoAction`. It's a rule based on Chainalysis KYT integration (Know-Your-Transaction). Upon an incoming transaction detectedby our indexers, we will [register the transfer with Chainalysis](https://docs.chainalysis.com/api/kyt/#registration-register-a-transfer), and fetch the results of the analysis (alerts & exposures detected). Based on the results, and the configuration of this rule, the policy will be triggered. The shape of the rule is almost like the `ChainalysisTransactionPrescreening` rule, expect the the `address` property is not supported. ```json { "rule": { "kind": "ChainalysisTransactionPrescreening", "configuration": { "alerts": { "alertLevel": "LOW", "categoryIds": [] }, "exposures": { "direct": { "categoryIds": [] } }, "fallbackBehaviours": { "skipUnscreenableTransaction": false, "skipUnsupportedNetwork": false, "skipUnsupportedAsset": false, "skipChainalysisFailure": false } } } } ``` **Configuration** Please refer to the configuration for the `ChainalysisTransactionPrescreening` rule. title: ChainalysisTransactionScreening action: oneOf: - type: object properties: kind: type: string enum: - NoAction required: - kind additionalProperties: false description: |2- This action kind means that nothing will happen after policy rule evaluation. It's meant to be used with policy rules "`ChainalysisTransactionPrescreening`" or "`ChainalysisTransactionScreening`". This action is for when you just want the KYT analysis rule to be run, and then if triggered, those result returned in a `policy.triggered` [Webhook Event](https://docs.dfns.co/api-reference/webhook-events). ```json { "action": { "kind": "NoAction" } } ``` title: NoAction filters: type: object properties: walletId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false walletTags: type: object properties: hasAny: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 hasAll: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 additionalProperties: false additionalProperties: false required: - name - activityKind - rule - action additionalProperties: false description: >- A "`Wallets:IncomingTransaction`" activity represents when our indexers detected an incoming transaction into a wallet. This activity kind has to be used with the rule kind "`ChainalysisTransactionScreening`" (see more on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) integration page), and the action kind "`NoAction`", meaning that no actual action will be taken as a result of the Chainalysis screening, other than notifying you through a webhook event if the policy is triggered. The reason for that, is that the incoming transaction is already on-chain, so the funds are already in the wallet, we cannot block that transfer on chain. title: Wallets:IncomingTransaction examples: Chainalysis Transaction Prescreening: value: name: chainalysis prescreening policy activityKind: Wallets:Sign rule: kind: ChainalysisTransactionPrescreening configuration: alerts: alertLevel: LOW categoryIds: [] exposures: direct: categoryIds: [] addresses: alertLevel: LOW categoryIds: [] fallbackBehaviours: skipUnscreenableTransaction: false skipUnsupportedNetwork: false skipUnsupportedAsset: false skipChainalysisFailure: false action: kind: Block filters: walletId: in: - wa-4sql3-a6ct4-8j2q8ih86d853rgg - wa-j9btt-5s9o8-i3r8373ddg0usn3 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Policy' security: - authenticationToken: [] userActionSignature: [] components: schemas: Policy: oneOf: - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Registry:Addresses:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: {} required: - id - name - status - activityKind - rule - action additionalProperties: false title: Registry:Addresses:Modify - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Permissions:Assign rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: permissionId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false required: - permissionId additionalProperties: false required: - id - name - status - activityKind - rule - action additionalProperties: false title: Permissions:Assign - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Permissions:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: permissionId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false required: - permissionId additionalProperties: false required: - id - name - status - activityKind - rule - action additionalProperties: false title: Permissions:Modify - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Policies:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval filters: type: object properties: policyId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false required: - policyId additionalProperties: false required: - id - name - status - activityKind - rule - action additionalProperties: false title: Policies:Modify - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Registry:ContractSchemas:Modify rule: type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block filters: type: object properties: {} required: - id - name - status - activityKind - rule - action additionalProperties: false title: Registry:ContractSchemas:Modify - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Wallets:Sign rule: oneOf: - type: object properties: kind: type: string enum: - AlwaysTrigger configuration: type: object properties: {} additionalProperties: false required: - kind additionalProperties: false description: >- This rule will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details. title: AlwaysTrigger - type: object properties: kind: type: string enum: - TransactionRecipientWhitelist configuration: type: object properties: addresses: type: array items: type: string minLength: 1 description: Whitelisted recipient addresses required: - addresses additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the destination address *is NOT whitelisted*. title: TransactionRecipientWhitelist - type: object properties: kind: type: string enum: - TransactionAmountLimit configuration: type: object properties: limit: type: number description: Amount limit in `currency` currency: type: string enum: - USD description: Fiat currency, currently only `USD` required: - limit - currency additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the wallet activity detected is transferring some value which amount is greater than a given limit. Note: If the fiat amount of the wallet activity cannot be evaluated for any reason (eg. market prices are not available, or eg. the amount cannot be inferred from a wallet signature request, etc.), by default the rule will trigger the policy (this is called "failing closed" and is generally considered a security best practice). title: TransactionAmountLimit - type: object properties: kind: type: string enum: - TransactionAmountVelocity configuration: type: object properties: limit: type: number description: Amount limit in `currency` currency: type: string enum: - USD description: Currency for the amount limit above timeframe: type: integer minimum: 1 maximum: 43200 description: Time period in minutes. Minimum 1, Maximum 43,200. required: - limit - currency - timeframe additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the cumulative amount transferred from a given wallet within a given timeframe is greater than a specified limit. The aggregate amount evaluated is based only on the wallet that triggered the policy. title: TransactionAmountVelocity - type: object properties: kind: type: string enum: - TransactionCountVelocity configuration: type: object properties: limit: type: number description: Count limit timeframe: type: integer minimum: 1 maximum: 43200 description: Time period in minutes. Minimum 1, Maximum 43,200. required: - limit - timeframe additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule will trigger if the number of wallet activities for a given wallet within a given timeframe, is greater than a specified limit. The aggregate number of transactions evaluated is based only on the wallet that triggered the policy. title: TransactionCountVelocity - type: object properties: kind: type: string enum: - ChainalysisTransactionPrescreening configuration: type: object properties: alerts: type: object properties: alertLevel: type: string enum: - LOW - MEDIUM - HIGH - SEVERE categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - alertLevel - categoryIds exposures: type: object properties: direct: type: object properties: categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - categoryIds required: - direct addresses: type: object properties: categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - categoryIds userIdTemplate: type: string minLength: 1 maxLength: 50 pattern: >- ^([a-zA-Z0-9_:-]|{wallet\.id}|{wallet\.externalId})+$ default: dfns description: >- Value sent to Chainalysis as the "user ID". Used by Chainalysis for grouping transaction screenings. This template can include variables, included in brackets. The following variables are currently supported: `{wallet.id}` and `{wallet.externalId}`. As an example, if you set `userIdTemplate: "dfns:{wallet.id}_{wallet.externalId}"`, when your wallet receives a transaction that gets screened by a Chainalysis policy, the "user ID" sent to Chainalysis will be `dfns:wa-xxx_yyy` (`wa-xxx` being the wallet ID, and `yyy` being the wallet external ID). fallbackBehaviours: type: object properties: skipUnscreenableTransaction: type: boolean skipUnsupportedNetwork: type: boolean skipUnsupportedAsset: type: boolean skipChainalysisFailure: type: boolean required: - skipUnscreenableTransaction - skipUnsupportedNetwork - skipUnsupportedAsset - skipChainalysisFailure required: - alerts - exposures - addresses - fallbackBehaviours additionalProperties: false required: - kind - configuration additionalProperties: false description: >+ This rule can only be used once the Chainalysis integration is activated from the Dfns dashboard settings. (see more on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) integration page). It's a rule based on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) KYT integration (Know-Your-Transaction). Upon transfer attempt, we will first register the transfer with Chainalysis (as a ["withdrawal attempt"](https://docs.chainalysis.com/api/kyt/#registration-register-a-withdrawal-attempt)), and fetch the screening results (alerts, exposures, addresses detected). Based on the results, and the configuration of this rule, the policy will be triggered. It's called "Pre"-screening, because the scanned transaction is not on chain yet, it's still a transaction attempt (before the transaction actually make it on chain). ```json { "rule": { "kind": "ChainalysisTransactionPrescreening", "configuration": { "alerts": { "alertLevel": "LOW", "categoryIds": [] }, "exposures": { "direct": { "categoryIds": [] } }, "addresses": { "categoryIds": [] }, "fallbackBehaviours": { "skipUnscreenableTransaction": false, "skipUnsupportedNetwork": false, "skipUnsupportedAsset": false, "skipChainalysisFailure": false } } } } ``` **Configuration** | Property | Type | Description | | --- | --- | --- | | `alerts`

`.alertLevel`* | `string` | Minimum alert level above which the rule should trigger, if any [alert is returned in Chainalysis results](https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-alerts). Can be `LOW`, `MEDIUM`, `HIGH`, or `SEVERE` | | `alerts`

`.categoryIds`* | list of integers | List of Chainalysis category IDs (see [here](https://docs.chainalysis.com/api/kyt/#categories)). If you leave this list empty, alerts of any category will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list. | | `exposures`

`.direct`

`.categoryIds`* | list of integers | List of Chainalysis category IDs (see [here](https://docs.chainalysis.com/api/kyt/#categories)). If you leave this list empty, a [direct exposure](https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-direct-exposure) of any category detected by chainalysis will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list. | | `addresses`

`.categoryIds`* | list of integers | List of Chainalysis category IDs (see [here](https://docs.chainalysis.com/api/kyt/#categories)). If you leave this list empty, an [address](https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-address-identifications) of any category identified by chainalysis will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list. | | `fallbackBehaviours`

`.skipUnscreenableTransaction`* | boolean | Behaviour if the wallet activity is not screenable (eg. if it's a signature request of a hash). If true, a transaction which is "unscreenable" will just be skipped, and policy will not trigger | | `fallbackBehaviours.skipUnsupportedNetwork`* | boolean | Behaviour if the wallet activity is on a network not supported by chainalysis, or not yet supported in the dfns-chainalysis integration. If true, an unsupported network will just be skipped, and policy will not trigger | | `fallbackBehaviours.skipUnsupportedAsset`* | boolean | Behaviour if the wallet activity is with a asset not supported by chainalysis, or not yet supported in the dfns-chainalysis integration. If true, an unsupported asset will just be skipped, and policy will not trigger | | `fallbackBehaviours.skipChainalysisFailure`* | boolean | Behaviour if any issue with Chainalysis calls (timeout, results took too long, rate limiting errors, any error). If true, will skip if any error happens | title: ChainalysisTransactionPrescreening - type: object properties: kind: type: string enum: - GlobalLedgerTransactionPrescreening configuration: type: object properties: riskScoreThreshold: type: integer minimum: 0 maximum: 100 description: >- Risk score threshold (0-100). Policy triggers if address/transaction risk score >= threshold fallbackBehaviours: type: object properties: skipUnscreenableTransaction: type: boolean description: >- skip all wallet requests that cannot be screened (eg. raw signatures) skipUnsupportedNetwork: type: boolean description: >- skip transfer requests to a network not supported yet in our GlobalLedger integration skipUnsupportedAsset: type: boolean description: >- skip transfer requests of an asset not supported by our GlobalLedger integration skipGlobalLedgerFailure: type: boolean description: skips any errors from GlobalLedger API request required: - skipUnscreenableTransaction - skipUnsupportedNetwork - skipUnsupportedAsset - skipGlobalLedgerFailure required: - riskScoreThreshold - fallbackBehaviours additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule uses GlobalLedger KYT for pre-screening outgoing transfers by checking the destination address risk score. Upon transfer attempt, we will query GlobalLedger's address risk API, and check if the risk score (0-100) is at or above the configured threshold, or if any alerts show up. If so, the policy will be triggered. It's called "Pre"-screening, because the scanned transaction is not on chain yet, it's still a transaction attempt. title: GlobalLedgerTransactionPrescreening - type: object properties: kind: type: string enum: - TravelRuleTransactionPrescreening configuration: type: object properties: vendor: type: string enum: - Notabene autoTriggerTimeoutSeconds: type: integer minimum: 0 autoClearAfterDeliveredTimeoutSeconds: type: integer minimum: 0 required: - vendor - autoTriggerTimeoutSeconds additionalProperties: false required: - kind - configuration additionalProperties: false description: >- This rule can only be used once the Notabene integration is activated from the Dfns dashboard settings (see more on [Notabene](https://docs.dfns.co/integrations/travel-rule/notabene) integration page). It's a rule based on [Notabene](https://docs.dfns.co/integrations/travel-rule/notabene) [TravelRule](https://docs.dfns.co/integrations/travel-rule) integration. It ***ONLY*** applies to Dfns [Transfer Asset](https://docs.dfns.co/api-reference/wallets/transfer-asset) Api Calls. It is NOT supported for Transfers initiated via the dashboard. Upon transfer attempt with an optional [TravelRule](https://docs.dfns.co/api-reference/wallets/transfer-asset#body-travel-rule) payload, we will call Notabene's APIs on your behalf to both confirm the validity of the travel rule message and submit it for processing. Dfns then waits for a response from the counterparty (for custodial transfers) or Notabene (for non-custodial transfers). It's called "Pre"-screening, because the transaction is not on chain yet, it's still a transaction attempt (before the transaction actually make it on chain). title: TravelRuleTransactionPrescreening action: oneOf: - type: object properties: kind: type: string enum: - RequestApproval approvalGroups: type: array items: type: object properties: name: type: string quorum: type: integer minimum: 1 approvers: type: object properties: userId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false additionalProperties: false initiatorCanApprove: type: boolean description: >- Whether the initiator of the activity can participate in the approval. serviceAccountsCanApprove: type: boolean description: >- Whether service accounts can participate in the approval for this group. required: - quorum - approvers additionalProperties: false minItems: 1 autoRejectTimeout: type: - integer - 'null' minimum: 1 required: - kind - approvalGroups additionalProperties: false description: >- This action means that activity will first require an Approval process to be completed before it can be executed (or be aborted if someone rejects it during the approval process). One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity. The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed. The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users. ```json { "action": { "kind": "RequestApproval", "autoRejectTimeout": 60, // minutes "approvalGroups": [ { "name": "Admins", "quorum": 2, // only 2 approvers required in that group "approvers": { "userId": { "in": ["us-...1", "us-...2", "us-...3"], } } } ], } } ``` **Don't lock yourself up** By default, users cannot approve an activity they initiated themselves, even if they are in an approval group. To allow this, you must set `initiatorCanApprove: true`. *Example 1:* For any wallet transfer, a policy is setup to require approval from **1 specific admin user** (eg. the CEO). `initiatorCanApprove` was not set to `true`. If the CEO himself initiates a transfer, no-one can approve his transfer and it's stuck. *Example 2:* Company has only 3 users. A policy is setup to require approval from **any 3 users** (`quorum: 3`) for any modification of a policy. `initiatorCanApprove` was not set to `true`. In this case, they are locked, and the policy cannot be modified: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. To unlock, they would need to invite a new user and give him the rights to approve as well. title: RequestApproval - type: object properties: kind: type: string enum: - Block required: - kind additionalProperties: false description: > This action means that the activity will be blocked if the policy is triggered. ```json { "action": { "kind": "Block" } } ``` title: Block - type: object properties: kind: type: string enum: - NoAction required: - kind additionalProperties: false description: |2- This action kind means that nothing will happen after policy rule evaluation. It's meant to be used with policy rules "`ChainalysisTransactionPrescreening`" or "`ChainalysisTransactionScreening`". This action is for when you just want the KYT analysis rule to be run, and then if triggered, those result returned in a `policy.triggered` [Webhook Event](https://docs.dfns.co/api-reference/webhook-events). ```json { "action": { "kind": "NoAction" } } ``` title: NoAction filters: type: object properties: walletId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false walletTags: type: object properties: hasAny: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 hasAll: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 additionalProperties: false additionalProperties: false required: - id - name - status - activityKind - rule - action additionalProperties: false title: Wallets:Sign - type: object properties: id: type: string name: type: string status: type: string enum: - Active - Archived dateCreated: type: string dateUpdated: type: string activityKind: type: string enum: - Wallets:IncomingTransaction rule: oneOf: - type: object properties: kind: type: string enum: - ChainalysisTransactionScreening configuration: type: object properties: alerts: type: object properties: alertLevel: type: string enum: - LOW - MEDIUM - HIGH - SEVERE categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - alertLevel - categoryIds exposures: type: object properties: direct: type: object properties: categoryIds: type: array items: type: integer exclusiveMinimum: 0 required: - categoryIds required: - direct userIdTemplate: type: string minLength: 1 maxLength: 50 pattern: >- ^([a-zA-Z0-9_:-]|{wallet\.id}|{wallet\.externalId})+$ default: dfns description: >- Value sent to Chainalysis as the "user ID". Used by Chainalysis for grouping transaction screenings. This template can include variables, included in brackets. The following variables are currently supported: `{wallet.id}` and `{wallet.externalId}`. As an example, if you set `userIdTemplate: "dfns:{wallet.id}_{wallet.externalId}"`, when your wallet receives a transaction that gets screened by a Chainalysis policy, the "user ID" sent to Chainalysis will be `dfns:wa-xxx_yyy` (`wa-xxx` being the wallet ID, and `yyy` being the wallet external ID). fallbackBehaviours: type: object properties: skipUnscreenableTransaction: type: boolean skipUnsupportedNetwork: type: boolean skipUnsupportedAsset: type: boolean skipChainalysisFailure: type: boolean required: - skipUnscreenableTransaction - skipUnsupportedNetwork - skipUnsupportedAsset - skipChainalysisFailure required: - alerts - exposures - fallbackBehaviours additionalProperties: false required: - kind - configuration additionalProperties: false description: > This rule can only be used once the Chainalysis integration is activated from the Dfns dashboard settings. (see more on [Chainalysis](https://docs.dfns.co/integrations/aml-kyt/chainalysis) integration page). This rule can be used on a policy of `activityKind` = `Wallets:IncomingTransaction`, and with the action kind `NoAction`. It's a rule based on Chainalysis KYT integration (Know-Your-Transaction). Upon an incoming transaction detectedby our indexers, we will [register the transfer with Chainalysis](https://docs.chainalysis.com/api/kyt/#registration-register-a-transfer), and fetch the results of the analysis (alerts & exposures detected). Based on the results, and the configuration of this rule, the policy will be triggered. The shape of the rule is almost like the `ChainalysisTransactionPrescreening` rule, expect the the `address` property is not supported. ```json { "rule": { "kind": "ChainalysisTransactionPrescreening", "configuration": { "alerts": { "alertLevel": "LOW", "categoryIds": [] }, "exposures": { "direct": { "categoryIds": [] } }, "fallbackBehaviours": { "skipUnscreenableTransaction": false, "skipUnsupportedNetwork": false, "skipUnsupportedAsset": false, "skipChainalysisFailure": false } } } } ``` **Configuration** Please refer to the configuration for the `ChainalysisTransactionPrescreening` rule. title: ChainalysisTransactionScreening action: oneOf: - type: object properties: kind: type: string enum: - NoAction required: - kind additionalProperties: false description: |2- This action kind means that nothing will happen after policy rule evaluation. It's meant to be used with policy rules "`ChainalysisTransactionPrescreening`" or "`ChainalysisTransactionScreening`". This action is for when you just want the KYT analysis rule to be run, and then if triggered, those result returned in a `policy.triggered` [Webhook Event](https://docs.dfns.co/api-reference/webhook-events). ```json { "action": { "kind": "NoAction" } } ``` title: NoAction filters: type: object properties: walletId: type: object properties: in: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 required: - in additionalProperties: false walletTags: type: object properties: hasAny: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 hasAll: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 additionalProperties: false additionalProperties: false required: - id - name - status - activityKind - rule - action additionalProperties: false title: Wallets:IncomingTransaction securitySchemes: authenticationToken: type: http scheme: bearer bearerFormat: JWT description: >- **Bearer Token:** Used to authenticate API requests. More details how to generate the token: [Authentication flows](https://docs.dfns.co/api-reference/auth/login-flows) userActionSignature: type: apiKey in: header name: X-DFNS-USERACTION description: >- **User Action Signature:** Used to sign the change-inducing API requests. More details how to generate the token: [User Action Signing flows](https://docs.dfns.co/api-reference/auth/signing-flows) ````