# Conto Documentation

> Conto is a control center for agentic payments 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_finance/sdk


## Documentation Index

### Get Started
- [Overview](https://conto.finance/docs/introduction/overview): Conto is a control center for agentic payments with stablecoins, spending policies, and real-time monitoring
- [Core Concepts](https://conto.finance/docs/introduction/concepts): Learn about agents, wallets, policies, transactions, counterparties, and trust scores in Conto

### Quick Start
- [Quickstart](https://conto.finance/docs/quickstart/setup): Create an account, connect an agent, fund a Tempo Testnet wallet, and make your first policy-checked payment. No real funds required.
- [Agent Sandbox Quickstart](https://conto.finance/docs/quickstart/agent-sandbox): Let an AI agent discover Conto, create a test-mode sandbox without human intervention, inspect its setup, and try a policy-checked payment flow.
- [Connecting Agents via API](https://conto.finance/docs/quickstart/connecting-agents): Integrate your AI agents with Conto using the REST API

### Conto Pay
- [Overview](https://conto.finance/docs/conto-pay/overview): Conto Pay is the hosted payment agent workspace in Conto, with named agent profiles, managed wallets, checkout links, approvals, hosted requests and receipts, and assistant-led payment operations from chat.
- [Using the Assistant](https://conto.finance/docs/conto-pay/assistant-workflow): Operate the hosted Conto Pay agent with natural language prompts for profiles, checkout links, requests, activity inbox review, approvals, receipts, and payment execution.
- [Live Rollout](https://conto.finance/docs/conto-pay/live-rollout): How Conto Pay moves from sandbox to live money through launch evidence, live review, rollout gates, and customer-safe agent guidance.

### Policies
- [Policy Overview](https://conto.finance/docs/policies/overview): Control agent spending with policies
- [Spend Limits](https://conto.finance/docs/policies/spend-limits): Set per-transaction, daily, weekly, and monthly spending caps for AI agents with budget tracking and automatic resets
- [Time Windows](https://conto.finance/docs/policies/time-windows): Restrict agent transactions to business hours, specific days, or block during maintenance windows with blackout periods
- [Counterparty Policies](https://conto.finance/docs/policies/counterparties): Control spending based on recipient trust
- [Advanced Policies](https://conto.finance/docs/policies/advanced): Advanced policy configurations and rule engine

### SDK
- [Installation](https://conto.finance/docs/sdk/installation): Install and configure the Conto SDK
- [Authentication](https://conto.finance/docs/sdk/authentication): Generate and manage SDK keys for agent authentication, choose the right credential type, and set up key rotation
- [Admin SDK](https://conto.finance/docs/sdk/admin): Manage agents, wallets, and policies programmatically with organization API keys
- [Payments](https://conto.finance/docs/sdk/payments): Request payment authorization, execute onchain transactions, and use autoExecute for single-call payments
- [Budget Requests](https://conto.finance/docs/sdk/budget-requests): Let agents request spending budgets with human approval, tracked across all payment types
- [A2A Payments](https://conto.finance/docs/sdk/a2a-payments): Create, list, and execute agent-to-agent payment requests inside the same organization
- [Card Payments](https://conto.finance/docs/sdk/card-payments): Connect, manage, and enforce policies on payment cards for AI agents
- [x402 Payments](https://conto.finance/docs/sdk/x402-payments): Handle HTTP 402 micropayments through the x402 protocol
- [MPP Payments](https://conto.finance/docs/sdk/mpp-payments): Machine Payment Protocol for session-based micropayments on Tempo
- [Machine Spend](https://conto.finance/docs/sdk/machine-spend): Read unified x402 and MPP service-spend analytics for an agent
- [Error Handling](https://conto.finance/docs/sdk/error-handling): Handle payment denials, authentication errors, rate limits, and timeouts with the Conto SDK error system
- [Examples](https://conto.finance/docs/sdk/examples): Integration examples for OpenAI, Claude, LangChain, Python, Express, webhooks, and MCP server configuration
- [Agent Skills (OpenClaw and Hermes)](https://conto.finance/docs/sdk/skills): Install the Conto skill on any OpenClaw or Nous Hermes agent. Enforce spending policies on every payment.

### CLI
- [CLI Quickstart](https://conto.finance/docs/cli/quickstart): Set up an agent with wallet, policies, and SDK key in one command
- [Commands Reference](https://conto.finance/docs/cli/commands): All CLI commands for managing agents, payments, policies, and wallets
- [Policy Management](https://conto.finance/docs/cli/policies): Create, update, and manage spending policies from the command line

### MCP Server
- [MCP Server](https://conto.finance/docs/mcp/overview): Connect Claude and other AI agents to Conto via Model Context Protocol
- [Install MCP Server](https://conto.finance/docs/mcp/install): Add the Conto MCP server to Claude Desktop or Claude Code so the agent can use natural language for wallet and payment operations
- [Tools Reference](https://conto.finance/docs/mcp/tools): Reference for Conto MCP tools

### AI Assistant
- [AI Assistant](https://conto.finance/docs/assistant/overview): Natural language interface for managing agents, wallets, policies, and more
- [Tools Reference](https://conto.finance/docs/assistant/tools): Complete reference of all 82 tools available across the dashboard assistant and hosted Conto Pay workspace

### Integrations
- [Trust & Risk Providers](https://conto.finance/docs/integrations/trust-providers): External trust scoring, reputation, and compliance providers integrated with Conto
- [Notification Channels](https://conto.finance/docs/integrations/notification-channels): Route approval, payment execution, and Conto Pay lifecycle events to email, Slack, Telegram, WhatsApp, and custom webhooks

### Guides
- [Choose Your Integration](https://conto.finance/docs/guides/choose-your-integration): Compare Hermes, OpenClaw, the Conto SDK, x402, and MPP to choose the right integration path for your agent.
- [Developer Tooling](https://conto.finance/docs/guides/developer-tooling): A practical toolbelt for building, testing, and operating Conto agent payment integrations
- [Conto Hybrid Integration](https://conto.finance/docs/guides/conto-hybrid-integration): Use Conto as the spend-management control center while your app keeps execution and settlement.
- [Custody Modes](https://conto.finance/docs/guides/custody-modes): Understand who holds the keys, which payment flow to use, and what Conto can actually enforce
- [Delta Verification Setup](https://conto.finance/docs/guides/delta-setup): Request Delta access from Conto and prepare your organization for onboarding and testing
- [Delta Smoke Test](https://conto.finance/docs/guides/delta-smoke-test): Run the pilot Delta verification flow end to end after Conto activates Delta for your organization
- [Testing Payments Safely](https://conto.finance/docs/guides/testing-payments): Validate your integration on testnet, simulate policy outcomes, and test edge cases without risking real funds
- [Securing Agents with Policies](https://conto.finance/docs/guides/securing-agents): Production-ready policy configurations for spending limits, time controls, counterparty rules, and alerts
- [Approval Workflows for Agent Payments](https://conto.finance/docs/guides/approval-workflows): Configure multi-step approval workflows, escalation paths, and external approval channels for high-risk agent payments.
- [External Approval Channels](https://conto.finance/docs/guides/external-approvals): Set up email, Slack, Telegram, and WhatsApp approval flows so your team can approve payments without logging into Conto
- [Trust Scoring and Counterparty Controls](https://conto.finance/docs/guides/trust-scoring): Learn how Conto calculates trust scores, enriches counterparties with network intelligence and Fairscale, and turns trust into policy controls.
- [Paying for APIs with x402](https://conto.finance/docs/guides/x402-api-payments): End-to-end walkthrough: handle HTTP 402 responses, pre-authorize through Conto, and track API spending
- [MPP Session Payments](https://conto.finance/docs/guides/mpp-session-payments): End-to-end walkthrough: open a session, make incremental charges, settle, and track spending with MPP
- [Card Management](https://conto.finance/docs/guides/card-management): Connect and manage payment cards for AI agents in the Conto dashboard
- [Testing Spending Policies](https://conto.finance/docs/guides/policy-testing): End-to-end walkthrough: connect an agent, configure policies, and verify they enforce correctly
- [Architecture Patterns](https://conto.finance/docs/guides/architecture-patterns): Reference diagrams for Conto payment flows, approval workflows, trust scoring, x402, and MPP integrations.
- [Webhooks](https://conto.finance/docs/guides/webhooks): Receive real-time notifications for payment events, A2A payment requests, service spend records, and agent freeze events
- [Auto-Freeze](https://conto.finance/docs/guides/auto-freeze): Automatically suspend agents when behavioral anomalies are detected
- [Audit Logs](https://conto.finance/docs/guides/audit-logs): Tamper-evident audit trail for all actions in your organization
- [Roles & Permissions](https://conto.finance/docs/guides/roles-permissions): Organization roles and what each role can access
- [Rate Limits](https://conto.finance/docs/guides/rate-limits): API rate limits, response headers, and retry strategies
- [Recipes](https://conto.finance/docs/guides/recipes): Copy-paste recipes for the SDK, OpenClaw, Hermes, x402, MPP, approvals, and trust scoring

### API Reference
- [API Reference](https://conto.finance/docs/api/reference): OpenAPI and REST reference for the Conto platform and SDK endpoints

### Reference
- [Defaults](https://conto.finance/docs/reference/defaults): Single source of truth for every default value applied by the Conto API, SDK, and CLI

### Changelog
- [Changelog](https://conto.finance/docs/changelog/overview): Product updates from Conto

## 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.
- [Conto Monthly Update](https://conto.finance/blog/monthly-update-2026-05): A roundup of what shipped at Conto this month: a refreshed brand, the Enchant beta, Stripe Sessions, and improvements across policy, identity, wallets, billing, and developer docs.
- [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.
- [The Timeline for Agentic Payments](https://conto.finance/blog/timeline-for-agentic-payments): When will agentic payments become real? Adoption happens in phases. Here's my timeline: micropayments between agents and services today, local commerce in a year, and enterprise payments in two to three.
- [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.

### Agent Onboarding
Agent-forward signup flows, including anonymous test-mode sandboxes and organization-token self-registration

- `GET /api/agents/sandbox` — Describe anonymous agent sandbox signup
  Returns machine-readable defaults for creating an anonymous Conto test-mode sandbox without a human email verification step. Returned credentials expire after 7 days.
- `POST /api/agents/sandbox` — Create an anonymous agent sandbox
  Stripe-style agent onboarding: creates a test-mode organization, owner placeholder, agent, external testnet wallet, SDK key, and sandbox read-only organization API key. No human intervention is required. Returned keys are shown once and expire after 7 days. Sandbox payments execute in simulated mode: request then execute returns status COMPLETED with simulated true and a placeholder txHash receipt.
- `POST /api/agents/sandbox/claim` — Claim an anonymous sandbox
  Attaches an anonymous sandbox to the signed-in human account. Use the sandbox read-only organization API key returned by POST /api/agents/sandbox as the claim secret.
- `GET /api/agents/register` — Describe organization-token agent registration
  Returns public metadata for org-scoped agent self-registration. With a token query parameter, validates the registration token and returns available agent capacity.
- `POST /api/agents/register` — Register an agent into an existing organization
  Lets an agent join an existing organization using a human-generated registration token. This path issues a least-privilege SDK key scoped to payments:request.

### 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. Requests made with org API keys should include `ownerMembershipId`; browser-session requests can default to the current member.
- `POST /api/agents/remediation` — Run bulk identity remediation for agents
  Assign owners or backfill safe identity fields like missing agent IDs and purposes based on existing descriptions.
- `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. Request body supports `name`, optional `expiresInDays`, and optional `keyType`. Standard keys cover the payment lifecycle (request, execute, approve, confirm) plus read scopes; admin keys add delegated organization-management scopes for agents, wallets, and policies.
- `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 spend governance first, then optionally performs an AgentScore identity gate before settlement. Returns APPROVED, DENIED, REQUIRES_APPROVAL, or VERIFICATION_REQUIRED.
- `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. Keys always expire: `expiresInDays` defaults to 365 and is capped at 365.

### 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.

### Merchant Gates
Hosted merchant acceptance gates plus SDK CRUD for configuring AgentScore-gated purchase endpoints

- `GET /api/sdk/merchant-gates` — List merchant gates
  List hosted merchant acceptance gates configured for the authenticated agent organization.
- `POST /api/sdk/merchant-gates` — Create a merchant gate
  Create a conto-hosted AgentScore merchant acceptance gate for the authenticated organization.
- `GET /api/sdk/merchant-gates/{id}` — Get merchant gate details
- `PATCH /api/sdk/merchant-gates/{id}` — Update a merchant gate
- `DELETE /api/sdk/merchant-gates/{id}` — Delete a merchant gate
- `POST /api/merchant/{gateId}/purchase` — Purchase through a hosted merchant gate
  Run AgentScore compliance plus Conto spend governance, then settle the payment into the merchant settlement wallet.

### 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
- Agent sandbox: POST /api/agents/sandbox — Creates a test-mode organization, agent, external testnet wallet, SDK key, and sandbox API key without human email verification. Returned keys are shown once and expire after 7 days.
- Agent sandbox quickstart: https://conto.finance/docs/quickstart/agent-sandbox — Copy-paste discovery, signup, setup, approval, confirmation, and human claim flow for autonomous agents.
- Existing organization: POST /api/agents/register — Registers an agent with a human-generated organization registration token and returns a least-privilege SDK key.
- Human account: POST /api/auth/register — Creates a user and organization, then requires email verification before privileged credentials are issued.

### 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
Standard SDK keys: `payments:request`, `payments:execute`, `payments:approve`, `payments:confirm`, `wallets:read`, `policies:read`, `transactions:read`, `counterparties:read`, `alerts:read`, `agents:read`, `analytics:read`, `network:read`
Admin SDK keys add opt-in organization-management scopes such as `agents:write`, `wallets:write`, and `policies:write`.
Organization-token agent self-registration is more restrictive and only issues `payments:request`.

### 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_finance/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