Installation

# Installation

> Install and configure the Conto SDK

- Human URL: https://conto.finance/docs/sdk/installation
- Raw Markdown: https://conto.finance/docs/sdk/installation.md
- Terminal view: https://conto.finance/ai/docs/sdk/installation

Documentation group: Build

# SDK Installation

The Conto SDK provides two clients:

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

## Installation

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

```bash yarn
yarn add @conto_finance/sdk@0.1.0
```

```bash pnpm
pnpm add @conto_finance/sdk@0.1.0
```

```bash bun
bun add @conto_finance/sdk@0.1.0
```

## 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 20.19.0+ 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](https://conto.finance/sdk/authentication#choose-the-right-credential).

  Do not put `conto_agent_...` into `CONTO_ORG_API_KEY`, and do not put `conto_...` into
  `CONTO_API_KEY`.

## Basic Agent Setup

```typescript

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

## Organization Setup with `ContoAdmin`

```typescript

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 retries transient failures only for read-only calls and idempotency-protected payment
  authorization. Financial execution and other non-idempotent writes are never retried
  automatically. See [Retry Strategy](https://conto.finance/sdk/error-handling#retry-strategy) for the exact behavior.

### Full Configuration Example

```typescript
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
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

  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
// lib/conto.ts

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

### Express

```typescript
// app.ts

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

// 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 a customer-facing setup
summary without creating any payment record:

```typescript
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:', setup.agent.name);
  console.log('Wallets:', setup.wallets.length);
  console.log('Scopes:', setup.scopes);
}

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

Note:

  Existing integrations can continue using `GET /api/sdk/all` with its optional `include` query. It
  returns requested sections only when the key has their corresponding read scope; capability
  summaries require `wallets:read`. For compatibility, an unavailable requested section contains a
  `Requires ... scope` error object and is also listed in `omittedSections`; unknown `include`
  values are ignored. Customer-useful legacy fields remain available, with provider custody values
  normalized to `MANAGED`, `EXTERNAL`, or `SMART_CONTRACT`. Transaction `policyResult` remains a
  stable uppercase value and `authorizationDecision` provides `approved`, `declined`,
  `review_required`, or `pending`. Alert severity and status retain normalized uppercase values with
  customer-facing labels; raw alert metadata is omitted. New integrations should use `GET
  /api/sdk/setup` and the dedicated list endpoints; `/api/sdk/all` is retained as a deprecated
  compatibility route.

## Next Steps

### Authentication
Link: https://conto.finance/sdk/authentication

    Learn about SDK authentication

### Admin SDK
Link: https://conto.finance/sdk/admin

    Provision agents and wallets with org API keys

### Payments
Link: https://conto.finance/sdk/payments

    Make your first payment