Skip to main content

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

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

ModeKeys held byTypical flowCan Conto block a direct spend signed outside Conto?Best for
Managed (PRIVY, SPONGE)The custody providerrequest -> executeYes. Conto stays in the execution path.Teams that want Conto-orchestrated execution
External / Watch-Only (EXTERNAL)You, your agent, or your wallet stackapprove -> transfer -> confirmNo. Conto only controls payments routed through Conto.Self-custody, MPC wallets, existing wallet tools
Smart Contract (SMART_CONTRACT)Onchain wallet contractrequest -> contract execute -> confirmYes. 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.
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 modelEndpoints 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.

Choose Your Integration

Compare SDK, OpenClaw, Hermes, x402, and MPP

Payments API

See the managed and external payment flows