Admin SDK

The Admin SDK lets you programmatically create agents, provision wallets, and configure spending policies. It uses organization API keys (conto_xxx...) which operate at the org level, separate from the agent SDK keys used for payments.

import { ContoAdmin } from '@conto/sdk';

const admin = new ContoAdmin({
  orgApiKey: process.env.CONTO_ORG_API_KEY!,
});

// Create a policy, create an agent, wire them together
const policy = await admin.policies.create({
  name: 'Daily $500 limit',
  policyType: 'SPEND_LIMIT',
  rules: [{ ruleType: 'DAILY_LIMIT', operator: 'LTE', value: '500' }],
});

const agent = await admin.agents.create({
  name: 'billing-agent',
  agentType: 'CUSTOM',
});

await admin.agents.assignPolicy(agent.id, policy.id);

Organization API Keys

Organization API keys authenticate at the org level and can manage all agents, wallets, and policies in the organization. They are different from agent SDK keys.

	Org API Key	Agent SDK Key
Format	`conto_xxx...`	`conto_agent_xxx...`
Scope	Entire organization	Single agent
Used for	Admin operations	Payment operations
SDK class	`ContoAdmin`	`Conto`

Creating an Org API Key

Go to Settings

Navigate to Settings > API Keys in the dashboard.

Create Key

Click Create API Key, enter a name, and select a scope preset:

Read Only - View agents, wallets, policies
Standard - Read + write agents, wallets, policies, plus membership lookup for ownership flows
Admin - Full access (Owner only)

Copy the Key

Copy and save the key immediately. It is only shown once.

Scopes

Org API keys use fine-grained scopes that control what the key can access:

Scope	Description
`agents:read`	List and view agents
`agents:write`	Create, update, delete, freeze/unfreeze agents
`wallets:read`	List and view wallets
`wallets:write`	Create, update, delete, provision wallets
`policies:read`	List and view policies and rules
`policies:write`	Create, update, delete policies, manage rules, assign to agents
`transactions:read`	View transaction history
`counterparties:read`	View counterparties
`counterparties:write`	Create and update counterparties
`alerts:read`	View alerts
`alerts:write`	Acknowledge and resolve alerts
`analytics:read`	View spending analytics
`audit:read`	View audit logs
`team:read`	List organization memberships and ownership candidates

Initialization

import { ContoAdmin } from '@conto/sdk';

const admin = new ContoAdmin({
  orgApiKey: process.env.CONTO_ORG_API_KEY!,
  timeout: 30000,  // Optional, 30s default
});

ContoAdmin rejects agent SDK keys (conto_agent_xxx). If you pass one, it throws an error telling you to use the Conto class instead.

admin.agents

Manage the lifecycle of AI agents in your organization.

agents.list()

List agents with optional filters.

const { agents, total } = await admin.agents.list({
  status: 'ACTIVE',
  search: 'billing',
  limit: 20,
  offset: 0,
});

Parameter	Type	Description
`status`	string	Filter by status: ACTIVE, PAUSED, SUSPENDED, REVOKED, FROZEN
`search`	string	Search by name or description
`limit`	number	Results per page (1-100, default 50)
`offset`	number	Pagination offset

agents.create()

Create a new agent.

const { members } = await admin.team.listMembers();
const serviceOwner = members.find((member) => member.user?.email === 'ops@yourcompany.com');

const agent = await admin.agents.create({
  name: 'billing-agent',
  agentType: 'CUSTOM',
  description: 'Handles vendor payments',
  ownerMembershipId: serviceOwner?.id,
});

Parameter	Type	Required	Description
`name`	string	Yes	Agent name (1-100 chars)
`agentType`	string	Yes	OPENAI_ASSISTANT, ANTHROPIC_CLAUDE, LANGCHAIN, AUTOGPT, or CUSTOM
`description`	string	No	Description (max 500 chars)
`publicKey`	string	No	Ethereum address (auto-generated if omitted)
`externalId`	string	No	Your own identifier for the agent
`ownerMembershipId`	string	Yes	Organization member owner for programmatic/admin flows. Fetch this from `admin.team.listMembers()` and pass it when creating the agent.

admin.team

List organization memberships for the authenticated organization. This is useful when you need a stable ownerMembershipId to reuse across agent creation and repair flows.

team.listMembers()

const { organizationId, members } = await admin.team.listMembers();

const dedicatedOwner = members.find((member) => member.user?.email === 'ops@yourcompany.com');

if (!dedicatedOwner) {
  throw new Error('No dedicated owner membership found');
}

await admin.agents.create({
  name: 'billing-agent',
  agentType: 'CUSTOM',
  ownerMembershipId: dedicatedOwner.id,
});

This method requires an org API key with the team:read scope or admin.

agents.get()

const agent = await admin.agents.get('agent_id');

agents.update()

await admin.agents.update('agent_id', {
  name: 'Updated Name',
  status: 'PAUSED',
});

agents.delete()

Soft-deletes an agent. Deactivates its SDK keys and wallet/card links.

await admin.agents.delete('agent_id');

agents.freeze() / agents.unfreeze()

Freeze blocks all transactions for an agent. Unfreeze restores them.

await admin.agents.freeze('agent_id', {
  reason: 'Suspicious activity detected',
  freezeWallets: true,
});

await admin.agents.unfreeze('agent_id', {
  reason: 'Investigation complete',
  unfreezeWallets: true,
  resetCounters: true,
});

agents.linkWallet()

Link a wallet to an agent with spending limits.

await admin.agents.linkWallet('agent_id', {
  walletId: 'wallet_id',
  delegationType: 'LIMITED',
  spendLimitPerTx: 100,
  spendLimitDaily: 1000,
  spendLimitWeekly: 5000,
  allowedDays: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
});

Parameter	Type	Default	Description
`walletId`	string	Required	Wallet to link
`delegationType`	string	LIMITED	FULL, LIMITED, VIEW_ONLY, PREAPPROVED, ALLOWLIST
`spendLimitPerTx`	number	100	Max per transaction
`spendLimitDaily`	number	1000	Max per day
`spendLimitWeekly`	number	-	Max per week
`spendLimitMonthly`	number	-	Max per month
`allowedHoursStart`	number	0	Allowed hours start (0-23)
`allowedHoursEnd`	number	24	Allowed hours end (1-24)
`allowedDays`	string[]	Mon-Fri	Allowed days of week

agents.assignPolicy() / agents.unassignPolicy()

await admin.agents.assignPolicy('agent_id', 'policy_id');
await admin.agents.unassignPolicy('agent_id', 'policy_id');

agents.listWallets() / agents.listPolicies()

const { wallets } = await admin.agents.listWallets('agent_id');
const { policies } = await admin.agents.listPolicies('agent_id');

agents.createSdkKey() / agents.listSdkKeys() / agents.revokeSdkKey()

Create agent SDK keys programmatically. The key value is returned only once.

const { key } = await admin.agents.createSdkKey('agent_id', {
  name: 'Production Key',
  keyType: 'standard',
  expiresInDays: 90,
});

console.log('Save this key:', key); // conto_agent_xxx...

const keys = await admin.agents.listSdkKeys('agent_id');
await admin.agents.revokeSdkKey('agent_id', 'key_id');

admin.wallets

Manage wallets across the organization.

wallets.list()

const { wallets, total } = await admin.wallets.list({
  chainType: 'EVM',
  status: 'ACTIVE',
  limit: 20,
});

Parameter	Type	Description
`status`	string	ACTIVE, FROZEN, ARCHIVED
`chainType`	string	EVM or SOLANA
`chainId`	string	Specific chain ID
`limit`	number	Results per page (1-100, default 50)
`offset`	number	Pagination offset

wallets.create()

const wallet = await admin.wallets.create({
  name: 'billing-wallet',
  chainType: 'EVM',
  custodyType: 'SPONGE',
});

Parameter	Type	Default	Description
`name`	string	Required	Wallet name (1-100 chars)
`chainType`	string	EVM	EVM or SOLANA
`chainId`	string	-	Chain ID (defaults to Tempo testnet)
`custodyType`	string	PRIVY	PRIVY, SPONGE, EXTERNAL, SMART_CONTRACT
`walletType`	string	EOA	EOA, SMART_WALLET, MULTISIG
`address`	string	-	Required when attaching an existing wallet instead of minting a new one
`externalWalletId`	string	-	Existing provider wallet ID. Use with `custodyType=PRIVY` to attach an existing Privy wallet
`importAddress`	string	-	Legacy watch-only import path for `EXTERNAL` custody

Attach an existing Privy-backed wallet:

const wallet = await admin.wallets.create({
  name: 'enchant-treasury',
  chainType: 'EVM',
  chainId: '8453',
  custodyType: 'PRIVY',
  externalWalletId: 'privy_wallet_123',
  address: '0x1234...abcd',
});

const wallet = await admin.wallets.create({
  name: 'external-ops-wallet',
  chainType: 'EVM',
  chainId: '8453',
  custodyType: 'EXTERNAL',
  address: '0xabcd...1234',
});

wallets.create() is idempotent within the organization per externalWalletId + chainId or address + chainId, so retrying the same request returns the existing wallet instead of creating a duplicate. This attach flow only works when the referenced wallet is visible to the same Privy app Conto is configured to use for managed execution. If the signer lives in a different Privy app or an external wallet stack, register it as EXTERNAL instead.

wallets.get() / wallets.update() / wallets.delete()

const wallet = await admin.wallets.get('wallet_id');

await admin.wallets.update('wallet_id', {
  name: 'Renamed Wallet',
  status: 'FROZEN',
});

await admin.wallets.delete('wallet_id'); // Fails if linked to agents or if payment history exists

Organization API keys can now manage the full wallet lifecycle through wallets.get(), wallets.update(), and wallets.delete() in addition to wallets.list() and wallets.create().

wallets.provision()

Link a wallet to its custody provider and sync its onchain state.

const result = await admin.wallets.provision('wallet_id');
console.log('Address:', result.wallet.address);
console.log('Balance:', result.wallet.balance, result.wallet.currency);

wallets.refreshBalance()

Fetch the latest balance from the chain.

const result = await admin.wallets.refreshBalance('wallet_id');
console.log('Total:', result.totalBalance);
for (const balance of result.balances) {
  console.log(`${balance.chainName}:`, balance.balance, balance.symbol);
}

admin.policies

Create and manage spending policies and their rules.

policies.list()

const { policies, total } = await admin.policies.list({
  limit: 50,
  offset: 0,
});

policies.create()

Create a policy with optional rules and agent assignments in one call.

const policy = await admin.policies.create({
  name: 'Conservative limits',
  policyType: 'SPEND_LIMIT',
  priority: 50,
  rules: [
    { ruleType: 'MAX_AMOUNT', operator: 'LTE', value: '200' },
    { ruleType: 'DAILY_LIMIT', operator: 'LTE', value: '1000' },
    { ruleType: 'MONTHLY_LIMIT', operator: 'LTE', value: '10000' },
  ],
  agentIds: ['agent_1', 'agent_2'], // Assign immediately
});

Policy Types

Type	Description
`SPEND_LIMIT`	Transaction and periodic spending limits
`APPROVAL_THRESHOLD`	Require human approval above a threshold
`COUNTERPARTY`	Allow/block specific counterparties
`CATEGORY`	Allow/block spending categories
`GEOGRAPHIC`	Country-based restrictions
`TIME_WINDOW`	Time-of-day restrictions
`VELOCITY`	Transaction frequency limits
`WHITELIST`	Allowlist-only recipients
`CONTRACT_ALLOWLIST`	Allowed smart contracts
`BLACKOUT_PERIOD`	Block transactions during specific periods
`BUDGET_ALLOCATION`	Budget cap enforcement
`EXPIRATION`	Date-range validity
`COMPOSITE`	Combine multiple rule types
`MERCHANT`	Merchant category restrictions

policies.get() / policies.update() / policies.delete()

const policy = await admin.policies.get('policy_id');

await admin.policies.update('policy_id', {
  name: 'Updated name',
  isActive: false,
  priority: 75,
});

await admin.policies.delete('policy_id');

Rule Management

Add, update, and remove individual rules on a policy.

// Add a single rule
await admin.policies.addRule('policy_id', {
  ruleType: 'DAILY_LIMIT',
  operator: 'LTE',
  value: '500',
  action: 'DENY',
});

// Add multiple rules at once
await admin.policies.addRules('policy_id', [
  { ruleType: 'MAX_AMOUNT', operator: 'LTE', value: '100' },
  { ruleType: 'WEEKLY_LIMIT', operator: 'LTE', value: '2000' },
]);

// Update a rule
await admin.policies.updateRule('policy_id', 'rule_id', {
  value: '750',
});

// Delete a rule
await admin.policies.deleteRule('policy_id', 'rule_id');

// Delete all rules
await admin.policies.deleteAllRules('policy_id');

Rule Operators

Operator	Description
`EQUALS`	Exact match
`NOT_EQUALS`	Not equal
`GREATER_THAN`	Greater than
`LESS_THAN`	Less than
`GTE`	Greater than or equal
`LTE`	Less than or equal
`IN` / `IN_LIST`	Value is in list
`NOT_IN` / `NOT_IN_LIST`	Value is not in list
`BETWEEN`	Value is between two bounds
`NOT_BETWEEN`	Value is outside bounds
`DENY`	Always deny

Rule Actions

Action	Description
`ALLOW`	Allow if condition met (default)
`DENY`	Block if condition met
`REQUIRE_APPROVAL`	Require human approval if condition met

Complete Example

Provision a new agent from scratch:

import { ContoAdmin } from '@conto/sdk';

const admin = new ContoAdmin({
  orgApiKey: process.env.CONTO_ORG_API_KEY!,
});

// 1. Create a wallet
const wallet = await admin.wallets.create({
  name: 'ops-wallet',
  chainType: 'EVM',
  custodyType: 'SPONGE',
});
await admin.wallets.provision(wallet.id);

// 2. Create a spending policy
const policy = await admin.policies.create({
  name: 'Standard ops limits',
  policyType: 'SPEND_LIMIT',
  rules: [
    { ruleType: 'MAX_AMOUNT', operator: 'LTE', value: '500' },
    { ruleType: 'DAILY_LIMIT', operator: 'LTE', value: '2000' },
  ],
});

// 3. Create the agent
const agent = await admin.agents.create({
  name: 'ops-agent',
  agentType: 'CUSTOM',
  description: 'Handles operational payments',
});

// 4. Link wallet with per-agent limits
await admin.agents.linkWallet(agent.id, {
  walletId: wallet.id,
  delegationType: 'LIMITED',
  spendLimitPerTx: 500,
  spendLimitDaily: 2000,
});

// 5. Assign the policy
await admin.agents.assignPolicy(agent.id, policy.id);

// 6. Generate an SDK key for the agent
const { key } = await admin.agents.createSdkKey(agent.id, {
  name: 'Production',
  expiresInDays: 90,
});

console.log('Agent ready. SDK key:', key);

Security

Org keys are powerful. Treat them accordingly.

Org API keys can manage all agents and wallets in the organization. Store them in a secrets manager (AWS Secrets Manager, Vault, etc.), never in source control. Use the minimum scope needed for the task.

Use scoped keys for CI/CD

Create keys with only the scopes your pipeline needs. A deployment script that provisions agents only needs agents:write, wallets:write, and policies:write.

Rotate keys regularly

Set expiration when creating keys. When rotating:

Create a new key
Update your secrets
Deploy
Revoke the old key

All actions are audit-logged

Every operation made with an org API key is recorded in the audit log with actor type API_KEY and the key ID. Review audit logs in the dashboard under Audit Logs.

Limitations

Org API keys cannot change billing plans. Billing changes require dashboard session auth with an Owner account.

Error Handling

try {
  await admin.agents.create({ name: 'test', agentType: 'CUSTOM' });
} catch (error) {
  console.error(error.code, error.status, error.message);
}

Error Code	Status	Description
`AUTH_FAILED`	401	Invalid or revoked API key
`INSUFFICIENT_SCOPE`	403	Key lacks required scope
`NOT_FOUND`	404	Resource not found
`VALIDATION_FAILED`	400	Invalid request body
`TIMEOUT`	0	Request timed out

Next Steps

Policies

Learn about the policy engine and all rule types

Authentication

Agent SDK keys and scopes

Payments

Making payments with agent SDK keys

CLI Policies

Manage policies from the command line

Documentation Index

​Admin SDK

​Organization API Keys

​Creating an Org API Key

​Scopes

​Initialization

​admin.agents

​agents.list()

​agents.create()

​admin.team

​team.listMembers()

​agents.get()

​agents.update()

​agents.delete()

​agents.freeze() / agents.unfreeze()

​agents.linkWallet()

​agents.assignPolicy() / agents.unassignPolicy()

​agents.listWallets() / agents.listPolicies()

​agents.createSdkKey() / agents.listSdkKeys() / agents.revokeSdkKey()

​admin.wallets

​wallets.list()

​wallets.create()

​wallets.get() / wallets.update() / wallets.delete()

​wallets.provision()

​wallets.refreshBalance()

​admin.policies

​policies.list()

​policies.create()

​Policy Types

​policies.get() / policies.update() / policies.delete()

​Rule Management

​Rule Operators

​Rule Actions

​Complete Example

​Security

​Limitations

​Error Handling

​Next Steps

Policies

Authentication

Payments

CLI Policies

Admin SDK

Organization API Keys

Creating an Org API Key

Scopes

Initialization

admin.agents

agents.list()

agents.create()

admin.team

team.listMembers()

agents.get()

agents.update()

agents.delete()

agents.freeze() / agents.unfreeze()

agents.linkWallet()

agents.assignPolicy() / agents.unassignPolicy()

agents.listWallets() / agents.listPolicies()

agents.createSdkKey() / agents.listSdkKeys() / agents.revokeSdkKey()

admin.wallets

wallets.list()

wallets.create()

wallets.get() / wallets.update() / wallets.delete()

wallets.provision()

wallets.refreshBalance()

admin.policies

policies.list()

policies.create()

Policy Types

policies.get() / policies.update() / policies.delete()

Rule Management

Rule Operators

Rule Actions

Complete Example

Security

Limitations

Error Handling

Next Steps