diff --git a/docs.json b/docs.json index 9c87f6a5..d58bce35 100644 --- a/docs.json +++ b/docs.json @@ -171,6 +171,7 @@ "pages": [ "category/code-examples", "embedded-wallets/code-examples/embedded-consumer-wallet", + "products/embedded-business-wallets/overview", "embedded-wallets/code-examples/create-sub-org-passkey", "embedded-wallets/code-examples/authenticate-user-passkey", "embedded-wallets/code-examples/create-passkey-session", diff --git a/images/embedded-wallets/embedded-business-wallets.png b/images/embedded-wallets/embedded-business-wallets.png new file mode 100644 index 00000000..4cf3834b Binary files /dev/null and b/images/embedded-wallets/embedded-business-wallets.png differ diff --git a/products/embedded-business-wallets/overview.mdx b/products/embedded-business-wallets/overview.mdx new file mode 100644 index 00000000..2d821602 --- /dev/null +++ b/products/embedded-business-wallets/overview.mdx @@ -0,0 +1,300 @@ +--- +title: "Embedded Business Wallets" +description: "Use Turnkey's embedded wallet infrastructure for internal enterprise operations: treasury management, payroll automation, vendor payments, and organizational spending controls." +--- + +## Why Turnkey for Embedded Business Wallets? + +The same [Embedded Wallet Kit](/embedded-wallets/overview) that powers consumer applications works equally well for internal business operations such as treasury, payroll, vendor payments, and operational funds. + +Let Turnkey run your wallet infrastructure for business operations. Define who can sign, what they can sign, and how many approvals are required. Set spending limits and recipient allowlists. Private key material and sensitive operations are protected through Turnkey's [verifiable security architecture](/security/our-approach). + +Use the [policy engine](/concepts/policies/overview) to define your approval workflows. No contract deployments or on-chain coordination necessary. + +## Turnkey Solutions + +| Need | Turnkey solution | +| :--- | :--- | +| [Merchant deposit addresses](#example-merchant-deposit-addresses-with-automated-sweeping) | Instant wallet provisioning with policy-enforced sweeping to omnibus | +| [Contractor and vendor payments](#example-contractor-and-vendor-payments) | Contact lists with pre-approved addresses and spending limits | +| [Scheduled recurring payments](#example-scheduled-recurring-payments) | Scheduled payments to allowlisted recipients without manual signing | +| [Role Based Access Control](#example-role-based-access-control-rbac) | Grant limited payment authority to teams or individuals | +| [Multi-approval workflows](#example-multi-approval-workflows) | Require 2+ approvers for high-value transactions | +| [Spending controls](#example-spending-controls) | Per-transaction limits, asset restrictions, and role-based rules | + +## Core Capabilities + +**Instant wallet provisioning** +Create secure wallets programmatically during onboarding with familiar authentication and a white-labeled interface using [Embedded Wallet Kit](/embedded-wallets/overview). + +**Programmable approval requirements** +Define how many approvals each transaction type needs. For example, small payments auto-approve, large transfers require multiple signers. + +**Role-based access control (RBAC)** +Tag users as “finance-team” or “executive,” then use Turnkey's policy engine to grant specific permissions to those groups. + +**Recipient allowlists** +Maintain approved vendor and contractor addresses. Payments to known recipients can bypass additional approval steps. + +**Automated scheduled payments** +Backend services sign recurring transactions (payroll, subscriptions) based on policy rules. No manual intervention required. + +**Spending controls** +Enforce per-transaction maximums, asset restrictions, or destination restrictions at the policy level. + +**Transaction Management with Gas Sponsorship** +Sponsor gas fees and manage the transaction lifecycle end-to-end — construction, nonce sequencing, gas estimation and payment, signing, broadcast, and status tracking. See [Transaction Management](/concepts/transaction-management). + +--- + +## Example: Merchant Deposit Addresses with Automated Sweeping + +Provision deposit addresses instantly for merchants or customers. Enforce that funds can only move to your omnibus wallet, and only approved assets (like USDC) can be transferred. + +### Architecture + + + Embedded business wallets architecture showing wallet provisioning, policy engine, and omnibus sweeping + + +**Policy: Restrict transfers to USDC only, omnibus destination only** + +First, upload the USDC contract ABI as a [smart contract interface](/concepts/policies/smart-contract-interfaces) via the dashboard or API. Then create a policy that references the parsed contract call arguments: + +```json +{ + "policyName": "USDC transfers to omnibus only", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.tags.contains('sweep-service'))", + "condition": "wallet.id == '' && eth.tx.to == '' && eth.tx.function_name == 'transfer' && eth.tx.contract_call_args['_to'] == ''" +} +``` + +All other transfer attempts are implicitly denied, such as an incorrect token or destination. The policy engine enforces your rules at signing time. + +**Transaction flow:** +1. Create a unique merchant address instantly via API (~100ms) +2. Customer deposits funds to merchant's unique address +3. Backend sweep service lists balances across all merchant wallets +4. Sweep service signs transfers to omnibus wallet +5. Policy enforces USDC-only, omnibus-only at signing time + +## Example: Contractor and vendor payments + +Maintain a contact list of approved payment recipients. Store each contractor's preferred wallet address for USDC disbursements. + +**Set up recipient allowlist policy:** + +With the USDC ABI uploaded as a [smart contract interface](/concepts/policies/smart-contract-interfaces), you can restrict payments to approved recipients: + +```json +{ + "policyName": "Auto-approve payments to verified vendors", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.tags.contains('accounts-payable'))", + "condition": "wallet.id == '' && eth.tx.to == '' && eth.tx.function_name == 'transfer' && eth.tx.contract_call_args['_to'] in ['', '', '']" +} +``` + +Payments to known recipients execute with single approval. Add new vendors by updating the policy. No on-chain changes required. + +## Example: Scheduled recurring payments + +Set up automated payments that execute on a schedule without manual signing. Pay contractors on the last business day of each month for the next 6 months. + + + + Define recurring payments in your application: recipient, amount, frequency, duration. + + + Allow your backend service to sign transactions to specific recipients up to specified amounts: + + ```json + { + "policyName": "Backend can execute monthly contractor payments", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.id == '')", + "condition": "wallet.id == '' && eth.tx.to == '' && eth.tx.function_name == 'transfer' && eth.tx.contract_call_args['_to'] in ['', '']" + } + ``` + + + Your backend executes payments when due. No manual approval required for pre-authorized recipients and amounts. + + + +## Example: Role Based Access Control (RBAC) + +Grant limited payment permissions to individuals or teams without giving full wallet access. + +### Petty cash for operators + +```json +{ + "policyName": "Operators can make small purchases", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.tags.contains('operator'))", + "condition": "wallet.id == '' && activity.action == 'SIGN' && eth.tx.value <= 500000000000000000000" +} +``` + +### Contractor self-service withdrawals + +```json +{ + "policyName": "Contractor can withdraw earned funds to registered address", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.id == '')", + "condition": "wallet.id == '' && eth.tx.to == '' && eth.tx.value <= 2000000000000000000000" +} +``` + +### Department budgets + +Assign each department a spending limit. Marketing can spend up to $25k without executive approval: + +```json +{ + "policyName": "Marketing team budget authority", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.tags.contains('marketing-team'))", + "condition": "wallet.id == '' && activity.action == 'SIGN' && eth.tx.value <= 25000000000000000000000" +} +``` + +## Example: Multi-approval workflows + +Require multiple approvers for high-value or sensitive transactions. + +### Two finance approvers for large payments + +```json +{ + "policyName": "Require 2 finance approvers for transactions over $10,000", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.filter(user, user.tags.contains('finance-team')).count() >= 2", + "condition": "wallet.id == '' && activity.action == 'SIGN' && eth.tx.value > 10000000000000000000000" +} +``` + +### Executive approval for major transactions + +```json +{ + "policyName": "CFO required for transactions over $50,000", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.tags.contains('cfo'))", + "condition": "wallet.id == '' && activity.action == 'SIGN' && eth.tx.value > 50000000000000000000000" +} +``` + +## Example: Spending controls + +Implement organizational controls beyond simple approval requirements. + +| Control | Policy approach | +| :--- | :--- | +| **Per-transaction limits** | Set `eth.tx.value` ceiling in condition | +| **Recipient restrictions** | Allowlist addresses with `eth.tx.contract_call_args['_to'] in [...]` | +| **Role-based limits** | Different `consensus` rules per spending tier | +| **Asset restrictions** | Filter by contract address for token transfers | + +See [Policy Language](/concepts/policies/language) for the full syntax and [Access Control Examples](/concepts/policies/examples/access-control) for more patterns. + +## Example: Transaction management with gas sponsorship + +Use Turnkey's [transaction management](/concepts/transaction-management) to handle the full transaction lifecycle, including gas sponsorship so your users and backend services never need to hold native tokens for fees. + + + + Use `ethSendTransaction` with `sponsor: true` to send a USDC transfer on Base. Turnkey handles construction, nonce management, gas estimation, signing, and broadcast. + + ```ts + import { Turnkey } from "@turnkey/sdk-server"; + + const client = new Turnkey({ + apiBaseUrl: "https://api.turnkey.com/", + apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY, + apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY, + defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID, + }).apiClient(); + + const sendTransactionStatusId = await client.ethSendTransaction({ + transaction: { + from: walletAccount.address, + to: "", + caip2: "eip155:8453", // Base mainnet + sponsor: true, + value: "0", + data: "", + nonce: "0", + }, + }); + ``` + + + Monitor the transaction until it's included in a block or fails: + + ```ts + const pollResult = await client.pollTransactionStatus({ + sendTransactionStatusId, + }); + + const txHash = pollResult?.eth?.txHash; + console.log("Transaction:", `https://basescan.org/tx/${txHash}`); + ``` + + + Check your sponsorship spend against configured limits: + + ```ts + const resp = await client.getGasUsage({}); + if (resp?.usageUsd! > resp?.windowLimitUsd!) { + console.error("Gas usage limit exceeded"); + return; + } + ``` + + + +Policies apply to sponsored transactions the same way as standard transactions. Set `sponsor: false` (or omit the field) to have the sender pay gas instead. See [Transaction Management](/concepts/transaction-management) for the full conceptual overview. + +## Trusted by leading businesses + +Turnkey's infrastructure powers enterprise payment operations at scale. See [Turnkey Customers](https://www.turnkey.com/customers) for more examples. + +**[Mural Pay](https://www.turnkey.com/customers/mural-pay-cross-border-payments)**: Cross-border stablecoin payments for non-crypto-native organizations. + +| Metric | Value | +| :--- | :--- | +| Monthly stablecoin payments | 5,000+ | +| Transaction volume (12 months) | $200M+ | +| Integration time | 3 weeks | + +## Implementation workflow + + + + [Sign up for Turnkey](https://app.turnkey.com/dashboard/auth/initial) and create your parent organization. + + + Create wallets for your business operations: treasury, payroll, vendor payments. See [Wallets Concept](/concepts/wallets) for HD wallet structure. + + + Create user tags representing roles in your organization (finance, operations, executive). Add users and assign appropriate tags. + + + Write policies encoding your approval workflows and spending controls. See [Policy Quickstart](/concepts/policies/quickstart) for setup guidance. + + + Integrate Turnkey's API to build approval interfaces, payment automation, and operational dashboards. See [Transaction Automation](/signing-automation/overview) for backend signing patterns. + + + +## Resources + +- [Policy Engine Overview](/concepts/policies/overview): Fundamentals of Turnkey policies +- [Access Control Examples](/concepts/policies/examples/access-control): Sample RBAC policies +- [Signing Control Examples](/concepts/policies/examples/signing-control): Transaction signing policies +- [Delegated Access](/concepts/policies/delegated-access-overview): Backend automation patterns +- [Transaction Automation](/signing-automation/overview): Building automated signing workflows