Skip to main content

​
Architecture Overview

Conto is designed as a secure, scalable control center for AI agent financial operations.

​
System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AI Agents                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   Claude    │  │  Custom AI  │  │  Workflow   │             │
│  │   Agent     │  │   Agent     │  │   Agent     │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
└─────────┼────────────────┼────────────────┼─────────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Conto SDK                                   │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  payments.request() → evaluate policies → payments.execute() ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Conto Control Center                          │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │    Policy     │  │   Wallet      │  │   Agent       │       │
│  │    Engine     │  │   Manager     │  │   Registry    │       │
│  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘       │
│          │                  │                  │                │
│          └──────────────────┼──────────────────┘                │
│                             ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Transaction Engine                        ││
│  │  • Policy Evaluation  • Spend Tracking  • Audit Logging     ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Blockchain                                │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │  Stablecoin   │  │  Transaction  │  │   Block       │       │
│  │   Contract    │  │   Mempool     │  │   Finality    │       │
│  └───────────────┘  └───────────────┘  └───────────────┘       │
└─────────────────────────────────────────────────────────────────┘

​
Core Components

SDK Layer

TypeScript SDK that agents use to request and execute payments. Handles authentication, policy pre-checks, and transaction submission.

Policy Engine

Evaluates payment requests against configurable rules. Supports spend limits, time windows, counterparty restrictions, and more.

Wallet Manager

Manages stablecoin wallets for agent payments. Handles key management, balance tracking, and spend limit enforcement.

Agent Registry

Identity management for AI agents. Tracks permissions, SDK keys, and activity history.

​
Payment Flow

1

Request

Agent calls payments.request() with amount, recipient, and purpose.
2

Authenticate

SDK key is validated and mapped to agent identity.
3

Evaluate

Policy engine checks all applicable rules:
  • Spend limits (per-tx, daily, weekly, monthly)
  • Time windows
  • Counterparty restrictions
  • Category rules
4

Decision

Request is approved, denied, or flagged for manual review.
5

Execute

If approved, agent calls payments.execute() to submit transaction.
6

Confirm

Transaction is submitted to the blockchain and confirmed on-chain.

​
Data Flow

​
Write Path (Payments)

Agent → SDK → API Gateway → Auth Middleware → Policy Engine
                                                    ↓
                                              Rate Limiter
                                                    ↓
                                           Transaction Engine
                                                    ↓
                                             Blockchain TX
                                                    ↓
                                             PostgreSQL

​
Read Path (Queries)

Dashboard → API Gateway → Auth → Database → Response Cache → UI

​
Technology Stack

  • Next.js 14 - React framework with App Router
  • TypeScript - Type-safe development
  • TailwindCSS - Utility-first styling
  • shadcn/ui - Component library
  • Recharts - Analytics visualization
  • Next.js API Routes - Serverless API endpoints
  • Prisma ORM - Type-safe database access
  • PostgreSQL - Primary database
  • Redis - Rate limiting and caching
  • Stablecoins - For secure payments
  • viem - Ethereum library
  • wagmi - React hooks for Ethereum
  • Vercel - Deployment platform
  • Neon - Serverless PostgreSQL
  • Upstash - Serverless Redis

​
Design Principles

​
1. Defense in Depth

Multiple layers of protection: 
┌─────────────────────────────────────┐
│          Rate Limiting              │  ← Request throttling
├─────────────────────────────────────┤
│        Authentication               │  ← SDK key validation
├─────────────────────────────────────┤
│        Authorization                │  ← Scope verification
├─────────────────────────────────────┤
│        Policy Evaluation            │  ← Business rules
├─────────────────────────────────────┤
│        Spend Tracking               │  ← Limit enforcement
├─────────────────────────────────────┤
│        Audit Logging                │  ← Full trail
└─────────────────────────────────────┘

​
2. Fail-Safe Defaults

  • New agents start with minimal permissions
  • Unknown counterparties require verification
  • Exceeding limits blocks transactions (doesn’t just warn)
  • Expired SDK keys are immediately rejected

​
3. Auditability

Every action is logged: 
{
  action: "PAYMENT_EXECUTED",
  actorType: "AGENT",
  actorId: "agt_abc123",
  resource: "transaction",
  resourceId: "tx_xyz789",
  metadata: {
    amount: 50,
    recipient: "0x...",
    policyResult: "ALLOWED"
  },
  timestamp: "2024-01-15T14:30:00Z"
}

​
4. Separation of Concerns

ConcernOwner
IdentityAgent Registry
AuthorizationPolicy Engine
FundsWallet Manager
ExecutionTransaction Engine
ObservabilityAudit System

​
Scalability

​
Horizontal Scaling

  • Stateless API servers (Vercel serverless)
  • Connection pooling (Prisma + PgBouncer)
  • Read replicas for analytics queries

​
Performance Optimizations

  • Policy evaluation cached per request
  • Balance reads cached with short TTL
  • Batch transaction confirmations
  • Background trust score updates

​
Reliability

​
Transaction Safety

// All payment operations use database transactions
await prisma.$transaction(async (tx) => {
  // 1. Lock wallet row
  const wallet = await tx.$queryRaw`SELECT ... FOR UPDATE`;

  // 2. Verify balance
  if (wallet.balance < amount) throw new Error("INSUFFICIENT_BALANCE");

  // 3. Create transaction record
  const txRecord = await tx.transaction.create({ ... });

  // 4. Update balances atomically
  await tx.wallet.update({ balance: { decrement: amount } });

  // 5. Update spend tracking
  await tx.agentWallet.update({ spentToday: { increment: amount } });
});

​
Idempotency

  • Payment requests have unique IDs
  • Duplicate execute calls return existing result
  • Retry-safe API design

​
Next Steps

Security Model

Deep dive into authentication, encryption, and access control.

Trust Scores

Learn about network intelligence and counterparty verification.