> ## 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. # Architecture Patterns > Reference diagrams for Conto payment flows, approval workflows, trust scoring, x402, and MPP integrations. # Architecture Patterns These are the core integration patterns teams implement with Conto in production. Use them as canonical reference diagrams when you are designing a new agent payment workflow or documenting an existing one. ## 1. Managed Execution with an Integrated Wallet Use this pattern when Conto should both evaluate policy and orchestrate execution through an integrated wallet provider such as Privy or Sponge. ```mermaid theme={null} flowchart LR Agent["Agent runtime"] --> Request["POST /api/sdk/payments/request\nautoExecute=true"] Request --> Policy["Policy engine"] Policy --> Decision{"Approved?"} Decision -->|"Yes"| Wallet["Integrated wallet provider\nPrivy or Sponge"] Decision -->|"Requires review"| Approval["Approval workflow"] Decision -->|"No"| Denied["Denied with violations"] Approval -->|"Approved"| Wallet Approval -->|"Rejected"| Denied Wallet --> Chain["Blockchain settlement"] Chain --> Audit["Transactions, audit logs,\nalerts, analytics"] ``` * Best for: teams that want fewer moving parts and Conto-managed execution. * Common controls: spend limits, approval thresholds, trust rules, time windows. ## 2. External Wallet Approval + Confirm Use this pattern when your agent already controls its own wallet or transfer tools and Conto acts as the policy gate. ```mermaid theme={null} flowchart LR Agent["Agent runtime"] --> Approve["POST /api/sdk/payments/approve"] Approve --> Policy["Policy engine"] Policy --> Gate{"Approved?"} Gate -->|"Yes"| Transfer["Agent executes transfer\nwith its own keys or wallet tools"] Gate -->|"Requires review"| Review["Approval workflow"] Gate -->|"No"| Denied["Denied with reasons"] Review -->|"Approved"| Transfer Review -->|"Rejected"| Denied Transfer --> Confirm["POST /api/sdk/payments/{id}/confirm"] Confirm --> Audit["Conto records tx hash,\nstatus, audit trail"] ``` * Best for: OpenClaw and Hermes agents that already have wallet tools. * Canonical flow: `approve -> transfer -> confirm`. ## 3. x402 API Control Loop Use this pattern when an API returns `402 Payment Required` and each paid call is a separate machine payment event. ```mermaid theme={null} flowchart LR Agent["Agent calls paid API"] --> Challenge["HTTP 402 challenge"] Challenge --> PreAuth["POST /api/sdk/x402/pre-authorize"] PreAuth --> Policy["x402 policy controls"] Policy --> Allowed{"Authorized?"} Allowed -->|"Yes"| Pay["Wallet signs x402 payment"] Allowed -->|"No"| Stop["Abort or escalate"] Pay --> Retry["Retry API call with payment"] Retry --> Record["POST /api/sdk/x402/record"] Record --> Analytics["Budgets, service stats,\nauditability"] ``` * Best for: pay-per-use APIs and machine commerce with explicit per-call pricing. * Core controls: price ceilings, service allowlists, endpoint velocity, service budgets. ## 4. MPP Session Lifecycle Use this pattern when an agent will make repeated requests to the same service and wants a session budget instead of separate onchain settlement for each call. ```mermaid theme={null} flowchart LR Agent["Agent receives MPP payment challenge"] --> PreAuth["POST /api/sdk/mpp/pre-authorize"] PreAuth --> Policy["MPP policy controls"] Policy --> Session{"Authorized?"} Session -->|"Yes"| Open["Open session with deposit"] Session -->|"No"| Stop["Abort or escalate"] Open --> Charges["Multiple service requests\nconsume session budget"] Charges --> Close["Close session and settle"] Close --> Record["POST /api/sdk/mpp/record"] Record --> Analytics["Session budgets,\nservice usage, burn rate"] ``` * Best for: chat, streaming, iterative processing, or high-frequency service calls. * Core controls: session budget, max concurrent sessions, max duration, and service allowlists. ## 5. Human Approval Workflow Approval workflows sit in front of execution and resolve high-risk or policy-triggered payments before money moves. ```mermaid theme={null} flowchart TD Request["Payment request"] --> Match["Find highest-priority matching workflow"] Match --> Create["Create approval request"] Create --> Notify["Dispatch to Slack, email,\nTelegram, WhatsApp, or webhook"] Notify --> Decide["Approver decision(s)"] Decide --> Enough{"Enough approvals?"} Decide --> Reject{"Any rejection?"} Enough -->|"Yes"| Approved["Payment approved"] Enough -->|"No"| Pending["Still pending"] Reject -->|"Yes"| Denied["Payment denied"] Reject -->|"No"| Pending Approved --> Audit["Record channel, actor,\nstatus, audit trail"] Denied --> Audit ``` * Best for: large payments, new recipients, low-trust counterparties, and finance review. * Supports multi-approver, role-based, specific-approver, and sequential workflows. ## 6. Trust Scoring Feedback Loop Trust scoring is not just a lookup; it is a feedback loop that continuously changes how counterparties are evaluated. ```mermaid theme={null} flowchart LR Counterparty["Counterparty address"] --> History["Transaction history"] Counterparty --> Reliability["Failures, flags, alerts"] Counterparty --> Activity["Age, recency, consistency"] Counterparty --> Verification["Verification + network data"] Verification --> Fairscale["Fairscale for Solana\ncold-start enrichment"] Verification --> Network["Conto network intelligence"] History --> Score["Trust score + trust level"] Reliability --> Score Activity --> Score Fairscale --> Score Network --> Score Score --> Policies["Counterparty and approval policies"] Policies --> Outcomes["Allow, require approval,\nor deny"] ``` * Best for: vendor controls, trust-based approvals, network-aware risk gating. * Related docs: [/guides/trust-scoring](/guides/trust-scoring), [/integrations/trust-providers](/integrations/trust-providers) ## Which Pattern Should You Start With? | Goal | Recommended pattern | | ----------------------------------------------- | ---------------------------------------- | | Fastest first payment with minimal custom logic | Managed execution with integrated wallet | | Add guardrails to an existing agent wallet | External wallet approval + confirm | | Govern machine-paid APIs | x402 API control loop | | Govern repeated session spend | MPP session lifecycle | | Add finance or security review | Human approval workflow | | Route based on recipient quality and risk | Trust scoring feedback loop | ## Related Guides Decide between SDK, OpenClaw, Hermes, x402, and MPP Configure review and escalation logic Understand how recipient trust feeds policy decisions Copy-paste commands for the main flows above