Onboarding

External checks let a policy rule require a decision from an external provider before it contributes to the final policy decision. They extend transaction policies with specialized business and compliance decisions, including transaction screening, KYC status, Travel Rule approval, and fraud detection.

The rule contributes its deny or allow action only when its external checks pass.

Participants

Participant	Role
Client application	Discovers external provider integrations, defines policies, and submits signing requests
Deployment operator	Team that deploys the MPC nodes and configures the available external provider integrations
MPC node	One MPC signing participant. It evaluates the policy and executes requested checks through policy-integration
Policy engine	Matches transaction conditions, identifies checks required by matched rules, and decides the policy after receiving their results
policy-integration	Resolves provider integration to perform HTTP calls to external providers, and validates the responses
External provider	Customer-operated or third-party service that returns pass or fail for a requested check

Every selected MPC node evaluates the policy and calls the configured provider independently.

Add an external check

1. Discover available integrations

Client applications can discover the provider integrations catalog through the public GET endpoint:

curl -X GET "http://<YOUR_WALLET_BACKEND_ENDPOINT>/v2/rest/getPolicyIntegrations"

Example response:

{
  "integrations": [
    {
      "integration_id": "transaction-screening",
      "operations": [
        {
          "operation": "screen-destination-address",
          "description": "Screen a transaction destination address for compliance risk",
          "payload_projection": {
            "context": ["/address"]
          }
        }
      ]
    }
  ]
}

The endpoint returns an IntegrationCatalog struct. It tells policy authors available external checks.

Field	Description
integration_id	Stable identifier used by a policy to select an integration. One integration can offer multiple operations
operation	Identifier used by a policy to select a capability of the external provider
description	Human-readable explanation of the operation
payload_projection	Transaction or client-context fields sent to the operation

The catalog defines the external capabilities available to policies. Use its integration_id and operation values when defining an ExternalCheck in the next step. See Policy Integrations for how these capabilities are registered and translated into provider requests.

2. Add the check to a Rule

Each Rule in a Policy can have its own set of external checks. Example:

{
  "description": "Allow transfers that pass destination screening",
  "issuer": [{ "type": "UserId", "id": "alice" }],
  "action": "allow",
  "chain_type": "ethereum",
  "conditions": [
    {
      "transaction_type": "nativeTransfer",
      "transaction_attr": "nativeValue",
      "operator": "lte",
      "value": 1000
    }
  ],
  "external_checks": {
    "logic": "and",
    "checks": [
      {
        "check_id": "550e8400-e29b-41d4-a716-446655440000",
        "integration_id": "transaction-screening",
        "operation": "screen-destination-address",
        "duration_ms": 3000
      }
    ]
  }
}

Each entry in external_checks.checks is an ExternalCheck struct.

Field	Description
check_id	Client-generated identifier used to distinguish this check within the policy; must be unique
integration_id	Selects an integration from the catalog
operation	Selects one operation offered by that integration
duration_ms	Maximum time allowed for the provider check

integration_id and operation identify an operation of the integrated provider that exposed by the catalog; logic controls how check results are combined:

• "and" requires every check to pass.
• "or" requires at least one.

An external-check failure means the owning rule does not match. Normal policy resolution still applies.

3. Supply request-specific context

The deployment operator configures which context fields each external provider operation receives through payload_projection on every MPC node:

{
  "operation": "screen-destination-address",
  "description": "Screen a transaction destination address for compliance risk",
  "payload_projection": {
    "context": ["/address"]
  }
}

/address is an RFC 6901 JSON Pointer into the policy_integration_context object. It declares that this operation may receive the value at address. The projection belongs to the deployment registry, not the policy.

The client supplies provider integration context as a stringified, non-empty JSON object in the authenticated signing request:

const policyIntegrationContext = JSON.stringify({
  address: destinationAddress,
});

await sdk.signMessage(
  threshold,
  selectedKeyId,
  'secp256k1',
  signMessage,
  policyIntegrationContext,
);

The authenticated context reaches every selected MPC node; policy-integration applies the operation's projection and copies /address into the provider request:

{
  "version": "1",
  "evaluation_id": "5d10...",
  "operation": "screen-destination-address",
  "context": {
    "address": "0x1234..."
  }
}

If /address is missing from the source context, request construction fails closed before being sent to the provider. See Policy Integrations for transaction projections and nested JSON Pointer paths.

End-to-end evaluation flow

The engine plans external checks only for rules that satisfy its conditions; then policy-integration converts each external provider response into a standard check result:

• A valid response becomes Decision(pass | fail, reason_code?).
• A request or validation failure becomes Unavailable(category).

The engine uses these results to resume Rule evaluation. An unavailable required check will fail the evaluation.