# Conto Documentation

> Conto is an enterprise control center for managing AI agent financial transactions using stablecoins. It provides identity management, wallet controls, spending policies, and real-time transaction monitoring for autonomous AI agents.

## Quick Reference

Base URL: https://conto.finance
API Base: https://conto.finance/api
OpenAPI Spec: https://conto.finance/api/openapi
SDK Package: @conto/sdk

## Documentation Index

### Getting Started
- [Overview](https://conto.finance/docs/introduction/overview): Platform overview and key features
- [Core Concepts](https://conto.finance/docs/introduction/concepts): Agents, wallets, policies, transactions, counterparties

### Quick Start
- [Setup Guide](https://conto.finance/docs/quickstart/setup): Create account, agent, wallet in 5 minutes
- [First Agent](https://conto.finance/docs/quickstart/first-agent): Register your first AI agent
- [Connecting Agents](https://conto.finance/docs/quickstart/connecting-agents): Connect agents via SDK or API
- [First Payment](https://conto.finance/docs/quickstart/first-payment): Make your first payment

### CLI
- [CLI Quickstart](https://conto.finance/docs/cli/quickstart): Interactive setup wizard with create-conto-agent
- [CLI Commands](https://conto.finance/docs/cli/commands): Full command reference for agent, wallet, policy, and payment operations
- [CLI Policies](https://conto.finance/docs/cli/policies): Create and manage spending policies from the command line

### SDK Reference
- [Installation](https://conto.finance/docs/sdk/installation): Install @conto/sdk package
- [Authentication](https://conto.finance/docs/sdk/authentication): SDK key authentication
- [Payments](https://conto.finance/docs/sdk/payments): Request, execute, and check payment status
- [A2A Payments](https://conto.finance/docs/sdk/a2a-payments): Agent-to-agent payment requests and transfers
- [Card Payments](https://conto.finance/docs/sdk/card-payments): Card payment approval and confirmation (BYOC flow)
- [x402 Payments](https://conto.finance/docs/sdk/x402-payments): x402 protocol pre-authorization and recording
- [MPP Payments](https://conto.finance/docs/sdk/mpp-payments): Machine Payment Protocol session-based micropayments
- [Error Handling](https://conto.finance/docs/sdk/error-handling): Handle errors and retries
- [Examples](https://conto.finance/docs/sdk/examples): Complete integration examples
- [OpenClaw Skill](https://conto.finance/docs/sdk/openclaw): Install Conto as an OpenClaw skill for policy enforcement
- [Nous Hermes Skill](https://conto.finance/docs/sdk/hermes): Install Conto as a Nous Hermes skill for policy enforcement

### MCP Server
- [MCP Overview](https://conto.finance/docs/mcp/overview): Connect Claude and compatible AI agents to Conto via Model Context Protocol
- [Claude Desktop](https://conto.finance/docs/mcp/claude-desktop): Setup guide for Claude Desktop integration
- [Claude Code](https://conto.finance/docs/mcp/claude-code): Setup guide for Claude Code CLI integration
- [MCP Tools](https://conto.finance/docs/mcp/tools): Complete reference for all MCP tools

### Policies
- [Policy Overview](https://conto.finance/docs/policies/overview): Policy types and evaluation
- [Spend Limits](https://conto.finance/docs/policies/spend-limits): Amount-based restrictions
- [Time Windows](https://conto.finance/docs/policies/time-windows): Hour and day restrictions
- [Counterparties](https://conto.finance/docs/policies/counterparties): Vendor allowlists and blocklists
- [Advanced Policies](https://conto.finance/docs/policies/advanced): Composite rules, geographic restrictions

### Integrations
- [Trust & Risk Providers](https://conto.finance/docs/integrations/trust-providers): Fairscale, Chainalysis, TRM Labs, and OFAC sanctions screening
- [Notification Channels](https://conto.finance/docs/integrations/notification-channels): Slack, Email, Telegram, WhatsApp, and Webhook approval channels

### Guides
- [Choose Your Integration](https://conto.finance/docs/guides/choose-your-integration): Compare SDK, OpenClaw, Hermes, x402, and MPP
- [First Agent Payment](https://conto.finance/docs/guides/first-agent-payment): End-to-end guide to your first onchain payment
- [Testing Payments](https://conto.finance/docs/guides/testing-payments): Test approved, denied, and approval-required scenarios on testnet
- [Securing Agents](https://conto.finance/docs/guides/securing-agents): Production-ready policy configurations and defense-in-depth
- [Approval Workflows](https://conto.finance/docs/guides/approval-workflows): Configure multi-step human review and escalation
- [Trust Scoring](https://conto.finance/docs/guides/trust-scoring): Understand counterparty risk, trust levels, and provider signals
- [x402 API Payments](https://conto.finance/docs/guides/x402-api-payments): Implement HTTP 402 micropayment flows with policy enforcement
- [MPP Session Payments](https://conto.finance/docs/guides/mpp-session-payments): Session-based micropayments on Tempo with deposit budgets
- [Card Management](https://conto.finance/docs/guides/card-management): Manage card payments with policy controls
- [Policy Testing](https://conto.finance/docs/guides/policy-testing): Set up and validate spending policies with test scenarios
- [External Approvals](https://conto.finance/docs/guides/external-approvals): Configure Slack, Email, Telegram, and Webhook approval channels
- [Architecture Patterns](https://conto.finance/docs/guides/architecture-patterns): Canonical diagrams for payments, approvals, x402, MPP, and trust
- [Recipes](https://conto.finance/docs/guides/recipes): Copy-paste solutions for common Conto tasks

## Blog Posts

- [Agentic Payments Are the Wild West](https://conto.finance/blog/agentic-payments-wild-west): Agents are spending money without controls, limits, or governance. Enterprises need a control layer to move agentic payments from experimentation to production.
- [The Enterprise is the Biggest Opportunity for Agentic Payments](https://conto.finance/blog/enterprise-agentic-payments): The largest opportunity for agentic payments isn't consumer commerce — it's the enterprise. Companies deploying AI agents need financial infrastructure designed for autonomous economic actors.
- [Conto Integrates Fairscale for Solana Wallet Reputation](https://conto.finance/blog/fairscale-integration): Why onchain reputation matters for agentic payments
- [Field Notes from Stripe Sessions](https://conto.finance/blog/field-notes-from-stripe-sessions): What a day at Stripe Sessions revealed about agentic commerce, stablecoin rails, and Stripe's position in the next phase of payments.
- [Five Layers of Security for Agents That Spend Money](https://conto.finance/blog/five-layers-agent-security): A defense-in-depth policy strategy for AI agents handling real money. Spending limits, counterparty controls, time windows, micropayment guardrails, and real-time alerts, configured through Conto's policy engine.
- [Conto for Hermes: Policy Enforcement for Nous Research Agents](https://conto.finance/blog/hermes-launch): Conto adds spending policy controls to every payment your Hermes agent makes. Per-transaction limits, daily budgets, category restrictions, approval workflows, and 40+ other rule types. One API call, every policy evaluated.
- [MPP: Session-Based Payments for Agents on Tempo](https://conto.finance/blog/mpp-session-payments): MPP (Machine Payment Protocol) lets agents open payment sessions with a deposit, make multiple requests against it, and settle once on close. Here's how session-based payments work with Conto's policy engine.
- [Conto for OpenClaw: The Spend Management Layer Your Agents Need](https://conto.finance/blog/openclaw-launch): Conto adds policy enforcement to every payment your OpenClaw agent makes. Per-transaction limits, daily budgets, category restrictions, approval workflows, and 40+ other rule types. One API call, every policy evaluated.
- [Adding Spending Policies to Any OpenClaw Agent](https://conto.finance/blog/openclaw-spending-policies): The Conto skill for OpenClaw checks every payment against 40+ policy rules before money leaves the wallet. Here's how to set it up.
- [How to Test Agent Payments Without Losing Real Money](https://conto.finance/blog/testing-agent-payments): Tempo Testnet, policy simulation, and five test scenarios that prove your agent's spending controls work before production.
- [This Week at Conto: Assistant Upgrades, Tighter Controls, Cleaner Operations](https://conto.finance/blog/weekly-release-notes-2026-04-17): Weekly release notes covering AI assistant improvements, authentication and audit hardening, admin tooling, and developer docs.
- [This Week at Conto: Conto Pay, End to End Hosted Agentic Payments](https://conto.finance/blog/weekly-release-notes-2026-04-24): Weekly release notes covering Conto Pay chat actions, a more complete hosted payments experience, and expanded stablecoin coverage.
- [x402: How Agents Pay for APIs with HTTP](https://conto.finance/blog/x402-paying-for-apis): The x402 protocol turns HTTP 402 into a real payment flow. Here's how it works with Conto and why it matters for agentic commerce.
- [Zero to First Agent Payment in 5 Minutes](https://conto.finance/blog/zero-to-first-payment): Set up an AI agent with Conto and execute your first policy-checked onchain payment in four steps. Create a wallet, connect your agent, generate an SDK key, and pay with full spending controls from day one.

## API Reference (auto-generated from OpenAPI spec)

### Authentication
User registration and authentication

- `POST /api/auth/register` — Register a new account
  Create a new user account and organization, then send an email verification link. Privileged API credentials are not issued until the account is verified.

### Agents
AI agent management

- `GET /api/agents` — List all agents
  Retrieve all agents for the current organization.
- `POST /api/agents` — Create a new agent
  Create an AI agent that can be linked to wallets and policies for controlled payments.
- `GET /api/agents/{id}` — Get agent by ID
  Get full agent details including linked wallets, policies, and transaction counts.
- `PATCH /api/agents/{id}` — Update agent
- `DELETE /api/agents/{id}` — Delete agent
- `GET /api/agents/{id}/wallets` — List wallets linked to agent
- `POST /api/agents/{id}/wallets` — Link wallet to agent
  Link a wallet to an agent with delegation type, spend limits, and time window controls.
- `PATCH /api/agents/{id}/wallets/{walletId}` — Update agent-wallet link
  Update spend limits, delegation type, or time window for an agent-wallet link.
- `DELETE /api/agents/{id}/wallets/{walletId}` — Unlink wallet from agent
- `GET /api/agents/{id}/policies` — List policies assigned to agent
- `POST /api/agents/{id}/policies` — Assign policy to agent
- `DELETE /api/agents/{id}/policies` — Unassign policy from agent
  Uses query parameter: DELETE /api/agents/{id}/policies?policyId={policyId}
- `GET /api/agents/{id}/sdk-keys` — List SDK keys for agent
- `POST /api/agents/{id}/sdk-keys` — Generate SDK key for agent
  Generate a new SDK API key for the agent. The full key is returned only once. Key format: conto_agent_xxx...
- `POST /api/agents/{id}/freeze` — Freeze an agent
  Immediately suspend an agent and block all transactions. Optionally freeze associated wallets. Creates a FreezeEvent audit record.
- `GET /api/agents/{id}/freeze` — Get freeze status and configuration
  Returns the agent freeze status, behavioral counters, stored freeze config, and the effective config (stored merged with defaults).
- `POST /api/agents/{id}/unfreeze` — Unfreeze an agent
  Restore a frozen agent to ACTIVE status. Optionally unfreeze associated wallets and reset behavioral counters.
- `PATCH /api/agents/{id}/freeze-config` — Update freeze configuration
  Update auto-freeze thresholds for an agent. Omitted fields keep their current values. Thresholds define when automatic freezing triggers fire.
- `GET /api/agents/{id}/freeze-history` — Get agent freeze event history
  Paginated list of freeze and unfreeze events for this agent.

### Wallets
Wallet management, provisioning, and funding

- `GET /api/wallets` — List all wallets
  List all wallets for the organization with linked agents and policies.
- `POST /api/wallets` — Create a new wallet
  Create a new wallet. By default creates a PRIVY-custodied EOA wallet on EVM. You can also attach an existing Privy-backed wallet by providing custodyType=PRIVY with externalWalletId and address, or register a self-custodied wallet with custodyType=EXTERNAL and address/importAddress. Requests are idempotent per externalWalletId + chainId or address + chainId within the organization.
- `GET /api/wallets/{id}` — Get wallet by ID
- `PATCH /api/wallets/{id}` — Update wallet
- `POST /api/wallets/{id}/provision` — Provision wallet onchain
  Provision a Sponge-custodied wallet: links to the platform Sponge account, syncs a real blockchain address and balance, and marks the wallet ready for SDK-initiated payments. No request body required.

### Policies
Spending policy configuration and rules

- `GET /api/policies` — List all policies
  List all policies for the organization with their rules and assignments.
- `POST /api/policies` — Create a new policy
  Create a policy with optional inline rules and agent assignments. When `rules` and/or `agentIds` are provided, everything is created in a single atomic transaction — if any step fails, nothing is created. You can also create a policy shell first and add rules separately via POST /api/policies/{id}/rules.
- `GET /api/policies/{id}` — Get policy by ID
- `PATCH /api/policies/{id}` — Update policy
- `DELETE /api/policies/{id}` — Delete policy
  Permanently delete a policy and remove it from all agents. Consider deactivating (PATCH with isActive: false) instead if you want to preserve the policy configuration.
- `GET /api/policies/{id}/rules` — List rules for a policy
- `POST /api/policies/{id}/rules` — Add rules to a policy
  Add one or more rules to a policy. Rules are evaluated using AND logic — all must pass for a payment to be approved.

### Transactions
Transaction history and management

- `GET /api/transactions` — List transactions
  List payment transactions for the organization. Filter by status, agent, or amount. Transaction statuses: PENDING, APPROVED, DENIED, CONFIRMED, FAILED.

### SDK Payments
SDK endpoints for agent payment flow (request, execute, status)

- `POST /api/sdk/payments/request` — Request payment authorization
  Request authorization for a payment from an AI agent. Evaluates all assigned policies and wallet-level spend limits. Returns APPROVED, DENIED, or REQUIRES_APPROVAL.
- `GET /api/sdk/payments/{requestId}` — Get payment request status
  Check the status of a payment request.
- `POST /api/sdk/payments/{requestId}/execute` — Execute approved payment
  Execute a previously approved payment request. The request must have status APPROVED and not be expired. Executes the onchain transaction via Sponge wallet.
- `POST /api/sdk/payments/approve` — Approve an external wallet payment
  Request policy approval for a payment the agent will execute via its own external wallet. Returns an approval token to use when confirming. Requires `payments:approve` scope.
- `POST /api/sdk/payments/{requestId}/confirm` — Confirm external wallet payment execution
  Confirm that an externally approved payment was executed by providing the transaction hash and approval token. Requires `payments:confirm` scope.

### SDK Agent
SDK endpoints for agent self-service

- `GET /api/sdk/all` — Get complete agent data
  Returns everything about the authenticated agent in a single call: profile, wallets, policies, counterparties, transactions, alerts, analytics, and capabilities. Use the `include` query parameter to cherry-pick specific sections.
- `GET /api/sdk/agents/me` — Get agent profile
  Get the authenticated agent profile and summary statistics.
- `GET /api/sdk/setup` — Get agent bootstrap configuration
  Returns comprehensive agent configuration including profile, wallets, policies, counterparties, scopes, available endpoints, and capabilities. Designed for initial SDK bootstrap.

### SDK Wallets
SDK endpoints for agent wallet access

- `GET /api/sdk/wallets` — List agent wallets
  List all wallets assigned to the authenticated agent.
- `GET /api/sdk/wallets/{id}` — Get wallet details

### SDK Transactions
SDK endpoints for agent transaction history

- `GET /api/sdk/transactions` — List agent transactions
- `GET /api/sdk/transactions/{id}` — Get transaction details
- `POST /api/sdk/transactions/{id}/retry` — Retry a failed transaction
  Queue a failed transaction for retry. Only transactions with FAILED status can be retried. Requires `transactions:write` scope.

### SDK Policies
SDK endpoints for agent policy inspection

- `GET /api/sdk/policies` — List agent policies
  List policies that govern the authenticated agent, with effective limits.
- `GET /api/sdk/policies/exceptions` — List policy exception requests
  List policy exception requests submitted by this agent. Requires `policies:exceptions` scope.
- `POST /api/sdk/policies/exceptions` — Request a policy exception
  Submit a request for a policy exception (e.g., whitelist a counterparty, increase spend limit). Requires `policies:exceptions` scope.

### Counterparties
Counterparty management and trust

- `GET /api/counterparties` — List counterparties
  List counterparties (payment recipients) with their trust levels and transaction history. Trust levels: TRUSTED, VERIFIED, UNKNOWN, BLOCKED.
- `POST /api/counterparties` — Create a counterparty

### API Keys
Organization API key management

- `GET /api/api-keys` — List organization API keys
- `POST /api/api-keys` — Create organization API key
  Create an org-level API key with scoped permissions. The full key is returned only once.

### Alerts
Alert management

- `GET /api/alerts` — List alerts
  List alerts and notifications for the organization. Alert types include: SPEND_LIMIT_WARNING, SPEND_LIMIT_EXCEEDED, UNUSUAL_ACTIVITY, FAILED_TRANSACTION, POLICY_VIOLATION, NEW_COUNTERPARTY, HIGH_VALUE_TRANSACTION, AGENT_SUSPENDED, WALLET_LOW_BALANCE, BLOCKED_ADDRESS. Severities: INFO, WARNING, CRITICAL.

### x402
x402 protocol pre-authorization, recording, and analytics

- `POST /api/sdk/x402/pre-authorize` — Pre-authorize an x402 payment
  Check policy approval before signing an x402 payment.
- `POST /api/sdk/x402/record` — Record x402 payment(s)
  Record a single x402 payment or a batch of micropayments.
- `GET /api/sdk/x402/services` — List x402 services used by agent
- `GET /api/sdk/x402/budget` — Check x402 budget remaining
  Get x402 budget remaining, burn rate, and projections.

### mpp
Machine Payment Protocol pre-authorization, recording, and analytics

- `POST /api/sdk/mpp/pre-authorize` — Pre-authorize an MPP payment
  Check policy approval before creating an MPP credential. The agent sends the WWW-Authenticate: Payment challenge contents and Conto evaluates policies without executing anything.
- `POST /api/sdk/mpp/record` — Record MPP payment(s)
  Record a single MPP payment or a batch of micropayments. Used by agents that handle MPP payments directly and want to report them to Conto for spend tracking and policy enforcement.
- `GET /api/sdk/mpp/services` — List MPP services used by agent
  List all MPP services the agent has interacted with, including spend summaries, price trends, and known endpoints.
- `GET /api/sdk/mpp/budget` — Check MPP budget remaining
  Get MPP budget remaining, burn rate, and projections. Includes daily/weekly/monthly spend, policy limits, and hours until budget exhaustion.

### SDK A2A Payments
Agent-to-agent payment requests and resolution

- `POST /api/sdk/a2a/request` — Create an A2A payment request
  Request payment from another Conto agent. The requesting agent is asking the target agent to send them funds. Target can be specified by agent ID or wallet address.
- `GET /api/sdk/a2a/requests` — List A2A payment requests
  List payment requests for the authenticated agent. Filter by direction (incoming/outgoing) and status.
- `GET /api/sdk/a2a/requests/{id}` — Get A2A payment request details
  Get details of a specific A2A payment request, including direction and status.
- `POST /api/sdk/a2a/requests/{id}/execute` — Execute an approved A2A payment request
  Execute a previously approved A2A payment request. The request must be in an approved state.
- `GET /api/sdk/a2a/resolve` — Resolve a wallet address to a Conto agent
  Check if a wallet address belongs to a registered Conto agent. Useful for verifying recipients before sending A2A payment requests.
- `GET /api/sdk/a2a/stats` — Get A2A payment statistics
  Get aggregate A2A payment statistics for the authenticated agent.

### SDK Cards
Card payment approval and confirmation (BYOC flow)

- `POST /api/sdk/cards/approve` — Request card payment approval
  Request policy approval before charging a card (BYOC flow step 1). Evaluates per-transaction limits, daily/weekly/monthly limits, time windows, and merchant restrictions. Requires `payments:approve` scope.
- `POST /api/sdk/cards/{id}/confirm` — Confirm card payment execution
  Confirm that a card payment was charged externally (BYOC flow step 2). Requires the approval token from the approve step. Requires `payments:confirm` scope.

### SDK Counterparties
SDK endpoints for counterparty and network trust management

- `GET /api/sdk/counterparties` — List agent counterparties
  List counterparties the agent has interacted with, including trust levels and transaction history. Requires `counterparties:read` scope.
- `POST /api/sdk/counterparties` — Create a counterparty
  Register a new counterparty (payment recipient). Requires `counterparties:write` scope.
- `GET /api/sdk/counterparties/{id}` — Get counterparty details
  Get detailed counterparty info including trust relationship and recent transactions. Requires `counterparties:read` scope.
- `PATCH /api/sdk/counterparties/{id}` — Update a counterparty
  Update counterparty details. Requires `counterparties:write` scope.
- `GET /api/sdk/network/trust/{address}` — Get network trust for an address
  Look up trust information for any wallet address on the Conto network. Returns entity type, trust scores, relationship history, and any flags. Requires `network:read` scope.

### SDK Alerts & Analytics
SDK endpoints for alerts, analytics, audit logs, approval requests, spending limits, and rate limits

- `GET /api/sdk/alerts` — List agent alerts
  List alerts for the authenticated agent. Requires `alerts:read` scope. Filter by status and severity.
- `GET /api/sdk/alerts/{id}` — Get alert details
  Get details of a specific alert. Requires `alerts:read` scope.
- `PATCH /api/sdk/alerts/{id}` — Acknowledge or resolve an alert
  Update an alert status by acknowledging or resolving it. Requires `alerts:write` scope.
- `GET /api/sdk/analytics` — Get spending analytics
  Get spending analytics for the authenticated agent including volume trends, category breakdowns, and top merchants. Requires `analytics:read` scope.
- `GET /api/sdk/audit-logs` — List audit logs
  Get audit logs of actions performed by or affecting this agent. Requires `audit:read` scope.
- `GET /api/sdk/approval-requests` — List pending approval requests
  List pending approval requests for the agent, including payments awaiting human approval and incoming A2A payment requests.
- `GET /api/sdk/spending-limits` — Get spending limits and usage
  Get per-wallet spending limits and current usage for the authenticated agent. Requires `wallets:read` scope.
- `GET /api/sdk/rate-limits` — Get rate limit status
  Get current rate limit status, usage counts, and per-endpoint rate limits for the authenticated agent.

### Other

- `GET /api/health` — Health check
  Check API health status.

### Safety

- `GET /api/freeze-events` — List organization-wide freeze events
  Paginated list of all freeze and unfreeze events across all agents in the organization.

## Key Concepts Summary

### Registration
POST /api/auth/register — Creates user, organization, and returns a pre-generated org API key.
Required fields: name, email, password, organizationName

### Authentication
- SDK Keys: `conto_agent_xxx...` - For agent payment operations (per-agent, generated via POST /api/agents/{id}/sdk-keys)
- API Keys: `conto_xxx...` - For full platform API access (org-level, generated via POST /api/api-keys)

### Agent Types
OPENAI_ASSISTANT, ANTHROPIC_CLAUDE, LANGCHAIN, AUTOGPT, CUSTOM
Field name: `agentType` (not `type`)

### SDK Scopes
Default: `payments:request`, `payments:execute`
Additional (opt-in): `payments:confirm`, `wallets:read`, `transactions:read`, `transactions:write`, `policies:read`, `policies:exceptions`, `counterparties:read`, `counterparties:write`, `alerts:read`, `alerts:write`, `agents:read`, `analytics:read`, `network:read`, `audit:read`

### Payment Flow
1. Agent calls `payments.request()` with amount, recipient, purpose
2. Conto evaluates all policies (spend limits, time windows, counterparty rules)
3. Returns APPROVED, DENIED, or REQUIRES_APPROVAL
4. If approved, agent calls `payments.execute()` with requestId
5. Transaction is submitted to blockchain and confirmed
6. Alternative: Use `autoExecute: true` in step 1 to request + execute in one call (returns status: "EXECUTED" with txHash)

### Wallet Selection
Wallets are selected by custody priority: PRIVY > SPONGE > SMART_CONTRACT > EXTERNAL. Executable wallets (PRIVY, SPONGE) are preferred. Response includes `walletSelectionReason` and `currency`/`chain` info.

### Custody Providers
- PRIVY (Default): Enterprise-grade key management with policy controls
- SPONGE: Fast setup with gas sponsorship for stablecoins
- EXTERNAL: Externally managed wallet (import address required)
- SMART_CONTRACT: Onchain enforcement (coming soon)

### Wallet Lifecycle
1. Create wallet via POST /api/wallets (default: PRIVY custody, EOA, EVM)
2. Provision wallet via POST /api/wallets/{id}/provision (gets blockchain address)
3. Link wallet to agent via POST /api/agents/{agentId}/wallets (set spend limits)
4. Agent can now request and execute payments

### Policy Types & Rule Types
Policies are created via `POST /api/policies` then rules added via `POST /api/policies/{id}/rules`.
Each rule has: `ruleType`, `operator`, `value` (JSON string), `action` (ALLOW/DENY/REQUIRE_APPROVAL).

- SPEND_LIMIT: Rules: `MAX_AMOUNT`, `DAILY_LIMIT`, `WEEKLY_LIMIT`, `MONTHLY_LIMIT`, `BUDGET_CAP`
- TIME_WINDOW: Rules: `TIME_WINDOW` (BETWEEN operator, HH:MM format), `DAY_OF_WEEK` (IN_LIST), `BLACKOUT_PERIOD`, `DATE_RANGE`
- COUNTERPARTY: Rules: `ALLOWED_COUNTERPARTIES` (IN_LIST, ALLOW), `BLOCKED_COUNTERPARTIES` (IN_LIST, DENY), `TRUST_SCORE`, `COUNTERPARTY_STATUS`
- CATEGORY: Rules: `ALLOWED_CATEGORIES` (IN_LIST, ALLOW), `BLOCKED_CATEGORIES` (IN_LIST, DENY)
- VELOCITY: Rules: `VELOCITY_LIMIT` (value: `{"maxCount": N, "period": "HOUR"}` or `{"maxAmount": N, "period": "DAILY"}`)
- GEOGRAPHIC: Rules: `GEOGRAPHIC_RESTRICTION` (IN_LIST, DENY)
- APPROVAL_THRESHOLD: Rules: `REQUIRE_APPROVAL_ABOVE` (GREATER_THAN, REQUIRE_APPROVAL)
- CONTRACT/DeFi: Rules: `CONTRACT_ALLOWLIST`, `PROTOCOL_ALLOWLIST`

### Multi-Policy AND Logic
All assigned policies must pass. First DENY stops evaluation immediately.
DELETE policy from agent: `DELETE /api/agents/{id}/policies?policyId=xxx` (query param, not path param)

### AgentWallet-Level Limits
Spend limits also exist at wallet level: `spendLimitPerTx`, `spendLimitDaily`, `spendLimitWeekly`, `spendLimitMonthly` (null = unlimited).
Set via `POST /api/agents/{id}/wallets` or `PATCH /api/agents/{id}/wallets/{walletId}`.
Agent wallet endpoints support both session auth and org API key auth.

### Operators
Numeric: EQUALS/EQ, NOT_EQUALS/NEQ, GREATER_THAN/GT, GREATER_THAN_OR_EQUAL/GTE, LESS_THAN/LT, LESS_THAN_OR_EQUAL/LTE
List: IN/IN_LIST, NOT_IN/NOT_IN_LIST
Range: BETWEEN, NOT_BETWEEN

### Violation Types
INSUFFICIENT_BALANCE, PER_TX_LIMIT, DAILY_LIMIT, WEEKLY_LIMIT, MONTHLY_LIMIT, TIME_WINDOW, BLOCKED_COUNTERPARTY, WHITELIST_VIOLATION, CATEGORY_RESTRICTION, VELOCITY_LIMIT, GEOGRAPHIC_RESTRICTION, BUDGET_EXCEEDED, EXPIRED_PERMISSION, CONTRACT_NOT_ALLOWED, BLACKOUT_PERIOD

### Trust Levels
- TRUSTED (0.75-1.0): High confidence, minimal restrictions
- VERIFIED (0.5-0.75): Established relationship
- UNKNOWN (0.2-0.5): Limited history, requires scrutiny
- BLOCKED (0.0-0.2): High risk, transactions blocked

## Quick Code Examples

### Initialize SDK
```typescript
import { Conto } from '@conto/sdk';
const conto = new Conto({ apiKey: process.env.CONTO_API_KEY });
```

### Make a Payment
```typescript
const result = await conto.payments.pay({
  amount: 50.00,
  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
  recipientName: 'OpenAI',
  purpose: 'API credits',
  category: 'AI_SERVICES'
});
console.log('TX Hash:', result.txHash);
```

### Single-Call Payment (autoExecute)
```typescript
const result = await fetch('/api/sdk/payments/request', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 50, recipientAddress: '0x...', purpose: 'API credits', autoExecute: true })
}).then(r => r.json());
// result.status === 'EXECUTED', result.execution.txHash, result.currency, result.chain
```

### Bootstrap Agent (GET /api/sdk/setup)
```typescript
const config = await fetch('/api/sdk/setup', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());
// config.agent, config.wallets, config.policies, config.counterparties, config.scopes, config.capabilities
```

### Create Counterparty (POST /api/sdk/counterparties)
```typescript
// Requires scope: counterparties:write
await fetch('/api/sdk/counterparties', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Vendor', address: '0x...', type: 'VENDOR', category: 'AI_SERVICES' })
}).then(r => r.json());
```

### Request Policy Exception (POST /api/sdk/policies/exceptions)
```typescript
// Requires scope: policies:exceptions
await fetch('/api/sdk/policies/exceptions', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'ADD_TO_WHITELIST', reason: 'Need to pay new vendor', details: { counterpartyAddress: '0x...' } })
}).then(r => r.json());
```

### Two-Step Payment (Request then Execute)
```typescript
// Step 1: Request authorization
const request = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x...',
  purpose: 'Infrastructure costs'
});

// Step 2: Execute if approved
if (request.status === 'APPROVED') {
  const result = await conto.payments.execute(request.requestId);
}
```

### Create Wallet via API
```bash
curl -X POST https://conto.finance/api/wallets \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Operations Wallet",
    "custodyType": "SPONGE",
    "chainType": "EVM",
    "chainId": "42431"
  }'
```

## Support
- Dashboard: https://conto.finance
- Documentation: https://conto.finance/docs
- Email: support@conto.finance