Agents API

Manage AI agent identities and configurations.

Authentication

All endpoints require either:

Session auth (browser login cookie)
Org API key: Authorization: Bearer conto_xxx...

List Agents

curl https://conto.finance/api/agents \
  -H "Authorization: Bearer $CONTO_API_KEY"

Query Parameters

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

Response

{
  "agents": [
    {
      "id": "cmm59z8fj000l49h7bjqza11p",
      "name": "Customer Support Agent",
      "agentType": "ANTHROPIC_CLAUDE",
      "status": "ACTIVE",
      "description": "Handles customer inquiries and refunds",
      "publicKey": "0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Agent

curl https://conto.finance/api/agents/{agentId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "id": "cmm59z8fj000l49h7bjqza11p",
  "name": "Customer Support Agent",
  "agentType": "ANTHROPIC_CLAUDE",
  "status": "ACTIVE",
  "publicKey": "0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1",
  "description": "Handles customer inquiries and refunds",
  "wallets": [...],
  "policies": [...],
  "_count": { "sentTransactions": 156 },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Create Agent

curl -X POST https://conto.finance/api/agents \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "agentType": "CUSTOM",
    "description": "Conducts market research"
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent display name (1-100 chars)
`agentType`	string	Yes	Agent framework type (see below)
`description`	string	No	Agent description (max 500 chars)
`publicKey`	string	No	Ethereum address (`0x...`, 40 hex chars). Auto-generated if omitted.
`externalId`	string	No	External reference ID (e.g. OpenAI assistant ID)
`allowedContexts`	string[]	No	Allowed execution contexts

Agent Types

Type	Description
`OPENAI_ASSISTANT`	OpenAI GPT assistant
`ANTHROPIC_CLAUDE`	Anthropic Claude agent
`LANGCHAIN`	LangChain agent
`AUTOGPT`	AutoGPT agent
`CUSTOM`	Custom/generic agent

Update Agent

curl -X PATCH https://conto.finance/api/agents/{agentId} \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "description": "Updated description",
    "status": "PAUSED"
  }'

Request Body

Field	Type	Description
`name`	string	Agent display name (1-100 chars)
`description`	string	Agent description (max 500 chars)
`status`	string	`ACTIVE`, `PAUSED`, `SUSPENDED`, `REVOKED`

Delete Agent

curl -X DELETE https://conto.finance/api/agents/{agentId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Status Values

Status	Description
`ACTIVE`	Agent can make payments
`PAUSED`	Temporarily disabled
`SUSPENDED`	Suspended pending review
`REVOKED`	Permanently disabled

Bulk Import Agents

curl -X POST https://conto.finance/api/agents/bulk-import \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agents": [
      {
        "name": "GPT-4 Assistant",
        "publicKey": "0x1234567890abcdef1234567890abcdef12345678",
        "agentType": "OPENAI_ASSISTANT",
        "description": "Handles customer support",
        "externalId": "asst_abc123"
      },
      {
        "name": "Claude Agent",
        "publicKey": "0xabcdef1234567890abcdef1234567890abcdef12",
        "agentType": "ANTHROPIC_CLAUDE",
        "description": "Research assistant"
      }
    ],
    "skipExisting": true
  }'

Request Body

Field	Type	Required	Description
`agents`	array	Yes	Array of agent objects (1-100 per request)
`skipExisting`	boolean	No	Skip agents whose `publicKey` already exists (default: `true`)

Agent Object

Field	Type	Required	Description
`name`	string	Yes	Agent display name (max 100 chars)
`publicKey`	string	Yes	EVM address (`0x...`, 40 hex chars)
`agentType`	string	No	`OPENAI_ASSISTANT`, `ANTHROPIC_CLAUDE`, `LANGCHAIN`, `AUTOGPT`, `CUSTOM` (default: `CUSTOM`)
`description`	string	No	Agent description (max 500 chars)
`externalId`	string	No	External reference ID

Link Wallet to Agent

curl -X POST https://conto.finance/api/agents/{agentId}/wallets \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "cmm59z8fj000m49h7bjqza22q",
    "delegationType": "LIMITED",
    "spendLimitPerTx": 100,
    "spendLimitDaily": 1000,
    "allowedHoursStart": 0,
    "allowedHoursEnd": 24,
    "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"]
  }'

Request Body

Field	Type	Required	Default	Description
`walletId`	string	Yes	-	Wallet ID (CUID format)
`delegationType`	string	No	`LIMITED`	`FULL`, `LIMITED`, `VIEW_ONLY`, `PREAPPROVED`, `ALLOWLIST`
`spendLimitPerTx`	number	No	100	Max per transaction
`spendLimitDaily`	number	No	1000	Max per day
`spendLimitWeekly`	number	No	-	Max per week
`spendLimitMonthly`	number	No	-	Max per month
`allowedHoursStart`	number	No	0	Start hour (0-23)
`allowedHoursEnd`	number	No	24	End hour (1-24). 24 = end of day.
`allowedDays`	string[]	No	Mon-Fri	Days the agent can transact

Assign Policy to Agent

curl -X POST https://conto.finance/api/agents/{agentId}/policies \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"policyId": "cmm..."}'

Remove Policy from Agent

The policyId is passed as a query parameter, not a path parameter.

curl -X DELETE "https://conto.finance/api/agents/{agentId}/policies?policyId=cmm..." \
  -H "Authorization: Bearer $CONTO_API_KEY"

SDK Keys

List SDK Keys

curl https://conto.finance/api/agents/{agentId}/sdk-keys \
  -H "Authorization: Bearer $CONTO_API_KEY"

Generate SDK Key

The full API key is only shown once. Store it securely!

curl -X POST https://conto.finance/api/agents/{agentId}/sdk-keys \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "expiresInDays": 90
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable key name
`expiresInDays`	number	No	Expiration in days. Omit for no expiration.

Response

{
  "id": "cmm...",
  "key": "conto_agent_abc123def456...",
  "name": "Production Key",
  "keyPrefix": "conto_agent_abc...",
  "expiresAt": "2024-04-15T00:00:00Z"
}

Revoke SDK Key

curl -X DELETE "https://conto.finance/api/agents/{agentId}/sdk-keys?keyId=cmm..." \
  -H "Authorization: Bearer $CONTO_API_KEY"

Error Responses

Status	Description
400	Invalid request data
401	Authentication failed
403	Missing required scope
404	Agent not found
409	Agent name already exists

API Reference

​Agents API

​Authentication

​List Agents

​Query Parameters

​Response

​Get Agent

​Response

​Create Agent

​Request Body

​Agent Types

​Update Agent

​Request Body

​Delete Agent

​Status Values

​Bulk Import Agents

​Request Body

​Agent Object

​Link Wallet to Agent

​Request Body

​Assign Policy to Agent

​Remove Policy from Agent

​SDK Keys

​List SDK Keys

​Generate SDK Key

​Request Body

​Response

​Revoke SDK Key

​Error Responses

Agents API

Authentication

List Agents

Query Parameters

Response

Get Agent

Response

Create Agent

Request Body

Agent Types

Update Agent

Request Body

Delete Agent

Status Values

Bulk Import Agents

Request Body

Agent Object

Link Wallet to Agent

Request Body

Assign Policy to Agent

Remove Policy from Agent

SDK Keys

List SDK Keys

Generate SDK Key

Request Body

Response

Revoke SDK Key

Error Responses