Overview
Your backend owns a Dfns 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 with a service account
- Understanding of policies, specifically the
TransactionRecipientWhitelistrule - Understanding of wallet tags
- 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:- Your backend authenticates the client through your own auth system
- Your backend calls Dfns to create a wallet using the service account
- Your backend tags the wallet with a client-specific tag (e.g.,
client:<client-id>) - Your database stores the mapping between the client and their Dfns wallet ID
2. Per-client approved destinations
Approved destinations are implemented as DfnsTransactionRecipientWhitelist 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.
Each policy targets a client’s wallet via their tag and contains:
- Rule:
TransactionRecipientWhitelist— the list of approved destinations - Action:
Blockentirely, orRequestApproval— 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
3. Destination approval flow
When a client requests to add a new approved destination: 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 endpoint via the service account to add the new address. Layer 2 — Dfns policy on policy changes: Create aPolicies:Modify 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
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 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) |
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:- Client grants trading authorization — they want you to route funds to an exchange for a specific investment strategy
- 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
- Execute orders — your service account calls 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
- Client has visibility — the client can see the exchange address in their approved destinations and track every transfer in their activity dashboard (step 4)
| 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 |
Implementation checklist
Set up Dfns service account
Create a service account with the permissions listed above. Store credentials securely in your backend.
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.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.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.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.
Build client reporting
Use the Dfns wallet history and audit log endpoints to show clients their transaction history, account restrictions, and policy events.