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

Packages

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.
Do not put conto_agent_... into CONTO_ORG_API_KEY, and do not put conto_... into CONTO_API_KEY.

Basic Agent Setup

Organization Setup with ContoAdmin

Configuration Options

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 for the exact behavior.

Full Configuration Example

Environment Variables

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

Framework Integration

Next.js

Express

Serverless (AWS Lambda)

Verifying Installation

Verify connectivity with a read-only call. GET /api/sdk/setup returns a customer-facing setup summary without creating any payment record:
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

Learn about SDK authentication

Admin SDK

Provision agents and wallets with org API keys

Payments

Make your first payment