Quick comparison
What policies mean in each mode
Managed wallets


POST /api/sdk/payments/request, then POST /api/sdk/payments/{id}/execute, or set autoExecute: true. Choose root control when creating the wallet.
Create a managed wallet in the dashboard or use POST /api/wallets with
custodyMode=MANAGED. A sandbox organization cannot, and gets 403 SANDBOX_MANAGED_WALLET_UNAVAILABLE. Set controlModel to ORGANIZATION_CONTROLLED or CONTO_MANAGED. If you omit it, the wallet is organization-controlled when your organization has registered an owner key, and Conto-managed otherwise.
The selection is fixed for the new wallet. Changing the organization default never migrates an
existing wallet.
Managed control models
Organization-controlled (ORGANIZATION_CONTROLLED)
- Your organization’s owner key is the root owner. Only your organization holds it.
- Conto is a separate signer and signs only after your policies and approvals pass. On EVM, the wallet provider also limits what Conto’s signer can do.
- Your owner can manage the wallet and approve a key export.
- Conto cannot stop everything. The owner key can authorize actions outside Conto, and an exported key can sign outside Conto.
CONTO_MANAGED)
- A Conto authorization key is the root owner.
- Conto is the only signer and signs only after your policies and approvals pass.
- There is no self-service key export.
- There is no customer signing path outside Conto.
controlModel: "CONTO_MANAGED".
External (watch-only) wallets


EXTERNAL mode: you keep the keys and sign. Call POST /api/sdk/payments/approve for policy checks and review, send with your signer, then call POST /api/sdk/payments/{id}/confirm to record the transfer. Conto cannot block a transfer signed outside this flow.
A shared budget refuses this flow for covered agents, even while paused. Use a managed wallet for those agents.
You can register an external wallet directly with custodyMode=EXTERNAL plus address, or use
the watch-only import flow in the dashboard. Without a chain, the API records the address on its
default chain (Tempo Testnet). For a Solana address, also send chainType: "SOLANA" and chainId
(solana-mainnet or solana-devnet). The dashboard import detects a Solana address and asks for
the network. An address Conto manages for another organization cannot be added as external and returns 409 WALLET_ADDRESS_MANAGED.
Prove control of an external wallet
When external-wallet ownership enforcement is enabled, onchain payments require a signed ownership proof, including on testnets. Sandbox-plan requests through/api/sdk/payments/request can still produce simulated receipts without a proof. The sandbox exception does not apply to /approve or /confirm.
Registering an address does not show that you hold its key. Prove it by signing a one-time message
with the wallet’s address, using an organization API key or a signed-in owner or admin:
- EVM wallets sign with
personal_sign(EIP-191). Solana wallets sign the message bytes and send the signature in base58 or base64. - The message expires after 10 minutes and works once.
approvedeclines an unproven sender withWALLET_OWNERSHIP_UNPROVENwhen another organization has proven the same address. Prove your wallet to keep paying from it.
How to choose
- Pick Organization-controlled if your organization needs root control of the wallet or a way to export its key, with Conto still signing payments after your policies and approvals pass.
- Pick Conto-managed if you want Conto to be the only signer and do not need to export the key.
- Pick External if you already have a wallet stack, MPC signer, or agent-held wallet and want to keep that setup.
Export a wallet key
An organization Owner can export the private key of an organization-controlled managed wallet. The export is owner-authorized and end-to-end encrypted. Conto relays the signed request and returns only HPKE ciphertext, and never receives the customer owner private key, the HPKE recipient private key, or the plaintext wallet key. This flow is not available forCONTO_MANAGED wallets.
Before you start
You need two customer-controlled P-256 keys with different purposes:- The owner authorization key registered in Settings → Security → Wallet ownership. Keep its private half in your KMS or offline signing environment.
- A new HPKE recipient key for this export. Keep its private half outside Conto. Conto receives only its base64 SPKI public key.
Export from the dashboard
- Sign in as the organization Owner.
- Open Wallets, open the organization-controlled wallet menu, and select Export encrypted key.
- Paste the HPKE recipient public key and choose Prepare owner authorization.
- Copy and base64-decode the authorization payload. Sign the decoded bytes outside Conto with the registered owner authorization private key using ECDSA P-256 with SHA-256 and DER encoding.
- Paste the base64 DER signature and download the encrypted export before the displayed expiry.
- Decrypt
ciphertextusingencapsulatedKey, the HPKE recipient private key, and this suite:DHKEM(P-256, HKDF-SHA256) / HKDF-SHA256 / ChaCha20-Poly1305.
sign.ts and run npx tsx sign.ts with both environment variables
set:
keyAccess
to EXPORTED and writes an audit event. If Conto cannot confirm the result, keyAccess shows
EXPORT_RECONCILIATION_REQUIRED, and the next export request checks the provider’s export record
before it continues.
Operational boundaries
- The authorization payload covers this wallet, this recipient key, and this request, and expires after 10 minutes.
- Only an authenticated organization Owner can prepare or submit an export.
- Conto’s additional-signer key cannot authorize export or administer the customer owner quorum.
- Conto can continue signing through its normal policy and approval path after export, but the exported key also permits signing outside Conto.
Related guides
Choose your integration
Compare SDK, OpenClaw, Hermes, x402, and MPP
Payments API
See the managed and external payment flows