Skip to main content

​
SDK Installation

The Conto SDK provides two clients:
  • Conto for agent-scoped payment and read operations
  • ContoAdmin for organization-scoped provisioning and management

​
Installation

npm install @conto_finance/sdk

​
Packages

PackageScopeDescription
@conto_finance/sdk@conto_financeTypeScript SDK for payment operations
@conto_finance/create-conto-agent@conto_financeCLI quickstart tool (npx @conto_finance/create-conto-agent)
@conto_finance/mcp-server@conto_financeMCP 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.
Do not put conto_agent_... into CONTO_ORG_API_KEY, and do not put conto_... into CONTO_API_KEY.

​
Basic Agent Setup

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

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

​
Organization Setup with ContoAdmin

import { ContoAdmin } from '@conto_finance/sdk';

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

​
Configuration Options

OptionTypeDefaultDescription
apiKeystringRequiredYour agent’s SDK API key
baseUrlstringhttps://conto.financeAPI base URL
timeoutnumber30000Request timeout in milliseconds
The SDK automatically retries transient failures (429 rate limits, 5xx server errors) with exponential backoff. See Retry Strategy for the exact behavior.

​
Full Configuration Example

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

​
Environment Variables

We recommend using environment variables for configuration:
.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: 
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

// lib/conto.ts
import { Conto } from '@conto_finance/sdk';

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

​
Express

// 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)

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: 
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

Authentication

Learn about SDK authentication

Admin SDK

Provision agents and wallets with org API keys

Payments

Make your first payment