SDK Installation
The Conto SDK provides two clients:Contofor agent-scoped payment and read operationsContoAdminfor 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
UseConto 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.
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
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