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

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

Full Configuration Example

const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY,
  baseUrl: 'https://conto.finance',  // or your self-hosted URL
  timeout: 30000  // 30 seconds
});

Environment Variables

We recommend using environment variables for configuration:
.env
CONTO_API_KEY=conto_agent_abc123def456...
CONTO_BASE_URL=https://conto.finance
const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
  baseUrl: process.env.CONTO_BASE_URL,
});

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