> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custody Modes

> Understand who holds the keys, which payment flow to use, and what Conto can actually enforce

# 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                                   | Keys held by                          | Typical flow                             | Can Conto block a direct spend signed outside Conto?            | Best for                                         |
| -------------------------------------- | ------------------------------------- | ---------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
| **Managed** (`PRIVY`, `SPONGE`)        | The custody provider                  | `request -> execute`                     | **Yes.** Conto stays in the execution path.                     | 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`)  | Onchain wallet contract               | `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 `PRIVY` or `SPONGE`, the wallet provider holds the keys and Conto stays in the execution
path. This is the strongest standard setup for policy enforcement.

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

For `PRIVY`, you now have two setup options:

* **Create a new Privy wallet through Conto** and let Conto mint the wallet record for you.
* **Attach an existing Privy-backed wallet** by creating the Conto wallet with
  `custodyType=PRIVY`, `externalWalletId=<privy wallet id>`, and `address=<privy wallet address>`.

Attach requests are idempotent per `externalWalletId + chainId` or `address + chainId` inside the
organization, so you can safely retry provisioning calls from your backend.

This existing-Privy attach flow only works when the wallet is visible to the same Privy app Conto
is configured to use for managed execution. If the wallet lives in a different Privy app or a
different wallet stack, register it as `EXTERNAL` instead.

## External / Watch-Only Wallets

When you import a wallet, Conto registers it as `EXTERNAL` custody. 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 `custodyType=EXTERNAL` plus `address`, or use
the existing watch-only import flow. Both end up as `EXTERNAL` custody inside Conto.

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

<Warning>
  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.
</Warning>

## 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** (`PRIVY`, `SPONGE`)       | `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 **Managed** if you want the cleanest production path and want Conto to stay in the
  execution flow.
* 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

<CardGroup cols={2}>
  <Card title="Choose Your Integration" icon="compass" href="/guides/choose-your-integration">
    Compare SDK, OpenClaw, Hermes, x402, and MPP
  </Card>

  <Card title="Payments API" icon="money-bill-transfer" href="/sdk/payments">
    See the managed and external payment flows
  </Card>
</CardGroup>