Skip to main content
Choose who holds signing authority and whether they can spend outside Conto’s checks.

Quick comparison

What policies mean in each mode

Managed wallets

Managed wallet flow. The agent requests a payment, Conto checks the owner's policy, the owner's approver decides only when the payment needs review, the managed wallet sends the funds, and the payment is logged with full context. Managed wallet flow. The agent requests a payment, Conto checks the owner's policy, the owner's approver decides only when the payment needs review, the managed wallet sends the funds, and the payment is logged with full context. The wallet provider holds the private key, and Conto never stores it. Conto signs only after policies and approvals pass. Call 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 (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.
For organization-controlled creation, an organization owner first registers a base64 SPKI P-256 public key in Settings → Security → Wallet ownership and keeps the matching private key in the customer’s own key manager. Conto never receives or stores that private key. Your owner key alone forms the owner quorum that holds root control, and Conto is added separately as an additional signer. Organization-controlled wallets are EVM only. For Solana, create the wallet with controlModel: "CONTO_MANAGED".

External (watch-only) wallets

Agent-controlled wallet flow. The agent asks Conto to authorize a payment, Conto checks the owner's policy, the owner's approver decides only when the payment needs review, the agent's own signer sends the transaction within 10 minutes, and the agent confirms the transaction ID so Conto can record it. Agent-controlled wallet flow. The agent asks Conto to authorize a payment, Conto checks the owner's policy, the owner's approver decides only when the payment needs review, the agent's own signer sends the transaction within 10 minutes, and the agent confirms the transaction ID so Conto can record it. Imported wallets use 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.
  • approve declines an unproven sender with WALLET_OWNERSHIP_UNPROVEN when 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 for CONTO_MANAGED wallets.

Before you start

You need two customer-controlled P-256 keys with different purposes:
  1. The owner authorization key registered in Settings → Security → Wallet ownership. Keep its private half in your KMS or offline signing environment.
  2. A new HPKE recipient key for this export. Keep its private half outside Conto. Conto receives only its base64 SPKI public key.
Anyone with the decrypted wallet key can sign outside Conto and bypass Conto policies. Treat the export as a high-risk governance action and secure the resulting key accordingly.

Export from the dashboard

  1. Sign in as the organization Owner.
  2. Open Wallets, open the organization-controlled wallet menu, and select Export encrypted key.
  3. Paste the HPKE recipient public key and choose Prepare owner authorization.
  4. 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.
  5. Paste the base64 DER signature and download the encrypted export before the displayed expiry.
  6. Decrypt ciphertext using encapsulatedKey, the HPKE recipient private key, and this suite: DHKEM(P-256, HKDF-SHA256) / HKDF-SHA256 / ChaCha20-Poly1305.
For a base64 PKCS8 owner authorization private key, this TypeScript snippet prints the signature the dialog expects. Save it as sign.ts and run npx tsx sign.ts with both environment variables set:
Conto does not keep the ciphertext or the key. A successful export sets the wallet’s 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.

Choose your integration

Compare SDK, OpenClaw, Hermes, x402, and MPP

Payments API

See the managed and external payment flows