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

# Managed investment accounts

> Architecture for a discretionary investment platform with per-client approved destinations, audit visibility, and automated order execution to an exchange.

Build a managed accounts platform where your company holds and operates crypto wallets on behalf of clients. Each client gets per-account transfer restrictions that control where funds can go: approved destinations, spending limits, and velocity controls. Clients can view the rules governing their account, request changes to their approved destinations, and audit all activity. Your service account handles order execution, including routing funds to an exchange for discretionary trading.

## Overview

```mermaid theme={null}
flowchart TD
    A["Your frontend<br/>(user login, dashboard)"] --> B["Your backend<br/>• User auth<br/>• User↔Wallet DB<br/>• Dfns service account<br/>• Whitelist requests"]
    B --> C["Dfns API<br/>• Wallets<br/>• Policies<br/>• Activity"]
    B --> D["Exchange<br/>• Deposit address"]
```

Your backend owns a Dfns [service account](/guides/developers/service-account). Clients never interact with Dfns directly.

| Component            | Role                                                             |
| -------------------- | ---------------------------------------------------------------- |
| Your auth system     | Client login and identity (Auth0, Cognito, custom)               |
| Your database        | Maps clients to wallet IDs, stores destination approval requests |
| Dfns service account | Creates wallets, executes orders, manages policies               |
| Dfns policies        | Per-client approved destinations via wallet tags                 |
| Dfns activity logs   | Transaction history and audit trail                              |
| Exchange             | External trading venue (e.g., Gemini, Coinbase)                  |

## What you'll need

* A [Dfns account](https://app.dfns.io) with a [service account](/guides/developers/service-account)
* Understanding of [policies](/core-concepts/policies), specifically the [`TransactionRecipientWhitelist`](/api-reference/policies#transactionrecipientwhitelist-policy-rule) rule
* Understanding of [wallet tags](/api-reference/wallets/tag-wallet)
* An authentication system for your clients
* A database for client-to-wallet mapping and destination approval requests

## Architecture

### 1. Client onboarding and account creation

When a client signs up on your platform:

1. Your backend authenticates the client through your own auth system
2. Your backend calls Dfns to [create a wallet](/guides/developers/create-wallets) using the service account
3. Your backend [tags the wallet](/api-reference/wallets/tag-wallet) with a client-specific tag (e.g., `client:<client-id>`)
4. Your database stores the mapping between the client and their Dfns wallet ID

```mermaid theme={null}
flowchart LR
    A[Client signs up] --> B[Backend creates wallet] --> C["Tags wallet client:abc123"] --> D[Stores mapping in DB]
```

<Tip>
  Use a consistent tag naming convention like `client:<client-id>`. This lets you target policies to specific client wallets using [policy filters](/api-reference/policies#policy-filters).
</Tip>

The client sees a wallet address in their dashboard. They don't know about Dfns, tags, or service accounts, just that they have a managed account at your company.

### 2. Per-client approved destinations

Approved destinations are implemented as Dfns [`TransactionRecipientWhitelist`](/api-reference/policies#transactionrecipientwhitelist-policy-rule) policies, one per client wallet, restricting transfers to a list of addresses the client has explicitly approved. For your clients, this is the core trust mechanism of the managed account relationship: even your company cannot send their funds to arbitrary addresses.

```mermaid theme={null}
flowchart LR
    A[Client requests order execution] --> B[Service account initiates transfer]
    B --> C{Client's approved destinations policy}
    C -->|Destination approved| D[Funds sent to exchange]
    C -->|Destination not approved| E[Blocked or requires approval]
```

Each policy targets a client's wallet via their tag and contains:

* **Rule**: `TransactionRecipientWhitelist`, the list of approved destinations
* **Action**: `Block` entirely, or `RequestApproval`. If the destination is not approved, require review from your compliance team
* **Filter**: `walletTags: hasAll ["client:abc123"]`, scopes the policy to that client's wallets only

Transfers to approved destinations proceed without intervention. Transfers to unapproved addresses are either blocked or trigger review from your compliance team.

<Warning>
  EVM address comparison in whitelist rules is case sensitive. Always use lowercase addresses. See the [policy reference](/api-reference/policies#transactionrecipientwhitelist-policy-rule) for details.
</Warning>

See [creating policies](/guides/create-policies) for the dashboard workflow or [managing policies via API](/guides/developers/manage-policies) for programmatic setup.

### 3. Destination approval flow

When a client requests to add a new approved destination:

```mermaid theme={null}
flowchart LR
    A[Client requests new destination] --> B[Your backend stores request]
    B --> C[Service account calls Update Policy<br/>to add destination]
    C --> D{Policies:Modify policy triggered}
    D --> E[Compliance officer reviews<br/>the destination change]
    E -->|Approve| F[Policy updated,<br/>destination is now approved]
    E -->|Reject| G[Change rejected,<br/>approved destinations unchanged]
```

This flow uses two layers:

**Layer 1, Your application**: The client submits a request through your UI. Your backend stores it and calls the Dfns [Update Policy](/api-reference/policies/update-policy) endpoint via the service account to add the new address.

**Layer 2, Dfns policy on policy changes**: Create a [`Policies:Modify`](/api-reference/policies#policies-modify-activity) policy that requires a compliance officer to approve any destination policy update:

* **Activity**: `Policies:Modify`, triggers on any policy update or deletion
* **Rule**: `AlwaysTrigger`, every modification requires approval, no exceptions
* **Action**: `RequestApproval`, a compliance officer must approve before the change takes effect

Every destination change, regardless of which client it's for, requires human review from your team before taking effect.

<Tip>
  You can scope this policy to specific destination policies using the `policyId` filter if you want different approval rules for different types of policy changes.
</Tip>

### 4. Client reporting and transparency

Clients should be able to verify that your company is operating within the agreed investment restrictions. Two Dfns data sources make this possible:

**Account restrictions**: Use [List Policies](/api-reference/policies/list-policies) to retrieve the policies that apply to a client's wallets. Filter by the client's wallet tag or wallet ID to show only relevant policies.

| What to show                 | Where it comes from                                |
| ---------------------------- | -------------------------------------------------- |
| Approved destinations        | `TransactionRecipientWhitelist` rule configuration |
| Spending limits (if any)     | `TransactionAmountLimit` rule configuration        |
| Pending destination requests | Your database (application-level)                  |

**Activity and audit trail**: Use [Get Wallet History](/api-reference/wallets/get-wallet-history) for on-chain transactions (deposits, withdrawals, amounts, status) and [List Audit Logs](/api-reference/auth/list-audit-logs) for governance events (who initiated a transfer, policy approvals and rejections, destination changes).

Together, this gives clients a complete picture: which destinations are approved, what limits apply, and a full log of every action taken on their account. See [transaction monitoring](/guides/developers/transaction-monitoring) for implementation patterns including webhook-based status tracking.

### Putting it all together: discretionary trading

When a client authorizes you to execute trades on their behalf through an exchange, the full flow ties together every component above:

1. **Client grants trading authorization**: they want you to route funds to an exchange for a specific investment strategy
2. **Approve the exchange as a destination**: your service account submits the exchange deposit address to the client's approved destinations (step 3). A compliance officer reviews and approves the addition
3. **Execute orders**: your service account calls [Transfer Asset](/api-reference/wallets/transfer-asset) to move funds from the client's wallet to the exchange. The destination policy allows the transfer; any additional policies (spending limits, velocity controls) still apply
4. **Client has visibility**: the client can see the exchange address in their approved destinations and track every transfer in their activity dashboard (step 4)

```mermaid theme={null}
flowchart LR
    A[Client authorizes trading] --> B[Exchange added to<br/>approved destinations]
    B --> C{Compliance officer approves?}
    C -->|Yes| D[Service account executes orders]
    C -->|No| E[Request rejected]
    D --> F[Destination policy validates<br/>recipient address]
    F --> G[Spending/velocity policies<br/>validate amount]
    G --> H[Funds arrive at exchange]
```

You can layer additional policies on top of the approved destinations to control trading activity:

| Policy                      | Purpose                                     |
| --------------------------- | ------------------------------------------- |
| `TransactionAmountLimit`    | Cap single transfer amounts to the exchange |
| `TransactionAmountVelocity` | Limit total value transferred per day       |
| `TransactionCountVelocity`  | Limit number of transfers per time window   |

<Warning>
  Never grant [approval permissions](/core-concepts/roles-and-permissions) to service accounts. Keep automation and approval authority separate.
</Warning>

## Implementation checklist

<Steps>
  <Step title="Set up Dfns service account">
    Create a [service account](/guides/developers/service-account) with the permissions listed above. Store credentials securely in your backend.
  </Step>

  <Step title="Build client-to-wallet mapping">
    When clients sign up, create a Dfns wallet, tag it with `client:<client-id>`, and store the wallet ID in your database alongside the client record.
  </Step>

  <Step title="Create per-client destination policies">
    For each new client wallet, create a `TransactionRecipientWhitelist` policy filtered by their wallet tag. Start with an empty list or pre-approved destinations.
  </Step>

  <Step title="Create the policy modification policy">
    Create a `Policies:Modify` policy with `AlwaysTrigger` that requires a compliance officer to approve destination changes. This is a one-time setup.
  </Step>

  <Step title="Build the destination approval flow">
    In your UI, let clients submit new destinations. Your backend stores the request, calls Dfns Update Policy, and the approval flow handles the rest. Notify clients when their request is approved or rejected.
  </Step>

  <Step title="Build client reporting">
    Use the Dfns wallet history and audit log endpoints to show clients their transaction history, account restrictions, and policy events.
  </Step>

  <Step title="Implement order execution">
    When clients authorize discretionary trading, add the exchange deposit address to their approved destinations (with approval), then use the service account to execute orders on a schedule or trigger.
  </Step>
</Steps>

## Related solutions

<CardGroup cols={2}>
  <Card title="Accept cryptocurrencies" icon="building-columns" href="/solutions/accept-cryptocurrencies">
    Full custodial platform example with code
  </Card>

  <Card title="Define treasury policies" icon="shield-check" href="/solutions/define-treasury-policies">
    Policy configurations for spending controls
  </Card>

  <Card title="Automate payments" icon="robot" href="/solutions/automate-payments">
    Service account payment workflows
  </Card>

  <Card title="Govern wallet access" icon="folder-tree" href="/solutions/govern-wallet-access">
    Tags, roles, and organization patterns
  </Card>
</CardGroup>