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

# Installation

> Install and configure the Conto SDK

# SDK Installation

The Conto SDK provides two clients:

* `Conto` for agent-scoped payment and read operations
* `ContoAdmin` for organization-scoped provisioning and management

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @conto_finance/sdk
  ```

  ```bash yarn theme={null}
  yarn add @conto_finance/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @conto_finance/sdk
  ```

  ```bash bun theme={null}
  bun add @conto_finance/sdk
  ```
</CodeGroup>

## Packages

| Package                             | Scope            | Description                                                   |
| ----------------------------------- | ---------------- | ------------------------------------------------------------- |
| `@conto_finance/sdk`                | `@conto_finance` | TypeScript SDK for payment operations                         |
| `@conto_finance/create-conto-agent` | `@conto_finance` | CLI quickstart tool (`npx @conto_finance/create-conto-agent`) |
| `@conto_finance/mcp-server`         | `@conto_finance` | MCP server for Claude Desktop                                 |

## Requirements

* Node.js 18+ or Bun
* TypeScript 4.7+ (optional but recommended)

## Choose Your Client First

Use `Conto` with an agent SDK key (`conto_agent_...`, stored as `CONTO_API_KEY`) for payment
operations and agent-scoped reads, including the MCP server. Use `ContoAdmin` with an organization
API key (`conto_...`, stored as `CONTO_ORG_API_KEY`) to provision agents, wallets, policies, or
memberships from your backend. For the full credential selection guide, including admin SDK keys,
see [Choose the Right Credential](/sdk/authentication#choose-the-right-credential).

<Warning>
  Do not put `conto_agent_...` into `CONTO_ORG_API_KEY`, and do not put `conto_...` into
  `CONTO_API_KEY`.
</Warning>

## Basic Agent Setup

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

const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!, // conto_agent_xxx...
});
```

## Organization Setup with `ContoAdmin`

```typescript theme={null}
import { ContoAdmin } from '@conto_finance/sdk';

const admin = new ContoAdmin({
  orgApiKey: process.env.CONTO_ORG_API_KEY!, // conto_xxx...
});
```

## Configuration Options

| Option    | Type   | Default                 | Description                     |
| --------- | ------ | ----------------------- | ------------------------------- |
| `apiKey`  | string | Required                | Your agent's SDK API key        |
| `baseUrl` | string | `https://conto.finance` | API base URL                    |
| `timeout` | number | `30000`                 | Request timeout in milliseconds |

<Info>
  The SDK automatically retries transient failures (429 rate limits, 5xx server errors) with
  exponential backoff. See [Retry Strategy](/sdk/error-handling#retry-strategy) for the exact
  behavior.
</Info>

### Full Configuration Example

```typescript theme={null}
const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
  timeout: 30000, // 30 seconds
});
```

## Environment Variables

We recommend using environment variables for configuration:

```bash .env theme={null}
CONTO_API_KEY=conto_agent_abc123def456...
CONTO_ORG_API_KEY=conto_abc123def456...
```

Pass them to the constructors shown above: `apiKey` for `Conto`, `orgApiKey` for `ContoAdmin`.

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

```typescript theme={null}
import {
  Conto,
  ContoConfig,
  PaymentRequestInput,
  PaymentRequestResult,
  PaymentExecuteResult,
  ContoError,
} from '@conto_finance/sdk';

// All types are automatically inferred
const request: PaymentRequestResult = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x...',
});
```

## Framework Integration

### Next.js

```typescript theme={null}
// lib/conto.ts
import { Conto } from '@conto_finance/sdk';

export const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
});
```

### Express

```typescript theme={null}
// app.ts
import express from 'express';
import { Conto } from '@conto_finance/sdk';

const app = express();
const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
});

app.post('/pay', async (req, res) => {
  const result = await conto.payments.pay(req.body);
  res.json(result);
});
```

### Serverless (AWS Lambda)

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

// Initialize outside handler for connection reuse
const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
  timeout: 10000, // Lower timeout for Lambda
});

export const handler = async (event: any) => {
  const result = await conto.payments.pay(JSON.parse(event.body));
  return {
    statusCode: 200,
    body: JSON.stringify(result),
  };
};
```

## Verifying Installation

Verify connectivity with a read-only call. `GET /api/sdk/setup` returns your agent, wallets, and granted scopes without creating any payment record:

```typescript theme={null}
async function verifySetup() {
  const res = await fetch('https://conto.finance/api/sdk/setup', {
    headers: { Authorization: `Bearer ${process.env.CONTO_API_KEY}` },
  });

  if (!res.ok) {
    throw new Error(`Setup check failed: ${res.status}`);
  }

  const setup = await res.json();
  console.log('SDK connected successfully!');
  console.log('Agent status:', setup.agent.status);
  console.log('Wallets:', setup.wallets.length);
  console.log('Scopes:', setup.scopes);
}

verifySetup().catch(console.error);
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/sdk/authentication">
    Learn about SDK authentication
  </Card>

  <Card title="Admin SDK" icon="shield" href="/sdk/admin">
    Provision agents and wallets with org API keys
  </Card>

  <Card title="Payments" icon="credit-card" href="/sdk/payments">
    Make your first payment
  </Card>
</CardGroup>