Install the TypeScript SDK

Requires Node.js 20.19+. Keep SDK keys in your server or agent runtime, never in browser code.

Install

npm install @conto_finance/sdk

pnpm add @conto_finance/sdk

yarn add @conto_finance/sdk

Choose your client

Conto takes an agent SDK key (CONTO_API_KEY) and requests payments. ContoAdmin takes an organization API key (CONTO_ORG_API_KEY) and provisions agents, wallets, and policies. Get keys with the quickstart or see keys and scopes for the key types. Save the key in .env.local and add that file to .gitignore.

import { Conto, ContoAdmin } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });
const admin = new ContoAdmin({ orgApiKey: process.env.CONTO_ORG_API_KEY! });

Create only the client your application needs. ContoAdmin needs an organization API key (conto_...) and rejects admin SDK keys, which are still agent keys (conto_agent_...).

Verify without creating a payment

Save as verify.mjs. Setup uses the same agent key as the SDK and creates no payment record.

import { Conto } from '@conto_finance/sdk';
const conto = new Conto({ apiKey: process.env.CONTO_API_KEY });
const setup = await conto.setup();
console.log('Agent:', setup.agent.name);
console.log('Wallets:', setup.wallets);
console.log('Scopes:', setup.scopes);

node --env-file=.env.local verify.mjs

Check the intended wallet, network, and payment scopes. In a CLI-created project you can also run npx @conto_finance/create-conto-agent doctor. To run the same check in the dashboard, open Developers, select an agent and its wallet, and paste that agent’s SDK key into the connection panel. Check connection reads setup with the pasted key. Inspect payment reads a payment request by its ID. The panel shows HTTP status, latency, scopes, and payment status, and never executes payments. A passing connection check verifies authentication, not that a given payment will pass policy checks.

Setup diagnostics

setup() also returns diagnostics (version conto.setup-diagnostics.v1), a summary of what this key can do now. It can be null when Conto could not compute it, and older servers omit the field, so fall back to the other setup fields.

Field	Meaning
`environment.kind`	`anonymous_sandbox`, `claimed_sandbox`, or `account`
`environment.settlement`	`simulated` in a sandbox. `per_wallet` otherwise, so check each wallet
`status.canRequest`, `status.canExecute`	`yes`, `no`, or `unknown`
`status.ownerActionRequired`	`true` when at least one `error` issue belongs to an owner
`wallets`	Per wallet: execution mode, network, funding, whether limits are set, what it can do
`connectedCards`	Test and live card readiness, reported separately from wallets
`issues`	Each has a stable `code`, a `severity`, an `actor`, a `message`, and next `actions`

Act on each issue by its actor. The agent can resolve an agent issue with credentials it holds, such as starting a sandbox handoff with the sandbox API key for SANDBOX_UNCLAIMED. The agent cannot resolve an owner issue, such as SCOPE_MISSING, where an owner replaces the key. Report it to the owner with its actions: a CLI command, an API call that names the credential it needs, or a dashboard page. Issue codes keep their meaning, and new codes can be added: AGENT_PAUSED, AGENT_FROZEN, AGENT_UNAVAILABLE, SDK_KEY_EXPIRED, SDK_KEY_REVOKED, SCOPE_MISSING, NO_WALLET, WALLET_PAUSED, WALLET_UNAVAILABLE, WALLET_VIEW_ONLY, WALLET_UNFUNDED, MAINNET_REQUIRES_PROD_AGENT, LIVE_PAYMENTS_PAUSED, LIVE_PAYMENTS_UNAVAILABLE, EXTERNAL_SIGNER_REQUIRED, SANDBOX_UNCLAIMED, and SANDBOX_EXPIRED. The SDK exports the SetupDiagnostics, SetupDiagnosticIssue, SetupDiagnosticIssueCode, and SetupDiagnosticAction types. A key that Conto recognizes but will not serve, such as one for a paused agent or an expired or revoked key, gets 401 from GET /api/sdk/setup with the same diagnostics object. setup() throws a ContoError whose optional diagnostics property carries that object. Setup errors for missing scope (403) carry it too. Diagnostics are also available from conto doctor --json and the MCP get_setup tool.

Configuration

Option	Default	Meaning
`apiKey`	Required	Agent SDK key. Must start with `conto_agent_`
`baseUrl`	`https://conto.finance`	API origin. Must use https except for localhost
`timeout`	`30000`	Request timeout in milliseconds

The SDK retries eligible reads and idempotency-protected authorization. Execution is not retried automatically. See retry behavior.

Start building

Make a payment: request, execute, and status contracts.
Track and recover a payment: required actions, uncertainty, and settlement.
Code examples: Express and Lambda handlers, plus OpenAI, Anthropic, and Python HTTP examples.
Provision with the admin SDK: organization-level automation.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Install the TypeScript SDK

Install

Choose your client

Verify without creating a payment

Setup diagnostics

Configuration

Start building

​Install

​Choose your client

​Verify without creating a payment

​Setup diagnostics

​Configuration

​Start building

Install

Choose your client

Verify without creating a payment

Setup diagnostics

Configuration

Start building