Custody Modes

# Custody Modes

> Understand who controls signing, which payment flow to use, and what Conto can actually enforce

- Human URL: https://conto.finance/docs/guides/custody-modes
- Raw Markdown: https://conto.finance/docs/guides/custody-modes.md
- Terminal view: https://conto.finance/ai/docs/guides/custody-modes

Documentation group: Guides

# Custody Modes

Before you link a wallet, decide which custody mode you want. In Conto, these are two separate
questions:

1. **Custody**. Who can sign the transfer?
2. **Enforcement**. Can Conto actually stop the transfer, or only govern the path that goes
   through Conto?

## Quick Comparison

| Mode                                   | Signing control                             | Typical flow                             | Can Conto block a direct spend signed outside Conto?            | Best for                                         |
| -------------------------------------- | ------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
| **Managed** (`MANAGED`)                | Your selected root-control model plus Conto | `request -> execute`                     | Depends on the managed control model described below.           | Teams that want Conto-orchestrated execution     |
| **External / Watch-Only** (`EXTERNAL`) | You, your agent, or your wallet stack       | `approve -> transfer -> confirm`         | **No.** Conto only controls payments routed through Conto.      | Self-custody, MPC wallets, existing wallet tools |
| **Smart Contract** (`SMART_CONTRACT`)  | The contract's authorization rules          | `request -> contract execute -> confirm` | **Yes.** Transfers require the contract + Conto signature path. | Strongest onchain enforcement model              |

## What Policies Mean In Each Mode

### Managed Wallets

With a managed wallet, Privy's secure wallet infrastructure protects the key material. Conto does
not store the wallet's raw private key. Conto stays in its policy-gated execution path, and you
choose the root-control model for each new wallet.

- Conto evaluates the payment.
- If approved, Conto orchestrates execution.
- If denied, the payment does not execute through Conto.
- The agent uses the standard `request -> execute` flow.

Create a managed wallet in the dashboard or use `POST /api/wallets` with
`custodyMode=MANAGED`. You can set `controlModel` to `ORGANIZATION_CONTROLLED` or `CONTO_MANAGED`.
The selection is fixed for the new wallet; changing the organization default never migrates an
existing wallet.

### Managed Control Models

| Control model             | Root owner                      | Conto authority                                                                                      | Customer key access                                      | Enforcement boundary                                                                                 |
| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `ORGANIZATION_CONTROLLED` | Your customer-only owner quorum | Separate signer used after Conto policies and approvals; EVM also has a provider-level signer policy | The owner can administer the wallet and authorize export | The owner can authorize actions outside Conto; after export, the raw key can also sign outside Conto |
| `CONTO_MANAGED`           | Conto authorization key         | Root owner and signer, behind Conto policies and approvals                                           | No customer self-service export                          | There is no separate customer signing path                                                           |

For organization-controlled creation, an organization owner first registers a base64 SPKI P-256
public key in **Settings → Wallet Control** and keeps the matching private key in the customer's own
key manager. Conto never receives or stores that private key. Privy creates the customer-only owner
quorum and attaches Conto separately as an additional signer. The provider-level baseline policy is
currently Ethereum/EVM-specific. Organization-controlled Solana creation is unavailable until a
separately validated Solana signer policy is configured, so Conto is never attached as an
unpolicied additional signer.

Conto stores the wallet address, its public control model, and provider references needed for
operations. Provider IDs and authorization secrets are not returned by the customer wallet API.

An organization Owner can use **Wallets → wallet menu → Export encrypted key**. The owner signs the
prepared request outside Conto, and Conto returns only HPKE ciphertext encrypted to a separate
customer-provided recipient public key. See [Exporting Wallet Keys](https://conto.finance/guides/exporting-wallet-keys).

Note:

  This describes technical control and product access. It does not, by itself, determine legal or
  beneficial ownership of the wallet or its assets; that depends on your agreement and applicable
  law. Root-owner access can bypass Conto's offchain path, so use a contract-enforced design when
  every possible transfer must be cryptographically governed.

## External / Watch-Only Wallets

When you import a wallet, Conto registers it in `EXTERNAL` mode. You keep the keys, and your
agent or wallet stack signs the transaction.

- Conto can still evaluate policies before the transfer.
- Conto can still require approval, record the payment, and keep the audit trail.
- The agent uses the `approve -> transfer -> confirm` flow.
- Conto **cannot cryptographically block** a direct transfer signed outside Conto.

You can register an external wallet directly with `custodyMode=EXTERNAL` plus `address`, or use
the watch-only import flow in the dashboard.

That means external wallets are best described as **self-custody with policy gating**, not as
fully Conto-controlled execution.

  External wallets can have policies. Those policies are enforced when the payment goes through
  Conto. They are not a guarantee against a direct self-signed transfer outside Conto.

## Smart Contract Wallets

Smart contract wallets are the strongest enforcement option.

- Funds stay in an onchain contract wallet.
- Transfers require the approved contract path and Conto's signature.
- This gives you cryptographic enforcement without giving Conto direct key custody.

## Which Flow Should My Agent Use?

| Wallet model                          | Endpoints to use                                                                                              |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Managed** (`MANAGED`)               | `POST /api/sdk/payments/request` then `POST /api/sdk/payments/{id}/execute`                                   |
| **External** (`EXTERNAL`)             | `POST /api/sdk/payments/approve` then your signer/wallet transfer, then `POST /api/sdk/payments/{id}/confirm` |
| **Smart Contract** (`SMART_CONTRACT`) | Request approval, execute through the contract path, then confirm                                             |

## How To Choose

- Pick **Organization-controlled managed** if you need customer root administration or an export
  path while keeping Conto as the normal signer after Conto policies and approvals.
- Pick **Conto-managed** if you want Conto to remain the only product signing path and do not need
  customer self-service export.
- Pick **External** if you already have a wallet stack, MPC signer, or agent-held wallet and want
  to keep that setup.
- Pick **Smart Contract** if you want the strongest onchain enforcement model.

## Related Guides

### Choose Your Integration
Link: https://conto.finance/guides/choose-your-integration

    Compare SDK, OpenClaw, Hermes, x402, and MPP

### Payments API
Link: https://conto.finance/sdk/payments

    See the managed and external payment flows

### Exporting Wallet Keys
Link: https://conto.finance/guides/exporting-wallet-keys

    Use the owner-authorized, encrypted export flow