Skip to main content

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.

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

​
Choose Your Client First

If your application needs to…Use this clientCredentialEnv var
Request or execute payments as one agentContoAgent SDK key (conto_agent_...)CONTO_API_KEY
Run the MCP server or tool-calling assistant for one agentContoAgent SDK key (conto_agent_...)CONTO_API_KEY
Provision agents, wallets, policies, or memberships from your backendContoAdminOrganization API key (conto_...)CONTO_ORG_API_KEY
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/sdk';

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

​
Organization Setup with ContoAdmin

import { ContoAdmin } from '@conto/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 — 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...
CONTO_ORG_API_KEY=conto_abc123def456...

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

const admin = new ContoAdmin({
  orgApiKey: process.env.CONTO_ORG_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

Admin SDK

Provision agents and wallets with org API keys

Payments

Make your first payment