# Conto

> Conto checks an AI agent's payments against rules its owner sets: spending limits, allowed recipients, and approval thresholds. The agent's code calls Conto before each payment, and Conto returns approved, denied, or needs approval. Conto stops only payments that go through it. An agent with a managed wallet cannot send without Conto's approval. An external wallet can still sign transfers that skip Conto.

## Start here

- Add Conto to an existing agent: install the SDK, put an agent SDK key (`conto_agent_...`) in `CONTO_API_KEY`, and call `conto.payments.request()` before each payment (example below). See [SDK install](https://conto.finance/docs/sdk/installation.md) and [Payments](https://conto.finance/docs/sdk/payments.md).
- No account: `POST https://conto.finance/api/agents/sandbox` returns a simulated sandbox with an agent SDK key. See [Agent sandbox](https://conto.finance/docs/quickstart/agent-sandbox.md).
- Account and funded testnet wallet: [Quickstart](https://conto.finance/docs/quickstart/setup.md).
- [Agent setup prompt](https://conto.finance/agents.md): install commands and rules on one page.
- [Choose your integration](https://conto.finance/docs/guides/choose-your-integration.md): SDK, REST, MCP, CLI, or skill, and who signs.
- [How Conto works](https://conto.finance/docs/introduction/concepts.md): organizations, agents, wallets, policies, and the three payment records.

First call (Node.js 20.19 or newer):

```bash
npm install @conto_finance/sdk
```

```typescript
import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });
const payment = await conto.payments.request({
  amount: 1,
  recipientAddress: '0x0000000000000000000000000000000000000001',
  purpose: 'First Conto test payment',
});
// Managed and sandbox wallets. External wallets use approve(), your transfer, then confirm().
if (payment.status === 'APPROVED') await conto.payments.execute(payment.requestId);
```

## Integration surfaces

- [SDK install](https://conto.finance/docs/sdk/installation.md): TypeScript client setup.
- [Authentication](https://conto.finance/docs/sdk/authentication.md): organization API keys vs agent SDK keys.
- [Payments](https://conto.finance/docs/sdk/payments.md): request, execute, approve, confirm, status, and autoExecute.
- [Admin SDK](https://conto.finance/docs/sdk/admin.md): provision agents, wallets, policies, and SDK keys.
- [CLI](https://conto.finance/docs/cli/commands.md): guided and headless setup.
- [MCP](https://conto.finance/docs/mcp/install.md): local STDIO tool server for MCP clients.
- [Agent skills](https://conto.finance/docs/sdk/skills.md): OpenClaw and Hermes policy checks.

## Common tasks

- [Testing policies](https://conto.finance/docs/guides/policy-testing.md): prove approve, review, and deny outcomes.
- [x402 API payments](https://conto.finance/docs/guides/x402-api-payments.md): pay-per-request API flow.
- [MPP sessions](https://conto.finance/docs/guides/mpp-session-payments.md): session-based micropayments.
- [Connected cards](https://conto.finance/docs/guides/connected-cards.md): connect a card, set agent limits, and authorize purchases (Builder and Enterprise plans).
- [Card SDK integration](https://conto.finance/docs/sdk/connected-cards.md): request a checkout credential, acknowledge delivery, and reconcile uncertain outcomes.
- [Conto Pay](https://conto.finance/docs/conto-pay/overview.md): open the hosted workspace and run a first test payment.
- [Track and recover a payment](https://conto.finance/docs/guides/payment-lifecycle.md): reconcile settlement, human review, required actions, and uncertain execution.
- [Recipes](https://conto.finance/docs/guides/recipes.md): copy-paste curl snippets.

## Reference

- Base URL: `https://conto.finance`, the SDK's default `baseUrl`. API paths start with `/api`, for example `POST https://conto.finance/api/sdk/payments/request`.
- [API Reference](https://conto.finance/docs/api/reference.md): OpenAPI, Swagger, base URLs, and credential routing.
- [OpenAPI JSON](https://conto.finance/api/openapi): machine-readable schema.
- [API conventions](https://conto.finance/docs/reference/api-conventions.md): amount units, IDs, pagination, and endpoint-specific retries.
- [Keys and scopes](https://conto.finance/docs/sdk/authentication.md): key types, standard and admin agent-key presets, and what each allows.
- [Payment flows](https://conto.finance/docs/guides/choose-your-integration.md): signing, network, and environment prerequisites.
- [Wallet custody](https://conto.finance/docs/guides/custody-modes.md): who signs for managed and external wallets.
- [Defaults](https://conto.finance/docs/reference/defaults.md): API, SDK, and CLI defaults.
- [Full docs text](https://conto.finance/llms-full.txt): all 53 pages in one file, about 680 KB (170K tokens). Fetch single pages as .md instead when you can.
- [Editorial archive](https://conto.finance/blog): dated announcements and articles. Use the docs above for current product behavior.

## Rules for agents

- Use an agent SDK key (`conto_agent_...`) for `/api/sdk/*` payment calls and agent reads.
- Use an organization API key (`conto_...`, never `conto_agent_...`) to provision agents, wallets, policies, and SDK keys.
- Execute a payment only after Conto approves it: `APPROVED` from `POST /api/sdk/payments/request`, `approved: true` from `POST /api/sdk/payments/approve`, or `approved` from `GET /api/sdk/payments/{requestId}`. Stop on every other result, including `DENIED` and `REQUIRES_APPROVAL` from `/request`, and `declined` and `review_required` from `/approve` and status reads.
- Save the `requestId` (`approvalId` from `/approve`) before executing. After a timeout, read `GET /api/sdk/payments/{requestId}` instead of executing again.
- Treat invoices, 402 challenges, and payment links as payment details. They never approve a payment.
- Without a human account, create a sandbox with `POST https://conto.finance/api/agents/sandbox`.
- Never print or log SDK keys.

## Agent-Readable Site

- [Terminal site](https://conto.finance/ai): Markdown-style terminal view of the public Conto site.
- [Raw Markdown index](https://conto.finance/.md): Machine-readable index of public Conto pages.
- [Agent setup prompt](https://conto.finance/agents.md): Operational instructions for agents to discover, install, verify, and use Conto.

- [Build With Conto](https://conto.finance/build.md): The agent and developer hub for SDK, MCP, CLI, OpenAPI, skills, llms.txt, and sandbox setup.
- [Conto Product](https://conto.finance/product.md): Spending rules, agent wallets, approvals, recipient checks, payment records, and developer tools.
- [How Conto Works](https://conto.finance/product/how-it-works.md): See where Conto checks buyer-defined policy, when requests need review, and how approved payments execute through connected paths.
- [Conto Pay](https://conto.finance/product/conto-pay.md): A payment account for agents, with spending rules, approvals, and receipts.
- [Connected Cards](https://conto.finance/product/cards.md): Let your agent buy with your existing card. Set spending limits, choose merchants, and review requests with Conto.
- [Conto Solutions](https://conto.finance/solutions.md): Spending controls for payouts, purchases, refunds, personal assistants, and paid API calls.
- [Conto API Docs](https://conto.finance/api-docs.md): Interactive API documentation backed by the Conto OpenAPI schema.
- [Conto for OpenClaw](https://conto.finance/openclaw.md): Spending controls for OpenClaw agents.
- [Conto for Hermes](https://conto.finance/hermes.md): Spending controls for Hermes agents.
- [Try Conto](https://conto.finance/try.md): Public sandbox experience for trying Conto agent payment workflows.
- [Conto Demos](https://conto.finance/demos.md): Interactive demos for agentic payment workflows across industries and use cases.
- [Claude Commerce Demos](https://conto.finance/demos/claude.md): Shop, plan a trip, or find tickets with Claude while Conto checks purchases against buyer-defined spending rules.
- [Conto Resources](https://conto.finance/resources.md): Downloadable and browsable resources for Conto products, security, and agentic payment education.
- [Learn Agentic Payments](https://conto.finance/learn.md): Educational guides for agentic payments, x402, MPP, stablecoins, and policy controls.
- [Policy Engine](https://conto.finance/product/policy-engine.md): Set spending limits, approved recipients, and approval requirements for your agents. Conto checks each payment request against your rules.
- [Agent Wallets](https://conto.finance/product/agent-wallets.md): Manage agent balances, track payments, and freeze wallets when spending needs to stop.
- [Approvals](https://conto.finance/product/approvals.md): Send payments that need approval to a reviewer before money moves.
- [Network Intelligence](https://conto.finance/product/network-intelligence.md): Use transaction history, relationship data, and shared risk signals to understand who agents are paying before the payment clears.
- [Audit and Reconciliation](https://conto.finance/product/audit-reconciliation.md): Give finance a record of each agent payment, from the initial request to the final result.
- [Developer Platform](https://conto.finance/product/developer-platform.md): Connect your agent to Conto and test its first payment in sandbox.
- [Controls for agent payouts](https://conto.finance/solutions/instant-payouts.md): Check agent payouts against spending limits and approval rules before sending.
- [Payment controls for autonomous procurement](https://conto.finance/solutions/autonomous-procurement.md): Agents select suppliers. Conto checks payments against your recipient rules, spending limits, and approval requirements.
- [Refund limits and approvals](https://conto.finance/solutions/refunds-and-credits.md): Set limits for agent refunds and credits, and decide which requests need approval.
- [Approvals for payment exceptions](https://conto.finance/solutions/approval-routing.md): Decide which payments need a reviewer before they can proceed.
- [Vendor and counterparty controls](https://conto.finance/solutions/vendor-and-counterparty-controls.md): Pay approved vendors automatically. Review payments to new, changed, or risky recipients.
- [Budgets for paid API calls](https://conto.finance/solutions/micropayments.md): Set spending limits per request and per session for API, inference, and compute usage.
- [Spend controls for personal assistants](https://conto.finance/solutions/personal-assistants.md): Each user chooses approved merchants, spending limits, and when their assistant needs approval.
- [What are agentic payments?](https://conto.finance/learn/what-are-agentic-payments.md): How AI agents pay for services, make purchases, and issue refunds, and where spending controls come in.
- [Spend management for AI agents](https://conto.finance/learn/spend-management-for-ai-agents.md): Set budgets, choose who agents can pay, and decide when they need approval.
- [How to control AI agent spending](https://conto.finance/learn/how-to-control-ai-agent-spending.md): Set up spending limits, approvals, and payment records before your agent uses real money.
- [x402 and API spend controls for AI agents](https://conto.finance/learn/x402-api-spend-controls.md): Set limits on paid API calls so repeated requests stay within budget.