Skip to main content

​
SDK Installation

The Conto SDK provides a type-safe interface for AI agents to request and execute payments.

​
Installation

npm install @conto/sdk

​
Packages

PackageScopeDescription
@conto/sdk@contoTypeScript 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)

​
Basic Setup

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

const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY, // conto_agent_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 — up to 3 retries with 1s/2s/4s delays. It also respects Retry-After headers from the server.

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

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

​
TypeScript Support

The SDK is written in TypeScript and includes full type definitions: 
import {
  Conto,
  ContoConfig,
  PaymentRequestInput,
  PaymentRequestResult,
  PaymentExecuteResult,
  ContoError
} from '@conto/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/sdk';

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

​
Express

// app.ts
import express from 'express';
import { Conto } from '@conto/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/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

Test your installation: 
import { Conto } from '@conto/sdk';

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

  // Try a minimal request (will fail with small amount but confirms connectivity)
  const request = await conto.payments.request({
    amount: 0.01,
    recipientAddress: '0x0000000000000000000000000000000000000000',
    purpose: 'SDK verification test'
  });

  console.log('SDK connected successfully!');
  console.log('Request status:', request.status);
}

verifySetup().catch(console.error);

​
Next Steps

Authentication

Learn about SDK authentication

Payments

Make your first payment